{"id":15843,"library":"sugar","title":"Sugar.js Utility Library","description":"Sugar.js is a comprehensive JavaScript utility library that extends native object prototypes (e.g., String, Number, Array, Date) with additional methods for common operations. It provides functional programming utilities, robust date/time manipulation, and various helper functions. The current stable version is 2.0.6. While it offers polyfills, its primary design philosophy is to augment existing prototypes rather than providing standalone utility functions, which differentiates it from libraries like Lodash or Ramda. Releases appear to be driven by feature enhancements and bug fixes, with a major version bump from v1 to v2 bringing significant changes and requiring a dedicated upgrade path. It supports both browser and Node.js environments and ships with TypeScript type definitions.","status":"active","version":"2.0.6","language":"javascript","source_language":"en","source_url":"https://github.com/andrewplummer/Sugar","tags":["javascript","sugar","sugarjs","functional","browser","utility","util","date","time","typescript"],"install":[{"cmd":"npm install sugar","lang":"bash","label":"npm"},{"cmd":"yarn add sugar","lang":"bash","label":"yarn"},{"cmd":"pnpm add sugar","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Sugar.js is primarily a CommonJS library for Node.js. For TypeScript, use `import = require()` syntax. In plain JavaScript, use `const Sugar = require('sugar');`","wrong":"import Sugar from 'sugar';\nimport { Sugar } from 'sugar';","symbol":"Sugar","correct":"import Sugar = require('sugar');"},{"note":"To load a specific module like 'number', `require` the module path directly. This populates the returned `Sugar` object with `Number` methods.","wrong":"import { Number } from 'sugar';","symbol":"Sugar.Number (module)","correct":"import Sugar = require('sugar/number');"},{"note":"Individual methods can be required directly and will return their static form for immediate use. This method also extends `Number.prototype.round`.","wrong":"import { round } from 'sugar/number';","symbol":"round (individual method)","correct":"import round = require('sugar/number/round');"},{"note":"Date locales are loaded as side effects and apply globally to Sugar's date formatting. They are not intended to be imported as objects.","wrong":"import { ja } from 'sugar/locales';","symbol":"Date Locales","correct":"require('sugar/locales/ja');"},{"note":"For TypeScript users, `SugarStatic` provides type definitions for the global or imported `Sugar` object.","symbol":"SugarStatic (type)","correct":"import type { SugarStatic } from 'sugar';"}],"quickstart":{"code":"import Sugar = require('sugar');\nimport round = require('sugar/number/round');\n\n// Demonstrate Number module extension\nconst num = 3.14159;\nconsole.log(`Original number: ${num}`);\nconsole.log(`Rounded to 2 decimal places: ${Sugar.Number.round(num, 2)}`);\nconsole.log(`Ceiling: ${Sugar.Number.ceil(num)}`);\n\n// Demonstrate individual method import\nconst valueToRound = 4.567;\nconsole.log(`Value for direct round import: ${valueToRound}`);\nconsole.log(`Rounded using direct import: ${round(valueToRound)}`);\n\n// Demonstrate Array module extension\nconst arr = [1, 2, 3, 4, 5];\nconsole.log(`Original array: ${arr}`);\nconsole.log(`Array first element: ${Sugar.Array.first(arr)}`);\nconsole.log(`Array last element: ${Sugar.Array.last(arr)}`);\nconsole.log(`Array shuffled: ${Sugar.Array.shuffle(arr)}`);\n\n// Demonstrate Date module and locale\nrequire('sugar/locales/fr'); // Load French locale as a side effect\nconst today = new Date(); // Native Date object\nconsole.log(`Today's date (default format): ${today.format()}`); // Sugar extends Date.prototype\nconsole.log(`Today's date (French format): ${today.format('{Weekday}, {Month} {day}, {year}', 'fr')}`);\n\n// Demonstrate chaining with prototype extensions\nconst originalString = '  hello world  ';\nconsole.log(`Original string: \"${originalString}\"`);\nconst chainedResult = originalString.trim().capitalize();\nconsole.log(`Chained string operation: \"${chainedResult}\"`);","lang":"typescript","description":"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."},"warnings":[{"fix":"Consult https://sugarjs.com/upgrading and https://sugarjs.com/CAUTION.md for detailed migration steps and use the provided upgrade helper script.","message":"Upgrading from Sugar.js v1 to v2 introduces significant breaking changes. Refer to the official 'CAUTIONLOG' and use the upgrade helper script for assistance.","severity":"breaking","affected_versions":">=2.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Refactor code to no longer use `String#namespace`. Consider alternative string manipulation methods or a different library for namespacing if needed.","message":"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.","severity":"breaking","affected_versions":">=1.3.9"},{"fix":"Explicitly `require('sugar/polyfills/es6')` or other specific polyfill modules if you need them to be applied.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Include `require('sugar/locales/your_locale_code')` or `require('sugar/locales')` for all locales at an appropriate point in your application's bootstrap.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Ensure `require('sugar')` or the specific module/method (`require('sugar/number')` or `require('sugar/number/round')`) is called before using the method.","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.","error":"TypeError: 'someMethod' is not a function"},{"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.","cause":"Trying to access the global `Sugar` object in a Node.js (CommonJS) or ESM environment without explicitly importing it first.","error":"ReferenceError: Sugar is not defined"},{"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(...)`.","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.","error":"TypeError: Cannot read properties of undefined (reading 'round') (or similar for other modules)"},{"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.","cause":"The required date locale file (`sugar/locales/xx`) has not been loaded, so Sugar defaults to English or a generic format.","error":"Date formatting not showing expected language/locale"}],"ecosystem":"npm"}