Sugar.js Utility Library

Common errors

• TypeError: 'someMethod' is not a function

  cause Attempting to use a Sugar.js method on a native object when Sugar.js (or the relevant module/method) has not been loaded or correctly imported.
  fix Ensure `require('sugar')` or the specific module/method (`require('sugar/number')` or `require('sugar/number/round')`) is called before using the method.

• ReferenceError: Sugar is not defined

  cause Trying to access the global `Sugar` object in a Node.js (CommonJS) or ESM environment without explicitly importing it first.
  fix In Node.js CommonJS, use `const Sugar = require('sugar');`. For TypeScript, `import Sugar = require('sugar');`. The `Sugar` object is not globally available by default in these module systems.

• TypeError: Cannot read properties of undefined (reading 'round') (or similar for other modules)

  cause This typically occurs if you try to access a module's methods (e.g., `Sugar.Number.round`) after only importing an individual method or a non-module-specific entry point, or if trying to destructure incorrectly.
  fix If you intend to use a module's full API, ensure you `require('sugar/module_name')`, which will populate the `Sugar` object with that module's methods. For example, `const Sugar = require('sugar/number'); Sugar.Number.round(...)`.

• Date formatting not showing expected language/locale

  cause The required date locale file (`sugar/locales/xx`) has not been loaded, so Sugar defaults to English or a generic format.
  fix Add `require('sugar/locales/your_locale_code')` to your application to load the desired locale as a side effect. For example, `require('sugar/locales/es')` for Spanish.

Warnings

• breaking Upgrading from Sugar.js v1 to v2 introduces significant breaking changes. Refer to the official 'CAUTIONLOG' and use the upgrade helper script for assistance.
  Fix: Consult https://sugarjs.com/upgrading and https://sugarjs.com/CAUTION.md for detailed migration steps and use the provided upgrade helper script.
• gotcha Sugar.js extensively modifies native object prototypes (e.g., `String.prototype`, `Array.prototype`, `Date.prototype`). This can lead to conflicts with other libraries that also modify native prototypes, or unexpected behavior in environments expecting unadulterated natives.
  Fix: Be mindful of library load order. If conflicts occur, consider using Sugar.js's modular imports to only apply specific methods, or wrap native objects before applying Sugar methods if full prototype extension is not desired.
• breaking The `String#namespace` method was removed in v1.3.9 due to conflicts with jQuery and its limited utility. Code relying on this method will break.
  Fix: Refactor code to no longer use `String#namespace`. Consider alternative string manipulation methods or a different library for namespacing if needed.
• gotcha When using Sugar.js from npm in Node.js, polyfills (e.g., for ES6 features) are not automatically included with the main `require('sugar')` entry point. They must be explicitly required.
  Fix: Explicitly `require('sugar/polyfills/es6')` or other specific polyfill modules if you need them to be applied.
• gotcha Date locales are not loaded by default and must be explicitly required as a side effect. Failing to do so will result in default English formatting even if Sugar's date methods are used.
  Fix: Include `require('sugar/locales/your_locale_code')` or `require('sugar/locales')` for all locales at an appropriate point in your application's bootstrap.

Install

• npm install sugar npm
• yarn add sugar yarn
• pnpm add sugar pnpm

Imports

• Sugar
  wrong:

  import Sugar from 'sugar';
  import { Sugar } from 'sugar';

  correct:

  import Sugar = require('sugar');

  Sugar.js is primarily a CommonJS library for Node.js. For TypeScript, use `import = require()` syntax. In plain JavaScript, use `const Sugar = require('sugar');`
• Sugar.Number (module)
  wrong:

  import { Number } from 'sugar';

  correct:

  import Sugar = require('sugar/number');

  To load a specific module like 'number', `require` the module path directly. This populates the returned `Sugar` object with `Number` methods.
• round (individual method)
  wrong:

  import { round } from 'sugar/number';

  correct:

  import round = require('sugar/number/round');

  Individual methods can be required directly and will return their static form for immediate use. This method also extends `Number.prototype.round`.
• Date Locales
  wrong:

  import { ja } from 'sugar/locales';

  correct:

  require('sugar/locales/ja');

  Date locales are loaded as side effects and apply globally to Sugar's date formatting. They are not intended to be imported as objects.
• SugarStatic (type)

  import type { SugarStatic } from 'sugar';

  For TypeScript users, `SugarStatic` provides type definitions for the global or imported `Sugar` object.

Quickstart

This quickstart demonstrates how to import the full Sugar library, a specific module, and an individual method using CommonJS `require` syntax (adapted for TypeScript). It showcases extensions to `Number`, `Array`, and `Date` prototypes, including locale loading, and basic string manipulation.

import Sugar = require('sugar');
import round = require('sugar/number/round');

// Demonstrate Number module extension
const num = 3.14159;
console.log(`Original number: ${num}`);
console.log(`Rounded to 2 decimal places: ${Sugar.Number.round(num, 2)}`);
console.log(`Ceiling: ${Sugar.Number.ceil(num)}`);

// Demonstrate individual method import
const valueToRound = 4.567;
console.log(`Value for direct round import: ${valueToRound}`);
console.log(`Rounded using direct import: ${round(valueToRound)}`);

// Demonstrate Array module extension
const arr = [1, 2, 3, 4, 5];
console.log(`Original array: ${arr}`);
console.log(`Array first element: ${Sugar.Array.first(arr)}`);
console.log(`Array last element: ${Sugar.Array.last(arr)}`);
console.log(`Array shuffled: ${Sugar.Array.shuffle(arr)}`);

// Demonstrate Date module and locale
require('sugar/locales/fr'); // Load French locale as a side effect
const today = new Date(); // Native Date object
console.log(`Today's date (default format): ${today.format()}`); // Sugar extends Date.prototype
console.log(`Today's date (French format): ${today.format('{Weekday}, {Month} {day}, {year}', 'fr')}`);

// Demonstrate chaining with prototype extensions
const originalString = '  hello world  ';
console.log(`Original string: "${originalString}"`);
const chainedResult = originalString.trim().capitalize();
console.log(`Chained string operation: "${chainedResult}"`);