@vicin/sigil 2.0.3 → 2.2.0

package/dist/index.d.ts

@@ -3,7 +3,7 @@
  * ----------------------------------------- */
 /**
  * Static-side interface describing methods and properties added to a class
- * constructor when it is sigilized.
+ * constructor when it is sigilified.
  *
  * The properties and methods described here mirror the getters and static
  * predicates implemented by the `Sigilify` mixin.
@@ -22,8 +22,10 @@ interface ISigilStatic<L extends string = string, P extends Function = never> {
     readonly __SIGIL_BRAND__: Prettify<{
         [k in L]: true;
     } & SigilBrandOf<P>>;
-    /** Class-level label constant (human readable). */
+    /** Class-level label constant (identity). */
     readonly SigilLabel: string;
+    /** Class-level label constant (human readable). */
+    readonly SigilEffectiveLabel: string;
     /**
      * Copy of the linearized sigil type label chain for the current constructor.
      * Useful for debugging and strict lineage comparisons.
@@ -91,8 +93,10 @@ interface ISigilInstance<L extends string = string, P extends Function = never>
     readonly __SIGIL_BRAND__: Prettify<{
         [k in L]: true;
     } & SigilBrandOf<P>>;
-    /** Returns human-readable sigil label of the class constructor. */
+    /** Returns identity sigil label of the class constructor. */
     getSigilLabel(): string;
+    /** Returns human-readable sigil label of the class constructor. */
+    getSigilEffectiveLabel(): string;
     /** Returns copy of sigil type label lineage of the class constructor. */
     getSigilLabelLineage(): readonly string[];
     /** Returns copy of sigil type label set of the class constructor. */
@@ -228,6 +232,7 @@ declare const Sigil: {
         isOfType<T>(this: T, other: unknown): other is GetInstance<T>;
         isOfTypeStrict<T>(this: T, other: unknown): other is GetInstance<T>;
         getSigilLabel(): string;
+        getSigilEffectiveLabel(): string;
         getSigilLabelLineage(): readonly string[];
         getSigilLabelSet(): Readonly<Set<string>>;
     };
@@ -235,6 +240,7 @@ declare const Sigil: {
         Sigil: true;
     };
     get SigilLabel(): string;
+    get SigilEffectiveLabel(): string;
     get SigilLabelLineage(): readonly string[];
     get SigilLabelSet(): Readonly<Set<string>>;
     isSigilified(obj: unknown): obj is ISigil;
@@ -260,6 +266,7 @@ declare const SigilError: {
         isOfType<T>(this: T, other: unknown): other is GetInstance<T>;
         isOfTypeStrict<T>(this: T, other: unknown): other is GetInstance<T>;
         getSigilLabel(): string;
+        getSigilEffectiveLabel(): string;
         getSigilLabelLineage(): readonly string[];
         getSigilLabelSet(): Readonly<Set<string>>;
     };
@@ -268,6 +275,7 @@ declare const SigilError: {
         SigilError: true;
     };
     get SigilLabel(): string;
+    get SigilEffectiveLabel(): string;
     get SigilLabelLineage(): readonly string[];
     get SigilLabelSet(): Readonly<Set<string>>;
     isSigilified(obj: unknown): obj is ISigil;
@@ -322,7 +330,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,21 +346,10 @@ 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.
- * - Throws an error during class creation if the label validation fails.
+ * - Throws an error during class creation if the label validation fails (in development only).
  *
  * @typeParam L - Narrow string literal type for the provided label.
  * @param label - Optional sigil label to assign to the decorated class (e.g. `@scope/pkg.ClassName`).
@@ -366,13 +363,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 +372,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 +387,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 +402,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 +409,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 +416,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 +424,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,19 +431,14 @@ 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').
  *                If not passed a random label is generated instead.
  * @param opts - Options object to override any global options if needed.
  * @returns A new abstract constructor that extends `Base` and includes Sigil statics/instance methods.
- * @throws Error if `Base` is already sigilized.
+ * @throws Error if `Base` is already sigilified.
  */
 declare function Sigilify<B extends Constructor, L extends string>(Base: B, label?: L, opts?: SigilOptions): {
     new (...args: any[]): {
@@ -509,11 +475,17 @@ declare function Sigilify<B extends Constructor, L extends string>(Base: B, labe
          */
         isOfTypeStrict<T_1>(this: T_1, other: unknown): other is GetInstance<T_1>;
         /**
-         * Returns the human-readable sigil label of this instance's constructor.
+         * Returns the identity sigil label of this instance's constructor.
          *
-         * @returns The label string (e.g. '@scope/pkg.ClassName') or '@Sigil.unknown' in DEV when constructor is missing.
+         * @returns The label string if passed (e.g. '@scope/pkg.ClassName'), random label if not passed (e.g. '@Sigil.auto-dq62ib6jnvmmlfbjhxh2937h') or '@Sigil.unknown' if constructor is missing.
          */
         getSigilLabel(): string;
+        /**
+         * Returns the human-readable sigil label of this instance's constructor.
+         *
+         * @returns The last passed label string (e.g. '@scope/pkg.ClassName') or '@Sigil.unknown' if constructor is missing.
+         */
+        getSigilEffectiveLabel(): string;
         /**
          * Returns a copy of the sigil type label lineage for this instance's constructor.
          *
@@ -538,9 +510,13 @@ declare function Sigilify<B extends Constructor, L extends string>(Base: B, labe
         Sigil: true;
     } & { [K in L]: true; }>;
     /**
-     * Class-level human-readable label constant for this sigil constructor.
+     * Class-level identity label constant for this sigil constructor.
      */
     get SigilLabel(): string;
+    /**
+     * Class-level human-readable label constant for this sigil constructor, last passed label in 'Sigil' chain by developer.
+     */
+    get SigilEffectiveLabel(): string;
     /**
      * Copy of the linearized sigil type label chain for the current constructor.
      *
@@ -587,19 +563,14 @@ 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').
  *                If not passed a random label is generated instead.
  * @param opts - Options object to override any global options if needed.
  * @returns A new abstract constructor that extends `Base` and includes Sigil statics/instance methods.
- * @throws Error if `Base` is already sigilized.
+ * @throws Error if `Base` is already sigilified.
  */
 declare function SigilifyAbstract<B extends ConstructorAbstract, L extends string>(Base: B, label?: L, opts?: SigilOptions): ((abstract new (...args: any[]) => {
     /**
@@ -635,11 +606,17 @@ declare function SigilifyAbstract<B extends ConstructorAbstract, L extends strin
      */
     isOfTypeStrict<T_1>(this: T_1, other: unknown): other is GetInstance<T_1>;
     /**
-     * Returns the human-readable sigil label of this instance's constructor.
+     * Returns the identity sigil label of this instance's constructor.
      *
-     * @returns The label string (e.g. '@scope/pkg.ClassName') or '@Sigil.unknown' in DEV when constructor is missing.
+     * @returns The label string if passed (e.g. '@scope/pkg.ClassName'), random label if not passed (e.g. '@Sigil.auto-dq62ib6jnvmmlfbjhxh2937h') or '@Sigil.unknown' if constructor is missing.
      */
     getSigilLabel(): string;
+    /**
+     * Returns the human-readable sigil label of this instance's constructor.
+     *
+     * @returns The last passed label string (e.g. '@scope/pkg.ClassName') or '@Sigil.unknown' if constructor is missing.
+     */
+    getSigilEffectiveLabel(): string;
     /**
      * Returns a copy of the sigil type label lineage for this instance's constructor.
      *
@@ -664,9 +641,13 @@ declare function SigilifyAbstract<B extends ConstructorAbstract, L extends strin
         Sigil: true;
     } & { [K in L]: true; }>;
     /**
-     * Class-level human-readable label constant for this sigil constructor.
+     * Class-level identity label constant for this sigil constructor.
      */
     get SigilLabel(): string;
+    /**
+     * Class-level human-readable label constant for this sigil constructor, last passed label in 'Sigil' chain by developer.
+     */
+    get SigilEffectiveLabel(): string;
     /**
      * Copy of the linearized sigil type label chain for the current constructor.
      *
@@ -721,4 +702,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 };