{"id":12100,"library":"sugar-core","title":"Sugar.js Core Utilities","description":"Sugar-core is the foundational module for the Sugar.js JavaScript utility library, providing core functionalities and the mechanism to define new methods. Currently at stable version 2.0.6, the package itself was last published 7 years ago, suggesting a maintenance rather than active rapid development cadence for the core package specifically, although the broader Sugar.js project has more recent releases. It serves as a base for all other Sugar.js npm packages and allows plugin developers to extend the library with custom functionalities. A key differentiating factor is its approach to defining methods, specifically `defineInstance`, which expects the instance object as the first argument and explicitly discourages the use of `this` inside the method body (unless creating a polyfill). It also offers specific helpers like `defineInstanceAndStatic` for `Object` methods, as Sugar.js does not directly extend `Object.prototype` in extended mode. The library ships with TypeScript types, facilitating its use in modern TypeScript projects.","status":"maintenance","version":"2.0.6","language":"javascript","source_language":"en","source_url":"https://github.com/andrewplummer/Sugar","tags":["javascript","sugar","sugarjs","functional","browser","utility","util","typescript"],"install":[{"cmd":"npm install sugar-core","lang":"bash","label":"npm"},{"cmd":"yarn add sugar-core","lang":"bash","label":"yarn"},{"cmd":"pnpm add sugar-core","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Since v2.0.0, Sugar.js (and thus sugar-core) primarily uses ES Modules. While transpilation may allow CommonJS, named imports are the intended and most reliable pattern.","wrong":"const { defineInstance } = require('sugar-core');","symbol":"defineInstance","correct":"import { defineInstance } from 'sugar-core';"},{"note":"The `sugar-core` package provides named exports for its utility functions. There is no default export for the module as a whole.","wrong":"import SugarCore from 'sugar-core';","symbol":"SugarCore module object","correct":"import * as SugarCore from 'sugar-core';"},{"note":"For type-only imports in TypeScript, use `import type` to ensure the import is erased at compile time and has no runtime footprint.","symbol":"DefineMethodFunction (type)","correct":"import type { DefineMethodFunction } from 'sugar-core';"}],"quickstart":{"code":"import { defineInstance } from 'sugar-core';\n\n// Demonstrates defining a custom instance method 'pluralize' for strings.\n// This method, when defined, will be available on string instances if\n// the main Sugar.js library is configured in 'extended mode'.\n// The 'defineInstance' method expects the instance (the string itself)\n// as its first argument and discourages using 'this'.\ndefineInstance('pluralize', function(str: string, count: number = 2): string {\n  if (count === 1) {\n    return str;\n  }\n  // Simple pluralization logic for demonstration purposes\n  if (str.endsWith('y') && !str.endsWith('ay') && !str.endsWith('ey') && !str.endsWith('oy')) {\n    return str.slice(0, -1) + 'ies';\n  }\n  return str + 's';\n});\n\n// Example usage (requires Sugar.js extended mode or chainables for full functionality)\nconst singleWord = 'cat';\nconst multipleWord = 'dog';\nconst trickyWord = 'fly';\n\nconsole.log(`'${singleWord}' pluralized:`, (singleWord as any).pluralize(1)); // Expected: 'cat'\nconsole.log(`'${singleWord}' pluralized:`, (singleWord as any).pluralize(2)); // Expected: 'cats'\nconsole.log(`'${multipleWord}' pluralized:`, (multipleWord as any).pluralize()); // Expected: 'dogs'\nconsole.log(`'${trickyWord}' pluralized:`, (trickyWord as any).pluralize()); // Expected: 'flies'\n\n// Note: The 'as any' cast is used here to bypass TypeScript's type checking\n// because 'sugar-core' extends native prototypes at runtime, which TS doesn't\n// inherently know without explicit declaration merging.","lang":"typescript","description":"Demonstrates how to define a custom instance method (`pluralize`) for the String prototype using `defineInstance` and its subsequent use."},"warnings":[{"fix":"Remove any usage of `String#namespace`. Consider alternative string manipulation utilities or custom implementations if this functionality is still required.","message":"The `String#namespace` method was removed in Sugar.js v1.3.9. This was a significant breaking change for applications relying on it, particularly those interacting with jQuery 1.9, which had conflicts with this method.","severity":"breaking","affected_versions":">=1.3.9"},{"fix":"Refactor instance methods to receive the target object as the first argument, e.g., `function(instance, arg1, arg2) { /* ... */ }`.","message":"When using `defineInstance` to add instance methods, the provided function should accept the instance object as its first argument and explicitly avoid using `this` internally. `this` refers to the global scope or `undefined` in strict mode. Only `defineInstancePolyfill` is designed to use the `this` context for polyfilling native methods.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"For object methods, use `defineInstanceAndStatic` to ensure proper availability across static calls and chainables.","message":"Methods intended for `Object` instances must be defined using `defineInstanceAndStatic`. Sugar.js does not directly extend `Object.prototype` in 'extended mode' due to potential conflicts and 'property shadowing' issues, so object methods require both static (on `Sugar.Object`) and instance (for chainables) definitions.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Migrate module imports from CommonJS `require('sugar')` or global `Sugar` references to explicit named ES Module imports, e.g., `import { defineInstance } from 'sugar-core';`.","message":"Sugar.js `v2.0.0` (and by extension `sugar-core` `v2.0.0`) marked a fundamental shift to ES Modules and tree-shaking. Applications upgrading from `v1.x` should expect that direct global `Sugar` object usage and CommonJS `require()` patterns will no longer work as before, necessitating a transition to explicit named ES Module imports.","severity":"breaking","affected_versions":">=2.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure correct ES Module named import: `import { defineStatic } from 'sugar-core';`. If a CommonJS environment *must* be used, verify the bundler configuration or fallback to `const SugarCore = require('sugar-core'); const defineStatic = SugarCore.defineStatic;` if `sugar-core`'s CJS export behavior supports it.","cause":"Attempting to use CommonJS `require()` syntax or an incorrect named import for `defineStatic` (or similar exports) in an ES Module context.","error":"TypeError: (0, _sugarCore.defineStatic) is not a function"},{"fix":"Add a declaration file (`.d.ts`) to your project to extend the native interfaces. For example, `declare module 'sugar-core' { interface String { myCustomMethod(): string; } }` to inform TypeScript about the new method.","cause":"Attempting to call a custom `sugar-core` instance method (e.g., `String#myCustomMethod`) on a native type in a TypeScript project without adequate declaration merging.","error":"Property 'myCustomMethod' does not exist on type 'string'."}],"ecosystem":"npm"}