Sugar.js Core Utilities

Common errors

• TypeError: (0, _sugarCore.defineStatic) is not a function

  cause Attempting to use CommonJS `require()` syntax or an incorrect named import for `defineStatic` (or similar exports) in an ES Module context.
  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.

• Property 'myCustomMethod' does not exist on type 'string'.

  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.
  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.

Warnings

• breaking 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.
  Fix: Remove any usage of `String#namespace`. Consider alternative string manipulation utilities or custom implementations if this functionality is still required.
• gotcha 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.
  Fix: Refactor instance methods to receive the target object as the first argument, e.g., `function(instance, arg1, arg2) { /* ... */ }`.
• gotcha 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.
  Fix: For object methods, use `defineInstanceAndStatic` to ensure proper availability across static calls and chainables.
• breaking 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.
  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';`.

Install

• npm install sugar-core npm
• yarn add sugar-core yarn
• pnpm add sugar-core pnpm

Imports

• defineInstance
  wrong:

  const { defineInstance } = require('sugar-core');

  correct:

  import { defineInstance } from 'sugar-core';

  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.
• SugarCore module object
  wrong:

  import SugarCore from 'sugar-core';

  correct:

  import * as SugarCore from 'sugar-core';

  The `sugar-core` package provides named exports for its utility functions. There is no default export for the module as a whole.
• DefineMethodFunction (type)

  import type { DefineMethodFunction } from 'sugar-core';

  For type-only imports in TypeScript, use `import type` to ensure the import is erased at compile time and has no runtime footprint.

Quickstart

Demonstrates how to define a custom instance method (`pluralize`) for the String prototype using `defineInstance` and its subsequent use.

import { defineInstance } from 'sugar-core';

// Demonstrates defining a custom instance method 'pluralize' for strings.
// This method, when defined, will be available on string instances if
// the main Sugar.js library is configured in 'extended mode'.
// The 'defineInstance' method expects the instance (the string itself)
// as its first argument and discourages using 'this'.
defineInstance('pluralize', function(str: string, count: number = 2): string {
  if (count === 1) {
    return str;
  }
  // Simple pluralization logic for demonstration purposes
  if (str.endsWith('y') && !str.endsWith('ay') && !str.endsWith('ey') && !str.endsWith('oy')) {
    return str.slice(0, -1) + 'ies';
  }
  return str + 's';
});

// Example usage (requires Sugar.js extended mode or chainables for full functionality)
const singleWord = 'cat';
const multipleWord = 'dog';
const trickyWord = 'fly';

console.log(`'${singleWord}' pluralized:`, (singleWord as any).pluralize(1)); // Expected: 'cat'
console.log(`'${singleWord}' pluralized:`, (singleWord as any).pluralize(2)); // Expected: 'cats'
console.log(`'${multipleWord}' pluralized:`, (multipleWord as any).pluralize()); // Expected: 'dogs'
console.log(`'${trickyWord}' pluralized:`, (trickyWord as any).pluralize()); // Expected: 'flies'

// Note: The 'as any' cast is used here to bypass TypeScript's type checking
// because 'sugar-core' extends native prototypes at runtime, which TS doesn't
// inherently know without explicit declaration merging.