@vicin/sigil 2.0.3 → 2.1.0

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 All notable changes to this project will be documented in this file.
 
+## [2.1.0] - 2026-02-22
+
+### Changed
+
+- Changed name of `updateOptions` to be `updateSigilOptions`
+- Updated JSDOCs of multiple APIs
+
 ## [2.0.3] - 2026-02-21
 
 - Patched types
@@ -26,19 +33,19 @@ All notable changes to this project will be documented in this file.
 
 ### Breaking changes
 
-- All `SigilRegistry`options, methods and classes are removed.
+- All `SigilRegistry`options, methods and classes are removed
 
 ## [1.3.0] - 2026-02-18
 
 ### Added
 
-- `isOfType()` & `isOfTypeStrict()` now can be called from instances.
+- `isOfType()` & `isOfTypeStrict()` now can be called from instances
 
 ## [1.2.7] - 2026-02-13
 
 ### Added
 
-- Support for `abstract` classes using `SigilifyAbstract` factory.
+- Support for `abstract` classes using `SigilifyAbstract` factory
 
 ## [1.2.6] - 2026-02-11
 

package/README.md

@@ -156,8 +156,8 @@ Migrating old code into `Sigil` can be done seamlessly with this set-up:
 1. Set `SigilOptions.autofillLabels` to `true` at the start of the app so no errors are thrown in the migration stage:
 
 ```ts
-import { updateOptions } from '@vicin/sigil';
-updateOptions({ autofillLabels: true });
+import { updateSigilOptions } from '@vicin/sigil';
+updateSigilOptions({ autofillLabels: true });
 ```
 
 2. Pass your base class to `Sigilify` mixin:
@@ -384,7 +384,7 @@ class X extends Sigil {
   - `isInheritanceChecked(ctor)`
 
 - **Options:**
-  - `updateOptions(opts)`
+  - `updateSigilOptions(opts)`
   - `DEFAULT_LABEL_REGEX`
 
 - **Types:**
@@ -407,7 +407,7 @@ class X extends Sigil {
 - `withSigilTyped(Class, label?, opts?)`: like `withSigil` but narrows the TypeScript type to include brands.
 - `isSigilCtor(value)`: `true` if `value` is a `Sigil` constructor.
 - `isSigilInstance(value)`: `true` if `value` is an instance of a `Sigil` constructor.
-- `updateOptions(opts)`: change global runtime options before `Sigil` decoration (e.g., `autofillLabels`).
+- `updateSigilOptions(opts)`: change global runtime options before `Sigil` decoration (e.g., `autofillLabels`).
 - `DEFAULT_LABEL_REGEX`: regex that ensures structure of `@scope/package.ClassName` to all labels, it's advised to use it as your `SigilOptions.labelValidation`
 
 ### Instance & static helpers provided by Sigilified constructors
@@ -437,9 +437,9 @@ Instances of sigilified classes expose instance helpers:
 Customize behavior globally at startup:
 
 ```ts
-import { updateOptions } from '@vicin/sigil';
+import { updateSigilOptions } from '@vicin/sigil';
 
-updateOptions({
+updateSigilOptions({
   autofillLabels: false, // Automatically label unlabeled subclasses
   skipLabelInheritanceCheck: false, // Bypass dev inheritance checks -- ALMOST NEVER WANT TO SET THIS TO TRUE, Use 'autofillLabels: true' instead.
   labelValidation: null, // Function or regex, Enforce label format
@@ -452,13 +452,13 @@ Values defined in previous example are defaults, per-class overrides available i
 
 ## Minimal mode
 
-`updateOptions({ autofillLabels: true });` – Enables background operation without explicit labels:
+`updateSigilOptions({ autofillLabels: true });` – Enables background operation without explicit labels:
 
 ```ts
-import { Sigil, updateOptions } from '@vicin/sigil';
+import { Sigil, updateSigilOptions } from '@vicin/sigil';
 
 // run at the start of the app
-updateOptions({ autofillLabels: true });
+updateSigilOptions({ autofillLabels: true });
 
 // No decorators or HOF needed to use 'isOfType' ('instanceof' replacement)
 class A extends Sigil {}

package/dist/index.d.mts

@@ -322,7 +322,7 @@ interface SigilOptions {
  *
  * @param opts - Partial options to merge into the global `OPTIONS` object.
  */
-declare const updateOptions: (opts: SigilOptions) => void;
+declare const updateSigilOptions: (opts: SigilOptions) => void;
 /** -----------------------------------------
  *  Label validation
  * ----------------------------------------- */
@@ -338,17 +338,6 @@ declare const DEFAULT_LABEL_REGEX: RegExp;
 /**
  * Class decorator factory that attaches sigil statics to a class constructor.
  *
- * Usage:
- * ```ts
- * @WithSigil('@myorg/mypkg.MyClass')
- * class MyClass { ... }
- * ```
- *
- * The returned decorator:
- * - validates the provided label (via `verifyLabel`)
- * - performs inheritance checks (via `checkInheritance`) in DEV builds
- * - attaches sigil-related statics to the constructor (via `decorateCtor`)
- *
  * Notes:
  * - This decorator is intended to be applied to classes only. When used
  *   incorrectly (e.g. on a property), it is a no-op.
@@ -366,13 +355,6 @@ declare function WithSigil<L extends string>(label?: L, opts?: SigilOptions): (v
  * HOF (class inhancer) that attaches runtime sigil metadata to Sigil class.
  * Alternative to '@WithSigil' if you prefer HOFs.
  *
- * This does both:
- *  - validate (and autofill) a label,
- *  - perform runtime decoration (via `decorateCtor`),
- *
- * The helper is idempotent: `decorateCtor` will register the label and throw if already
- * decorated; we handle this gracefully in DEV to support HMR flows.
- *
  * @typeParam S - Constructor type (should be an ISigil).
  * @typeParam L - Label literal to attach.
  * @param Class - The constructor (class) to enhance.
@@ -382,15 +364,7 @@ declare function WithSigil<L extends string>(label?: L, opts?: SigilOptions): (v
  */
 declare function withSigil<S extends Function, L extends string = string>(Class: S, label?: L, opts?: SigilOptions): S;
 /**
- * Convenience helper that combine 'withSigil' and 'typeSigil'.
- *
- * This does both:
- *  - validate (and autofill) a label,
- *  - perform runtime decoration (via `decorateCtor`),
- *  - return the constructor typed as `TypedSigil`.
- *
- * The helper is idempotent: `decorateCtor` will register the label and throw if already
- * decorated; we handle this gracefully in DEV to support HMR flows.
+ * Convenience helper that combine 'withSigil' and update 'SigilBrand'.
  *
  * @typeParam S - Constructor type (should be an ISigil).
  * @typeParam L - Label literal to attach.
@@ -405,9 +379,6 @@ declare function withSigilTyped<S extends Function, L extends string = string>(C
 /**
  * Runtime predicate that checks whether the provided value is a sigil constructor.
  *
- * This is a lightweight check that verifies the presence of an internal
- * symbol attached to the constructor.
- *
  * @param ctor - Constructor to test.
  * @returns `true` if `value` is a sigil constructor, otherwise `false`.
  */
@@ -423,8 +394,6 @@ declare function isSigilInstance(inst: unknown): inst is GetInstance<ISigil>;
 /**
  * Check whether the provided constructor was marked as a sigil base constructor.
  *
- * Uses `Object.hasOwn` to ensure we only check own properties.
- *
  * @param ctor - Constructor to check.
  * @returns `true` if `ctor` is a sigil base constructor.
  */
@@ -432,8 +401,6 @@ declare function isSigilBaseCtor(ctor: Function): ctor is ISigil;
 /**
  * Check whether the provided object is an instance of a sigil base constructor.
  *
- * This resolves the instance's constructor and delegates to `isSigilBaseCtor`.
- *
  * @param inst - The instance to test.
  * @returns `true` if `inst` is an instance of a sigil base constructor.
  */
@@ -441,8 +408,6 @@ declare function isSigilBaseInstance(inst: unknown): inst is GetInstance<ISigil>
 /**
  * Returns whether the constructor has been explicitly decorated with `WithSigil`.
  *
- * This is an own-property check and does not traverse the prototype chain.
- *
  * @internal
  * @param ctor - Constructor to test.
  * @returns `true` if the constructor is explicitly decorated.
@@ -451,8 +416,6 @@ declare function isDecorated(ctor: Function): boolean;
 /**
  * Returns whether inheritance checks have already been performed for the constructor.
  *
- * This is used to avoid repeated checks during development (DEV-only checks).
- *
  * @internal
  * @param ctor - Constructor to test.
  * @returns `true` if inheritance checks were marked as completed.
@@ -460,12 +423,7 @@ declare function isDecorated(ctor: Function): boolean;
 declare function isInheritanceChecked(ctor: Function): boolean;
 
 /**
- * Mixin factory that augments an existing class with Sigil runtime metadata and
- * helpers.
- *
- * The returned class:
- * - exposes static helpers such as `SigilLabel`, `SigilType`, `isOfType`, and `isOfTypeStrict`
- * - exposes instance helpers such as `getSigilLabel`, `getSigilType`, etc.
+ * Mixin factory that augments an existing class with Sigil runtime metadata and helpers.
  *
  * @param Base - The base constructor to extend.
  * @param label - Optional identity label to attach to the resulting class (e.g. '@scope/pkg.ClassName').
@@ -587,12 +545,7 @@ declare function Sigilify<B extends Constructor, L extends string>(Base: B, labe
     isOfTypeStrict<T>(this: T, other: unknown): other is GetInstance<T>;
 } & B;
 /**
- * Mixin factory that augments an existing class with Sigil runtime metadata and
- * helpers. Accept and return 'abstract' class.
- *
- * The returned class:
- * - exposes static helpers such as `SigilLabel`, `SigilType`, `isOfType`, and `isOfTypeStrict`
- * - exposes instance helpers such as `getSigilLabel`, `getSigilType`, etc.
+ * Mixin factory that augments an existing class with Sigil runtime metadata and helpers. Accept and return 'abstract' class.
  *
  * @param Base - The base constructor to extend.
  * @param label - Optional identity label to attach to the resulting class (e.g. '@scope/pkg.ClassName').
@@ -721,4 +674,4 @@ declare function SigilifyAbstract<B extends ConstructorAbstract, L extends strin
     isOfTypeStrict<T>(this: T, other: unknown): other is GetInstance<T>;
 }) & B;
 
-export { DEFAULT_LABEL_REGEX, type GetInstance, type ISigil, type ISigilInstance, type ISigilStatic, Sigil, type SigilBrandOf, SigilError, type SigilOptions, Sigilify, SigilifyAbstract, type TypedSigil, type UpdateSigilBrand, WithSigil, isDecorated, isInheritanceChecked, isSigilBaseCtor, isSigilBaseInstance, isSigilCtor, isSigilInstance, updateOptions, withSigil, withSigilTyped };
+export { DEFAULT_LABEL_REGEX, type GetInstance, type ISigil, type ISigilInstance, type ISigilStatic, Sigil, type SigilBrandOf, SigilError, type SigilOptions, Sigilify, SigilifyAbstract, type TypedSigil, type UpdateSigilBrand, WithSigil, isDecorated, isInheritanceChecked, isSigilBaseCtor, isSigilBaseInstance, isSigilCtor, isSigilInstance, updateSigilOptions, withSigil, withSigilTyped };

package/dist/index.d.ts

@@ -322,7 +322,7 @@ interface SigilOptions {
  *
  * @param opts - Partial options to merge into the global `OPTIONS` object.
  */
-declare const updateOptions: (opts: SigilOptions) => void;
+declare const updateSigilOptions: (opts: SigilOptions) => void;
 /** -----------------------------------------
  *  Label validation
  * ----------------------------------------- */
@@ -338,17 +338,6 @@ declare const DEFAULT_LABEL_REGEX: RegExp;
 /**
  * Class decorator factory that attaches sigil statics to a class constructor.
  *
- * Usage:
- * ```ts
- * @WithSigil('@myorg/mypkg.MyClass')
- * class MyClass { ... }
- * ```
- *
- * The returned decorator:
- * - validates the provided label (via `verifyLabel`)
- * - performs inheritance checks (via `checkInheritance`) in DEV builds
- * - attaches sigil-related statics to the constructor (via `decorateCtor`)
- *
  * Notes:
  * - This decorator is intended to be applied to classes only. When used
  *   incorrectly (e.g. on a property), it is a no-op.
@@ -366,13 +355,6 @@ declare function WithSigil<L extends string>(label?: L, opts?: SigilOptions): (v
  * HOF (class inhancer) that attaches runtime sigil metadata to Sigil class.
  * Alternative to '@WithSigil' if you prefer HOFs.
  *
- * This does both:
- *  - validate (and autofill) a label,
- *  - perform runtime decoration (via `decorateCtor`),
- *
- * The helper is idempotent: `decorateCtor` will register the label and throw if already
- * decorated; we handle this gracefully in DEV to support HMR flows.
- *
  * @typeParam S - Constructor type (should be an ISigil).
  * @typeParam L - Label literal to attach.
  * @param Class - The constructor (class) to enhance.
@@ -382,15 +364,7 @@ declare function WithSigil<L extends string>(label?: L, opts?: SigilOptions): (v
  */
 declare function withSigil<S extends Function, L extends string = string>(Class: S, label?: L, opts?: SigilOptions): S;
 /**
- * Convenience helper that combine 'withSigil' and 'typeSigil'.
- *
- * This does both:
- *  - validate (and autofill) a label,
- *  - perform runtime decoration (via `decorateCtor`),
- *  - return the constructor typed as `TypedSigil`.
- *
- * The helper is idempotent: `decorateCtor` will register the label and throw if already
- * decorated; we handle this gracefully in DEV to support HMR flows.
+ * Convenience helper that combine 'withSigil' and update 'SigilBrand'.
  *
  * @typeParam S - Constructor type (should be an ISigil).
  * @typeParam L - Label literal to attach.
@@ -405,9 +379,6 @@ declare function withSigilTyped<S extends Function, L extends string = string>(C
 /**
  * Runtime predicate that checks whether the provided value is a sigil constructor.
  *
- * This is a lightweight check that verifies the presence of an internal
- * symbol attached to the constructor.
- *
  * @param ctor - Constructor to test.
  * @returns `true` if `value` is a sigil constructor, otherwise `false`.
  */
@@ -423,8 +394,6 @@ declare function isSigilInstance(inst: unknown): inst is GetInstance<ISigil>;
 /**
  * Check whether the provided constructor was marked as a sigil base constructor.
  *
- * Uses `Object.hasOwn` to ensure we only check own properties.
- *
  * @param ctor - Constructor to check.
  * @returns `true` if `ctor` is a sigil base constructor.
  */
@@ -432,8 +401,6 @@ declare function isSigilBaseCtor(ctor: Function): ctor is ISigil;
 /**
  * Check whether the provided object is an instance of a sigil base constructor.
  *
- * This resolves the instance's constructor and delegates to `isSigilBaseCtor`.
- *
  * @param inst - The instance to test.
  * @returns `true` if `inst` is an instance of a sigil base constructor.
  */
@@ -441,8 +408,6 @@ declare function isSigilBaseInstance(inst: unknown): inst is GetInstance<ISigil>
 /**
  * Returns whether the constructor has been explicitly decorated with `WithSigil`.
  *
- * This is an own-property check and does not traverse the prototype chain.
- *
  * @internal
  * @param ctor - Constructor to test.
  * @returns `true` if the constructor is explicitly decorated.
@@ -451,8 +416,6 @@ declare function isDecorated(ctor: Function): boolean;
 /**
  * Returns whether inheritance checks have already been performed for the constructor.
  *
- * This is used to avoid repeated checks during development (DEV-only checks).
- *
  * @internal
  * @param ctor - Constructor to test.
  * @returns `true` if inheritance checks were marked as completed.
@@ -460,12 +423,7 @@ declare function isDecorated(ctor: Function): boolean;
 declare function isInheritanceChecked(ctor: Function): boolean;
 
 /**
- * Mixin factory that augments an existing class with Sigil runtime metadata and
- * helpers.
- *
- * The returned class:
- * - exposes static helpers such as `SigilLabel`, `SigilType`, `isOfType`, and `isOfTypeStrict`
- * - exposes instance helpers such as `getSigilLabel`, `getSigilType`, etc.
+ * Mixin factory that augments an existing class with Sigil runtime metadata and helpers.
  *
  * @param Base - The base constructor to extend.
  * @param label - Optional identity label to attach to the resulting class (e.g. '@scope/pkg.ClassName').
@@ -587,12 +545,7 @@ declare function Sigilify<B extends Constructor, L extends string>(Base: B, labe
     isOfTypeStrict<T>(this: T, other: unknown): other is GetInstance<T>;
 } & B;
 /**
- * Mixin factory that augments an existing class with Sigil runtime metadata and
- * helpers. Accept and return 'abstract' class.
- *
- * The returned class:
- * - exposes static helpers such as `SigilLabel`, `SigilType`, `isOfType`, and `isOfTypeStrict`
- * - exposes instance helpers such as `getSigilLabel`, `getSigilType`, etc.
+ * Mixin factory that augments an existing class with Sigil runtime metadata and helpers. Accept and return 'abstract' class.
  *
  * @param Base - The base constructor to extend.
  * @param label - Optional identity label to attach to the resulting class (e.g. '@scope/pkg.ClassName').
@@ -721,4 +674,4 @@ declare function SigilifyAbstract<B extends ConstructorAbstract, L extends strin
     isOfTypeStrict<T>(this: T, other: unknown): other is GetInstance<T>;
 }) & B;
 
-export { DEFAULT_LABEL_REGEX, type GetInstance, type ISigil, type ISigilInstance, type ISigilStatic, Sigil, type SigilBrandOf, SigilError, type SigilOptions, Sigilify, SigilifyAbstract, type TypedSigil, type UpdateSigilBrand, WithSigil, isDecorated, isInheritanceChecked, isSigilBaseCtor, isSigilBaseInstance, isSigilCtor, isSigilInstance, updateOptions, withSigil, withSigilTyped };
+export { DEFAULT_LABEL_REGEX, type GetInstance, type ISigil, type ISigilInstance, type ISigilStatic, Sigil, type SigilBrandOf, SigilError, type SigilOptions, Sigilify, SigilifyAbstract, type TypedSigil, type UpdateSigilBrand, WithSigil, isDecorated, isInheritanceChecked, isSigilBaseCtor, isSigilBaseInstance, isSigilCtor, isSigilInstance, updateSigilOptions, withSigil, withSigilTyped };

package/dist/index.global.js

@@ -11,15 +11,25 @@
     skipLabelInheritanceCheck: false,
     autofillLabels: false
   };
-  var updateOptions = (opts) => {
-    for (const [k, v] of Object.entries(opts)) OPTIONS[k] = v;
-  };
-  var DEFAULT_OPTIONS = {
-    labelValidation: null,
-    skipLabelInheritanceCheck: false,
-    autofillLabels: false
+  var updateSigilOptions = (opts) => {
+    if (opts.autofillLabels) {
+      if (typeof opts.autofillLabels !== "boolean")
+        throw new Error("'updateSigilOptions.autofillLabels' must be boolean");
+      OPTIONS.autofillLabels = opts.autofillLabels;
+    }
+    if (opts.skipLabelInheritanceCheck) {
+      if (typeof opts.skipLabelInheritanceCheck !== "boolean")
+        throw new Error("'updateSigilOptions.skipLabelInheritanceCheck' must be boolean");
+      OPTIONS.skipLabelInheritanceCheck = opts.skipLabelInheritanceCheck;
+    }
+    if (opts.labelValidation) {
+      if (opts.labelValidation !== null && typeof opts.labelValidation !== "function" && !(opts.labelValidation instanceof RegExp))
+        throw new Error(
+          "'updateSigilOptions.labelValidation' must be null, function or regex expression"
+        );
+      OPTIONS.labelValidation = opts.labelValidation;
+    }
   };
-  updateOptions(DEFAULT_OPTIONS);
   var DEFAULT_LABEL_REGEX = /^@[\w-]+(?:\/[\w-]+)*\.[A-Z][A-Za-z0-9]*$/;
 
   // src/core/symbols.ts
@@ -2257,7 +2267,7 @@
     };
   }
 
-  // src/core/enhancers.ts
+  // src/core/hof.ts
   function withSigil(Class, label, opts) {
     var _a;
     if (!isSigilCtor(Class))
@@ -2308,7 +2318,7 @@
   exports.isSigilBaseInstance = isSigilBaseInstance;
   exports.isSigilCtor = isSigilCtor;
   exports.isSigilInstance = isSigilInstance;
-  exports.updateOptions = updateOptions;
+  exports.updateSigilOptions = updateSigilOptions;
   exports.withSigil = withSigil;
   exports.withSigilTyped = withSigilTyped;