@vicin/sigil 3.1.3 → 3.2.0

package/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 All notable changes to this project will be documented in this file.
 
+## [3.2.0] - 2026-02-27
+
+### Added
+
+- `RECOMMENDED_LABEL_REGEX` is the same as `DEFAULT_LABEL_REGEX` but renamed for clarity
+- `getSigilLabels` to get registered sigil labels
+
+### Deprecated
+
+- `DEFAULT_LABEL_REGEX` is deprecated and will be removed in v4, use `RECOMMENDED_LABEL_REGEX` instead
+
+## [3.1.4] - 2026-02-26
+
+### Changed
+
+- Updated description in `package.json`
+
 ## [3.1.3] - 2026-02-26
 
 ### Changed

package/README.md

@@ -16,14 +16,10 @@
 
 - ✅ **Drop-in `instanceof` replacement** that works across bundles, HMR, and monorepos, Also can check for **exact class instance**
 - ✅ **Simple nominal typing** with just one line of code for each class
-- ✅ **Tiny less than 1.5 KB minified and brotlied** measured using [size-limit](https://www.npmjs.com/package/size-limit)
+- ✅ **Tiny less than 1.6 KB minified and brotlied** measured using [size-limit](https://www.npmjs.com/package/size-limit)
 - ✅ **Performant as native instanceof** but with guaranteed checks
 - ✅ **Test coverage is 100%** to ensure that runtime remains consistent and predictable
-
-## Important Notes Before Using
-
-- **Explicit class identity:** `Sigil` uses passed class label to identify classes, which means that the developer is responsible for uniqueness of classes by passing unique labels.
-- **Simple instanceof Fix:** If you just need runtime checks without extras, see the [minimal mode](#minimal-mode).
+- ✅ **Safe with strict rules to ensure uniqueness of labels**, if duplicated label is passed and error is thrown immediately
 
 ---
 
@@ -40,6 +36,7 @@
   - [Purpose and Origins](#purpose-and-origins)
   - [Implementation Mechanics](#implementation-mechanics)
   - [Inheritance example](#inheritance-example)
+  - [Errors & throws](#errors--throws)
 - [API reference](#api-reference)
 - [Options & configuration](#options--configuration)
 - [Minimal mode](#minimal-mode)
@@ -144,7 +141,7 @@ import { Sigil } from '@vicin/sigil';
 class MyBaseClass extends Sigil {} // <-- add 'extends Sigil' here
 ```
 
-Congratulations — you’ve opted into `Sigil` and you can start replacing `instanceof` with `isOfType`, however there is more to add to your system, check [Core concepts](#core-concepts) for more.
+Congratulations — you’ve opted into `Sigil` and you can start replacing `instanceof` with `isOfType()` / `isExactType()`, however there is more to add to your system, check [Core concepts](#core-concepts) for more.
 
 ---
 
@@ -152,7 +149,7 @@ Congratulations — you’ve opted into `Sigil` and you can start replacing `ins
 
 ### Terminology
 
-- **Label**: An identity (string) such as `@scope/pkg.ClassName`, but can be random string (e.g. `@Sigil-auto:ClassName:mm2gkdwn:0:g1sq`) if no label passed.
+- **Label**: An identity (string) such as `@scope/pkg.ClassName`, must be unique for each `Sigil` class otherwise error is thrown.
 - **EffectiveLabel:** A human-readable (string) such as `@scope/pkg.ClassName`, if no label is passed it inherit the last defined label.
 - **isOfType**: Takes object argument and check if this object is an instance of calling class or it's children. Can be called from class instances as well.
 - **isExactType**: Takes object argument and check if this object is an instance of calling class only. Can be called from class instances as well.
@@ -253,6 +250,84 @@ type test1 = Admin extends User ? true : false; // true
 type test2 = User extends Admin ? true : false; // false
 ```
 
+### Errors & throws
+
+Run-time errors that can be thrown by `Sigil`:
+
+#### Double `Sigilify() / SigilifyAbstract()`
+
+```ts
+class A {}
+const B = Sigilify(A, 'A');
+const C = Sigilify(B, 'B'); // Throws: [Sigil Error] Class 'Sigilified' with label 'A' is already sigilified
+
+abstract class AbsA {}
+const AbsB = SigilifyAbstract(AbsA, 'AbsA');
+const AbsC = SigilifyAbstract(AbsB, 'AbsB'); // Throws: [Sigil Error] Class 'Sigilified' with label 'AbsA' is already sigilified
+```
+
+#### `@WithSigil() / withSigil()` on non-Sigil class
+
+```ts
+@WithSigil('A')
+class A {} // Throws: [Sigil Error] 'WithSigil' decorator accept only Sigil classes but used on class 'A'
+
+withSigil(class A {}); // Throws: [Sigil Error] 'WithSigil' decorator accept only Sigil classes but used on class 'A'
+```
+
+#### Double `@WithSigil() / withSigil()`
+
+```ts
+@WithSigil('B')
+@WithSigil('A')
+class A extends Sigil {} // Throws: [Sigil Error] Class 'A' with label 'A' is already sigilified
+
+class _A extends Sigil {}
+withSigil(withSigil(_A, 'A'), 'B'); // Throws: [Sigil Error] Class 'A' with label 'A' is already sigilified
+```
+
+#### No label is passed with `autofillLabels: false`
+
+```ts
+updateSigilOptions({ autofillLabels: false });
+
+class A extends Sigil {}
+new A(); // Throws: [Sigil Error] Class 'A' is not sigilified, Make sure to sigilify all Sigil classes or set 'autofillLabels' to 'true'
+```
+
+#### Same label is passed twice to `Sigil`
+
+```ts
+@WithSigil('Label')
+class A extends Sigil {}
+
+@WithSigil('Label')
+class B extends Sigil {} // Throws: [Sigil Error] Passed label 'Label' to class 'B' is re-used, passed labels must be unique
+```
+
+#### Invalid label format
+
+```ts
+updateSigilOptions({ labelValidation: RECOMMENDED_LABEL_REGEX });
+
+@WithSigil('InvalidLabel')
+class A extends Sigil {} // Throws: [Sigil Error] Invalid Sigil label 'InvalidLabel'. Make sure that supplied label matches validation regex or function
+```
+
+#### Using '@Sigil-auto' prefix
+
+```ts
+@WithSigil('@Sigil-auto:label')
+class X extends Sigil {} // Throws: '@Sigil-auto' is a prefex reserved by the library
+```
+
+#### Invalid options passed to `updateOptions`
+
+```ts
+updateSigilOptions({ autofillLabels: {} as any }); // Throws: 'updateSigilOptions.autofillLabels' must be boolean
+updateSigilOptions({ labelValidation: 123 as any }); // Throws: 'updateSigilOptions.labelValidation' must be null, function or RegExp
+```
+
 ---
 
 ## API reference
@@ -276,10 +351,11 @@ type test2 = User extends Admin ? true : false; // false
 - **Helpers:**
   - `isSigilCtor(ctor)`
   - `isSigilInstance(inst)`
+  - `getSigilLabels(includeAuto?)`
 
 - **Options:**
   - `updateSigilOptions(opts)`
-  - `DEFAULT_LABEL_REGEX`
+  - `RECOMMENDED_LABEL_REGEX`
 
 - **Types:**
   - `ISigil<Label, ParentSigil?>`
@@ -300,8 +376,9 @@ type test2 = User extends Admin ? true : false; // false
 - `withSigil(Class, label, opts?)`: HOF that validates and decorates an existing class constructor.
 - `isSigilCtor(value)`: `true` if `value` is a `Sigil` constructor.
 - `isSigilInstance(value)`: `true` if `value` is an instance of a `Sigil` constructor.
+- `getSigilLabels(includeAuto?)`: Get all `Sigil` labels registered, can include auto-generated labels as well.
 - `updateSigilOptions(opts)`: change global runtime options of `Sigil` library (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`
+- `RECOMMENDED_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
 
@@ -418,7 +495,9 @@ npm run bench
 
 ## Bundle Size
 
-**Less than 1.5 KB (1.44 KB)** minified + Brotli, including all dependencies
+**Less than 1.6 KB (1.51 KB)** (minified + Brotli, including all dependencies)
+
+This makes Sigil one of the smallest full-featured solutions for nominal typing + reliable runtime identity.
 
 **Running Tests**
 
@@ -429,8 +508,6 @@ npm install
 npm run size
 ```
 
-This makes Sigil one of the smallest full-featured solutions for nominal typing + reliable runtime identity.
-
 ---
 
 ## Tests

package/dist/index.d.mts

@@ -218,6 +218,9 @@ declare const SigilError: {
 } & ErrorConstructor;
 type SigilError = InstanceType<typeof SigilError>;
 
+/** -----------------------------------------
+ *  Types
+ * ----------------------------------------- */
 /**
  * Configuration options for the Sigil library.
  *
@@ -240,6 +243,9 @@ interface SigilOptions {
      */
     autofillLabels?: boolean;
 }
+/** -----------------------------------------
+ *  Update options
+ * ----------------------------------------- */
 /**
  * Update runtime options for the Sigil library.
  * Call this early during application startup if you want non-default behavior.
@@ -257,6 +263,8 @@ declare const updateSigilOptions: (opts: SigilOptions) => void;
  *
  * It's advised to use this regex in 'SigilOptions.labelValidation'.
  */
+declare const RECOMMENDED_LABEL_REGEX: RegExp;
+/** @deprecated - Use 'RECOMMENDED_LABEL_REGEX' instead, will be removed in v4 */
 declare const DEFAULT_LABEL_REGEX: RegExp;
 
 /**
@@ -281,7 +289,7 @@ declare function WithSigil(label: string, opts?: SigilOptions): (value: Function
 declare function withSigil<S extends Function>(Class: S, label: string, opts?: SigilOptions): S;
 
 /** -----------------------------------------
- *  Introspection helpers
+ *  Inspection helpers
  * ----------------------------------------- */
 /**
  * Runtime predicate that checks whether the provided value is a sigil constructor.
@@ -298,6 +306,13 @@ declare function isSigilCtor(ctor: unknown): ctor is ISigil;
  * @returns `true` if `obj` is an instance produced by a sigil constructor.
  */
 declare function isSigilInstance(inst: unknown): inst is ISigilInstance;
+/**
+ * Helper function to get labels registered by 'Sigil'
+ *
+ * @param includeAuto - Flag to include auto-generated labels as well, default is 'false'.
+ * @returns Sigil labels registered
+ */
+declare function getSigilLabels(includeAuto?: boolean): string[];
 
 /**
  * Mixin factory that augments an existing class with Sigil runtime metadata and helpers.
@@ -336,7 +351,7 @@ declare function Sigilify<B extends Constructor, L extends string>(Base: B, labe
         /**
          * Returns the identity sigil label of this instance's constructor.
          *
-         * @returns The label string if passed (e.g. '@scope/pkg.ClassName'), random label if not passed (e.g. '@Sigil-auto:ClassName:mm2gkdwn:0:g1sq').
+         * @returns The label string if passed (e.g. '@scope/pkg.ClassName'), random label if not passed (e.g. '@Sigil-auto:ClassName:1:pnf11bgl').
          */
         getSigilLabel(): string;
         /**
@@ -447,7 +462,7 @@ declare function SigilifyAbstract<B extends ConstructorAbstract, L extends strin
     /**
      * Returns the identity sigil label of this instance's constructor.
      *
-     * @returns The label string if passed (e.g. '@scope/pkg.ClassName'), random label if not passed (e.g. '@Sigil-auto:ClassName:mm2gkdwn:0:g1sq').
+     * @returns The label string if passed (e.g. '@scope/pkg.ClassName'), random label if not passed (e.g. '@Sigil-auto:ClassName:1:pnf11bgl').
      */
     getSigilLabel(): string;
     /**
@@ -523,4 +538,4 @@ declare function SigilifyAbstract<B extends ConstructorAbstract, L extends strin
     isExactType<T>(this: T, other: unknown): other is GetPrototype<T>;
 }) & B;
 
-export { DEFAULT_LABEL_REGEX, type ExtendSigil, type GetPrototype, type ISigil, type ISigilInstance, type ISigilStatic, Sigil, SigilError, type SigilOf, type SigilOptions, Sigilify, SigilifyAbstract, WithSigil, isSigilCtor, isSigilInstance, sigil, updateSigilOptions, withSigil };
+export { DEFAULT_LABEL_REGEX, type ExtendSigil, type GetPrototype, type ISigil, type ISigilInstance, type ISigilStatic, RECOMMENDED_LABEL_REGEX, Sigil, SigilError, type SigilOf, type SigilOptions, Sigilify, SigilifyAbstract, WithSigil, getSigilLabels, isSigilCtor, isSigilInstance, sigil, updateSigilOptions, withSigil };

package/dist/index.d.ts

@@ -218,6 +218,9 @@ declare const SigilError: {
 } & ErrorConstructor;
 type SigilError = InstanceType<typeof SigilError>;
 
+/** -----------------------------------------
+ *  Types
+ * ----------------------------------------- */
 /**
  * Configuration options for the Sigil library.
  *
@@ -240,6 +243,9 @@ interface SigilOptions {
      */
     autofillLabels?: boolean;
 }
+/** -----------------------------------------
+ *  Update options
+ * ----------------------------------------- */
 /**
  * Update runtime options for the Sigil library.
  * Call this early during application startup if you want non-default behavior.
@@ -257,6 +263,8 @@ declare const updateSigilOptions: (opts: SigilOptions) => void;
  *
  * It's advised to use this regex in 'SigilOptions.labelValidation'.
  */
+declare const RECOMMENDED_LABEL_REGEX: RegExp;
+/** @deprecated - Use 'RECOMMENDED_LABEL_REGEX' instead, will be removed in v4 */
 declare const DEFAULT_LABEL_REGEX: RegExp;
 
 /**
@@ -281,7 +289,7 @@ declare function WithSigil(label: string, opts?: SigilOptions): (value: Function
 declare function withSigil<S extends Function>(Class: S, label: string, opts?: SigilOptions): S;
 
 /** -----------------------------------------
- *  Introspection helpers
+ *  Inspection helpers
  * ----------------------------------------- */
 /**
  * Runtime predicate that checks whether the provided value is a sigil constructor.
@@ -298,6 +306,13 @@ declare function isSigilCtor(ctor: unknown): ctor is ISigil;
  * @returns `true` if `obj` is an instance produced by a sigil constructor.
  */
 declare function isSigilInstance(inst: unknown): inst is ISigilInstance;
+/**
+ * Helper function to get labels registered by 'Sigil'
+ *
+ * @param includeAuto - Flag to include auto-generated labels as well, default is 'false'.
+ * @returns Sigil labels registered
+ */
+declare function getSigilLabels(includeAuto?: boolean): string[];
 
 /**
  * Mixin factory that augments an existing class with Sigil runtime metadata and helpers.
@@ -336,7 +351,7 @@ declare function Sigilify<B extends Constructor, L extends string>(Base: B, labe
         /**
          * Returns the identity sigil label of this instance's constructor.
          *
-         * @returns The label string if passed (e.g. '@scope/pkg.ClassName'), random label if not passed (e.g. '@Sigil-auto:ClassName:mm2gkdwn:0:g1sq').
+         * @returns The label string if passed (e.g. '@scope/pkg.ClassName'), random label if not passed (e.g. '@Sigil-auto:ClassName:1:pnf11bgl').
          */
         getSigilLabel(): string;
         /**
@@ -447,7 +462,7 @@ declare function SigilifyAbstract<B extends ConstructorAbstract, L extends strin
     /**
      * Returns the identity sigil label of this instance's constructor.
      *
-     * @returns The label string if passed (e.g. '@scope/pkg.ClassName'), random label if not passed (e.g. '@Sigil-auto:ClassName:mm2gkdwn:0:g1sq').
+     * @returns The label string if passed (e.g. '@scope/pkg.ClassName'), random label if not passed (e.g. '@Sigil-auto:ClassName:1:pnf11bgl').
      */
     getSigilLabel(): string;
     /**
@@ -523,4 +538,4 @@ declare function SigilifyAbstract<B extends ConstructorAbstract, L extends strin
     isExactType<T>(this: T, other: unknown): other is GetPrototype<T>;
 }) & B;
 
-export { DEFAULT_LABEL_REGEX, type ExtendSigil, type GetPrototype, type ISigil, type ISigilInstance, type ISigilStatic, Sigil, SigilError, type SigilOf, type SigilOptions, Sigilify, SigilifyAbstract, WithSigil, isSigilCtor, isSigilInstance, sigil, updateSigilOptions, withSigil };
+export { DEFAULT_LABEL_REGEX, type ExtendSigil, type GetPrototype, type ISigil, type ISigilInstance, type ISigilStatic, RECOMMENDED_LABEL_REGEX, Sigil, SigilError, type SigilOf, type SigilOptions, Sigilify, SigilifyAbstract, WithSigil, getSigilLabels, isSigilCtor, isSigilInstance, sigil, updateSigilOptions, withSigil };

package/dist/index.global.js

@@ -19,7 +19,8 @@
       OPTIONS.labelValidation = val != null ? val : null;
     }
   };
-  var DEFAULT_LABEL_REGEX = /^@[\w-]+(?:\/[\w-]+)*\.[A-Z][A-Za-z0-9]*$/;
+  var RECOMMENDED_LABEL_REGEX = /^@[\w-]+(?:\/[\w-]+)*\.[A-Z][A-Za-z0-9]*$/;
+  var DEFAULT_LABEL_REGEX = RECOMMENDED_LABEL_REGEX;
 
   // src/symbols.ts
   var __SIGIL__ = /* @__PURE__ */ Symbol.for("@vicin/sigil.__SIGIL__");
@@ -33,13 +34,8 @@
   function handleSigil(ctor, label, opts) {
     if (handledCtors.has(ctor)) return;
     verifyLabel(ctor, label, opts);
-    const ancLabelsMap = handleAncestors(ctor, opts);
-    if (label && ancLabelsMap.has(label))
-      throw new Error(
-        `[Sigil Error] Attempt to assign label '${label}' to class '${ctor == null ? void 0 : ctor.name}' but label is already used by parent '${ancLabelsMap.get(label)}', Make sure that every class has a unique label`
-      );
+    handleAncestors(ctor, opts);
     sigilify(ctor, label != null ? label : generateRandomLabel(ctor));
-    handledCtors.add(ctor);
   }
   function handleAncestors(ctor, opts) {
     var _a;
@@ -56,13 +52,12 @@
       if (labelOwner.has(l)) {
         if (!autofillLabels)
           throw new Error(
-            `[Sigil Error] Class '${a2.name}' is not sigilified with 'autofillLabels' setted to 'false', Make sure to sigilify all Sigil classes or set 'autofillLabels' to 'true'`
+            `[Sigil Error] Class '${a2.name}' is not sigilified, Make sure to sigilify all Sigil classes or set 'autofillLabels' to 'true'`
           );
         sigilify(a2, generateRandomLabel(a2));
       }
       labelOwner.set(labelOf(a2), a2.name);
     }
-    return labelOwner;
   }
   function sigilify(ctor, label) {
     var _a;
@@ -106,6 +101,8 @@
         enumerable: false,
         writable: false
       });
+    getLabelRegistry().add(label);
+    handledCtors.add(ctor);
   }
   function isSigilCtor(ctor) {
     return typeof ctor === "function" && ctor.prototype && __SIGIL__ in ctor.prototype;
@@ -122,6 +119,30 @@
   function lineageOf(ctor) {
     return ctor.prototype[__LINEAGE__];
   }
+  function getSigilLabels(includeAuto = false) {
+    const labels = getLabelRegistry().labels();
+    if (includeAuto) return labels;
+    return labels.filter((l) => !l.startsWith(AUTO_LABEL_PREFEX));
+  }
+  function getLabelRegistry() {
+    if ("__labelRegistry__" in globalThis) return globalThis.__labelRegistry__;
+    const labelSet = /* @__PURE__ */ new Set();
+    let count = 0;
+    const labelRegistry = {
+      has: (label) => labelSet.has(label),
+      add: (label) => labelSet.add(label),
+      labels: () => [...labelSet],
+      enc: () => ++count
+    };
+    Object.freeze(labelRegistry);
+    Object.defineProperty(globalThis, "__labelRegistry__", {
+      value: labelRegistry,
+      writable: false,
+      configurable: false,
+      enumerable: false
+    });
+    return labelRegistry;
+  }
   function verifyLabel(ctor, label, opts) {
     var _a, _b;
     const labelValidation = (_a = opts == null ? void 0 : opts.labelValidation) != null ? _a : OPTIONS.labelValidation;
@@ -129,31 +150,28 @@
     if (!label) {
       if (!autofillLabels)
         throw new Error(
-          `[Sigil Error] Class '${ctor == null ? void 0 : ctor.name}' is not sigilified with 'autofillLabels' setted to 'false', Make sure to sigilify all Sigil classes or set 'autofillLabels' to 'true'`
+          `[Sigil Error] Class '${ctor == null ? void 0 : ctor.name}' is not sigilified, Make sure to sigilify all Sigil classes or set 'autofillLabels' to 'true'`
         );
       return;
     }
     if (label.startsWith(AUTO_LABEL_PREFEX))
       throw new Error(`'${AUTO_LABEL_PREFEX}' is a prefex reserved by the library`);
+    if (getLabelRegistry().has(label))
+      throw new Error(
+        `[Sigil Error] Passed label '${label}' to class '${ctor == null ? void 0 : ctor.name}' is re-used, passed labels must be unique`
+      );
     if (labelValidation) {
       let valid;
       if (labelValidation instanceof RegExp) valid = labelValidation.test(label);
       else valid = labelValidation(label);
       if (!valid)
         throw new Error(
-          `[Sigil Error] Invalid identity label '${label}'. Make sure that supplied label matches validation regex or function`
+          `[Sigil Error] Invalid Sigil label '${label}'. Make sure that supplied label matches validation regex or function`
         );
     }
   }
-  function initCounter() {
-    if (!globalThis.__SigilabelCounter) globalThis.__SigilabelCounter = 0;
-  }
   function generateRandomLabel(ctor) {
-    initCounter();
-    const counter = globalThis.__SigilabelCounter++;
-    const time = Date.now().toString(36);
-    const rand = Math.random().toString(36).slice(2, 6);
-    return `${AUTO_LABEL_PREFEX}:${ctor == null ? void 0 : ctor.name}:${time}:${counter.toString(36)}:${rand}`;
+    return `${AUTO_LABEL_PREFEX}:${ctor == null ? void 0 : ctor.name}:${getLabelRegistry().enc()}:${Math.random().toString(36).slice(2, 10)}`;
   }
 
   // src/mixin.ts
@@ -271,7 +289,7 @@
       /**
        * Returns the identity sigil label of this instance's constructor.
        *
-       * @returns The label string if passed (e.g. '@scope/pkg.ClassName'), random label if not passed (e.g. '@Sigil-auto:ClassName:mm2gkdwn:0:g1sq').
+       * @returns The label string if passed (e.g. '@scope/pkg.ClassName'), random label if not passed (e.g. '@Sigil-auto:ClassName:1:pnf11bgl').
        */
       getSigilLabel() {
         return this[__LABEL__];
@@ -418,7 +436,7 @@
       /**
        * Returns the identity sigil label of this instance's constructor.
        *
-       * @returns The label string if passed (e.g. '@scope/pkg.ClassName'), random label if not passed (e.g. '@Sigil-auto:ClassName:mm2gkdwn:0:g1sq').
+       * @returns The label string if passed (e.g. '@scope/pkg.ClassName'), random label if not passed (e.g. '@Sigil-auto:ClassName:1:pnf11bgl').
        */
       getSigilLabel() {
         return this[__LABEL__];
@@ -487,11 +505,13 @@
   }
 
   exports.DEFAULT_LABEL_REGEX = DEFAULT_LABEL_REGEX;
+  exports.RECOMMENDED_LABEL_REGEX = RECOMMENDED_LABEL_REGEX;
   exports.Sigil = Sigil;
   exports.SigilError = SigilError;
   exports.Sigilify = Sigilify;
   exports.SigilifyAbstract = SigilifyAbstract;
   exports.WithSigil = WithSigil;
+  exports.getSigilLabels = getSigilLabels;
   exports.isSigilCtor = isSigilCtor;
   exports.isSigilInstance = isSigilInstance;
   exports.updateSigilOptions = updateSigilOptions;