@vicin/sigil 1.0.0

package/dist/core/classes.js

@@ -0,0 +1,18 @@
+import { Sigilify } from './mixin';
+/**
+ * A minimal root Sigil class used by the library as a base identity.
+ *
+ * This is produced by `Sigilify` and can serve as a basic sentinel/base
+ * class for other sigil classes or for debugging/inspection.
+ */
+export const Sigil = Sigilify(class {
+}, 'Sigil');
+/**
+ * A sigil variant of the built-in `Error` constructor used by the library
+ * to represent Sigil-specific errors.
+ *
+ * Use `SigilError` when you want an Error type that is identifiable via sigil
+ * runtime checks (e.g. `SigilError.isOfType(someError)`).
+ */
+export const SigilError = Sigilify(Error, 'SigilError');
+//# sourceMappingURL=classes.js.map

package/dist/core/classes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"classes.js","sourceRoot":"","sources":["../../src/core/classes.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAEnC;;;;;GAKG;AACH,MAAM,CAAC,MAAM,KAAK,GAAG,QAAQ,CAAC;CAAQ,EAAE,OAAO,CAAC,CAAC;AAEjD;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC,CAAC"}

package/dist/core/decorator.d.ts

@@ -0,0 +1,28 @@
+import type { SigilOptions } from './options';
+/**
+ * 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.
+ *
+ * @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`).
+ *                If not passed a random label is generated instead.
+ * @param opts - Options object to override any global options if needed.
+ * @returns A class decorator compatible with the ECMAScript decorator context.
+ */
+export declare function WithSigil<L extends string>(label?: L, opts?: SigilOptions): (value: Function, context: ClassDecoratorContext) => void;
+//# sourceMappingURL=decorator.d.ts.map

package/dist/core/decorator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decorator.d.ts","sourceRoot":"","sources":["../../src/core/decorator.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAE9C;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,SAAS,CAAC,CAAC,SAAS,MAAM,EAAE,KAAK,CAAC,EAAE,CAAC,EAAE,IAAI,CAAC,EAAE,YAAY,IAQvD,OAAO,QAAQ,EAAE,SAAS,qBAAqB,UAYjE"}

package/dist/core/decorator.js

@@ -0,0 +1,48 @@
+import { checkInheritance, decorateCtor, generateRandomLabel, isSigilCtor, verifyLabel, } from './helpers';
+/**
+ * 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.
+ *
+ * @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`).
+ *                If not passed a random label is generated instead.
+ * @param opts - Options object to override any global options if needed.
+ * @returns A class decorator compatible with the ECMAScript decorator context.
+ */
+export function WithSigil(label, opts) {
+    // generate random label if not passed and verify it
+    let l;
+    if (label) {
+        verifyLabel(label, opts);
+        l = label;
+    }
+    else
+        l = generateRandomLabel();
+    return function (value, context) {
+        // Only apply to class declarations
+        if (context.kind !== 'class')
+            return;
+        if (!isSigilCtor(value))
+            throw new Error(`[Sigil Error] 'WithSigil' decorator accept only Sigil classes but used on class ${value.name}`);
+        // Attach sigil metadata to constructor (registers label, sets symbols, marks decorated)
+        decorateCtor(value, l);
+        // Development-only inheritance checks and potential autofill
+        checkInheritance(value, opts);
+    };
+}
+//# sourceMappingURL=decorator.js.map

package/dist/core/decorator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"decorator.js","sourceRoot":"","sources":["../../src/core/decorator.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,gBAAgB,EAChB,YAAY,EACZ,mBAAmB,EACnB,WAAW,EACX,WAAW,GACZ,MAAM,WAAW,CAAC;AAGnB;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,UAAU,SAAS,CAAmB,KAAS,EAAE,IAAmB;IACxE,oDAAoD;IACpD,IAAI,CAAS,CAAC;IACd,IAAI,KAAK,EAAE,CAAC;QACV,WAAW,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;QACzB,CAAC,GAAG,KAAK,CAAC;IACZ,CAAC;;QAAM,CAAC,GAAG,mBAAmB,EAAE,CAAC;IAEjC,OAAO,UAAU,KAAe,EAAE,OAA8B;QAC9D,mCAAmC;QACnC,IAAI,OAAO,CAAC,IAAI,KAAK,OAAO;YAAE,OAAO;QACrC,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC;YACrB,MAAM,IAAI,KAAK,CACb,mFAAmF,KAAK,CAAC,IAAI,EAAE,CAChG,CAAC;QACJ,wFAAwF;QACxF,YAAY,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;QACvB,6DAA6D;QAC7D,gBAAgB,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;IAChC,CAAC,CAAC;AACJ,CAAC"}

package/dist/core/enhancers.d.ts

@@ -0,0 +1,58 @@
+import { type SigilOptions } from './options';
+import type { TypedSigil } from './types';
+/**
+ * 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.
+ * @param label - Optional label string. If omitted, a random label is generated.
+ * @param opts - Options object to override any global options if needed.
+ * @returns The same constructor value, with runtime metadata ensured.
+ */
+export declare function withSigil<S extends Function, L extends string = string>(Class: S, label?: L, opts?: SigilOptions): S;
+/**
+ * Narrow a constructor to a compile-time `TypedSigil` without modifying runtime.
+ *
+ * This is a *purely type-level* helper (no runtime changes). It optionally
+ * verifies in DEV that the runtime `SigilLabel` matches the provided `label`.
+ *
+ * Use this when the runtime metadata is already present (for example the class
+ * is already decorated or was created via `Sigilify`).
+ *
+ * @typeParam S - Constructor type (should be an ISigil).
+ * @typeParam L - Label literal to associate at compile-time.
+ * @param Class - The constructor to assert as typed sigil.
+ * @param label - Optional label literal to assert at compile-time (and to verify in DEV).
+ * @returns The same constructor value, typed as `TypedSigil<S, L, P>`.
+ */
+export declare function typed<S extends Function, L extends string = string>(Class: S, label?: L, opts?: Pick<SigilOptions, 'devMarker'>): TypedSigil<S, L>;
+/**
+ * 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.
+ *
+ * @typeParam S - Constructor type (should be an ISigil).
+ * @typeParam L - Label literal to attach.
+ * @param Class - The constructor (class) to decorate and type.
+ * @param label - Optional label string. If omitted, a random label is generated.
+ * @param parent - Optional parent sigil constructor (type-only).
+ * @param opts - Options object to override any global options if needed.
+ * @returns The same constructor value, with runtime metadata ensured and typed as `TypedSigil<S,L,P>`.
+ */
+export declare function withSigilTyped<S extends Function, L extends string = string>(Class: S, label?: L, opts?: SigilOptions): TypedSigil<S, L>;
+//# sourceMappingURL=enhancers.d.ts.map

package/dist/core/enhancers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"enhancers.d.ts","sourceRoot":"","sources":["../../src/core/enhancers.ts"],"names":[],"mappings":"AAOA,OAAO,EAAW,KAAK,YAAY,EAAE,MAAM,WAAW,CAAC;AACvD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAE1C;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,SAAS,CAAC,CAAC,SAAS,QAAQ,EAAE,CAAC,SAAS,MAAM,GAAG,MAAM,EACrE,KAAK,EAAE,CAAC,EACR,KAAK,CAAC,EAAE,CAAC,EACT,IAAI,CAAC,EAAE,YAAY,GAClB,CAAC,CAmBH;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,KAAK,CAAC,CAAC,SAAS,QAAQ,EAAE,CAAC,SAAS,MAAM,GAAG,MAAM,EACjE,KAAK,EAAE,CAAC,EACR,KAAK,CAAC,EAAE,CAAC,EACT,IAAI,CAAC,EAAE,IAAI,CAAC,YAAY,EAAE,WAAW,CAAC,GACrC,UAAU,CAAC,CAAC,EAAE,CAAC,CAAC,CAgBlB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,cAAc,CAAC,CAAC,SAAS,QAAQ,EAAE,CAAC,SAAS,MAAM,GAAG,MAAM,EAC1E,KAAK,EAAE,CAAC,EACR,KAAK,CAAC,EAAE,CAAC,EACT,IAAI,CAAC,EAAE,YAAY,GAClB,UAAU,CAAC,CAAC,EAAE,CAAC,CAAC,CAmBlB"}

package/dist/core/enhancers.js

@@ -0,0 +1,101 @@
+import { checkInheritance, decorateCtor, generateRandomLabel, isSigilCtor, verifyLabel, } from './helpers';
+import { OPTIONS } from './options';
+/**
+ * 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.
+ * @param label - Optional label string. If omitted, a random label is generated.
+ * @param opts - Options object to override any global options if needed.
+ * @returns The same constructor value, with runtime metadata ensured.
+ */
+export function withSigil(Class, label, opts) {
+    if (!isSigilCtor(Class))
+        throw new Error(`[Sigil Error] 'withSigil' HOF accept only Sigil classes  but used on class ${Class?.name ?? 'unknown'}`);
+    // generate random label if not passed and verify it
+    let l;
+    if (label) {
+        verifyLabel(label, opts);
+        l = label;
+    }
+    else
+        l = generateRandomLabel();
+    // decorate and check inheritance.
+    const ctor = Class;
+    decorateCtor(ctor, l);
+    checkInheritance(ctor, opts);
+    return Class;
+}
+/**
+ * Narrow a constructor to a compile-time `TypedSigil` without modifying runtime.
+ *
+ * This is a *purely type-level* helper (no runtime changes). It optionally
+ * verifies in DEV that the runtime `SigilLabel` matches the provided `label`.
+ *
+ * Use this when the runtime metadata is already present (for example the class
+ * is already decorated or was created via `Sigilify`).
+ *
+ * @typeParam S - Constructor type (should be an ISigil).
+ * @typeParam L - Label literal to associate at compile-time.
+ * @param Class - The constructor to assert as typed sigil.
+ * @param label - Optional label literal to assert at compile-time (and to verify in DEV).
+ * @returns The same constructor value, typed as `TypedSigil<S, L, P>`.
+ */
+export function typed(Class, label, opts) {
+    if (!isSigilCtor(Class))
+        throw new Error(`[Sigil Error] 'typed' HOF accept only Sigil classes but used on class ${Class?.name ?? 'unknown'}`);
+    if ((opts?.devMarker ?? OPTIONS.devMarker) && label) {
+        const runtimeLabel = Class.SigilLabel;
+        if (runtimeLabel && runtimeLabel !== label) {
+            // Runtime label mismatch — surfaced in DEV only
+            throw new Error(`[Sigil Error][typed] runtime label "${runtimeLabel}" does not match asserted label "${label}".`);
+        }
+    }
+    return Class;
+}
+/**
+ * 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.
+ *
+ * @typeParam S - Constructor type (should be an ISigil).
+ * @typeParam L - Label literal to attach.
+ * @param Class - The constructor (class) to decorate and type.
+ * @param label - Optional label string. If omitted, a random label is generated.
+ * @param parent - Optional parent sigil constructor (type-only).
+ * @param opts - Options object to override any global options if needed.
+ * @returns The same constructor value, with runtime metadata ensured and typed as `TypedSigil<S,L,P>`.
+ */
+export function withSigilTyped(Class, label, opts) {
+    if (!isSigilCtor(Class))
+        throw new Error(`[Sigil Error] 'withSigilTyped' HOF accept only Sigil classes but used on class ${Class?.name ?? 'unknown'}`);
+    // generate random label if not passed and verify it
+    let l;
+    if (label) {
+        verifyLabel(label, opts);
+        l = label;
+    }
+    else
+        l = generateRandomLabel();
+    // decorate and check inheritance.
+    const ctor = Class;
+    decorateCtor(ctor, l);
+    checkInheritance(ctor, opts);
+    return Class;
+}
+//# sourceMappingURL=enhancers.js.map

package/dist/core/enhancers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"enhancers.js","sourceRoot":"","sources":["../../src/core/enhancers.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,gBAAgB,EAChB,YAAY,EACZ,mBAAmB,EACnB,WAAW,EACX,WAAW,GACZ,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,OAAO,EAAqB,MAAM,WAAW,CAAC;AAGvD;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,SAAS,CACvB,KAAQ,EACR,KAAS,EACT,IAAmB;IAEnB,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC;QACrB,MAAM,IAAI,KAAK,CACb,8EAA8E,KAAK,EAAE,IAAI,IAAI,SAAS,EAAE,CACzG,CAAC;IAEJ,oDAAoD;IACpD,IAAI,CAAS,CAAC;IACd,IAAI,KAAK,EAAE,CAAC;QACV,WAAW,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;QACzB,CAAC,GAAG,KAAK,CAAC;IACZ,CAAC;;QAAM,CAAC,GAAG,mBAAmB,EAAE,CAAC;IAEjC,kCAAkC;IAClC,MAAM,IAAI,GAAG,KAAK,CAAC;IACnB,YAAY,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;IACtB,gBAAgB,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IAE7B,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,KAAK,CACnB,KAAQ,EACR,KAAS,EACT,IAAsC;IAEtC,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC;QACrB,MAAM,IAAI,KAAK,CACb,yEAAyE,KAAK,EAAE,IAAI,IAAI,SAAS,EAAE,CACpG,CAAC;IAEJ,IAAI,CAAC,IAAI,EAAE,SAAS,IAAI,OAAO,CAAC,SAAS,CAAC,IAAI,KAAK,EAAE,CAAC;QACpD,MAAM,YAAY,GAAG,KAAK,CAAC,UAAU,CAAC;QACtC,IAAI,YAAY,IAAI,YAAY,KAAK,KAAK,EAAE,CAAC;YAC3C,gDAAgD;YAChD,MAAM,IAAI,KAAK,CACb,uCAAuC,YAAY,oCAAoC,KAAK,IAAI,CACjG,CAAC;QACJ,CAAC;IACH,CAAC;IACD,OAAO,KAAyB,CAAC;AACnC,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,cAAc,CAC5B,KAAQ,EACR,KAAS,EACT,IAAmB;IAEnB,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC;QACrB,MAAM,IAAI,KAAK,CACb,kFAAkF,KAAK,EAAE,IAAI,IAAI,SAAS,EAAE,CAC7G,CAAC;IAEJ,oDAAoD;IACpD,IAAI,CAAS,CAAC;IACd,IAAI,KAAK,EAAE,CAAC;QACV,WAAW,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;QACzB,CAAC,GAAG,KAAK,CAAC;IACZ,CAAC;;QAAM,CAAC,GAAG,mBAAmB,EAAE,CAAC;IAEjC,kCAAkC;IAClC,MAAM,IAAI,GAAG,KAAK,CAAC;IACnB,YAAY,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;IACtB,gBAAgB,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IAE7B,OAAO,KAAyB,CAAC;AACnC,CAAC"}

package/dist/core/helpers.d.ts

@@ -0,0 +1,192 @@
+import { type SigilOptions } from './options';
+import type { ISigil, ISigilInstance } from './types';
+/** -----------------------------------------
+ *  High level helpers
+ * ----------------------------------------- */
+/**
+ * Attach sigil-related statics to a constructor and register its label.
+ *
+ * Side effects:
+ * - Registers `label` in the global registry via `REGISTRY.register(label)`.
+ * - Defines non-enumerable statics on the constructor:
+ *   - `__LABEL__` (string)
+ *   - `__TYPE__` (Symbol.for(label))
+ *   - `__TYPE_LINEAGE__` (array of symbols)
+ *   - `__TYPE_SET__` (Set of symbols)
+ * - Marks the constructor as decorated via `markDecorated`.
+ *
+ * Throws if the constructor is already decorated.
+ *
+ * @internal
+ * @param ctor - The constructor to decorate.
+ * @param label - The identity label to register and attach (e.g. '@scope/pkg.ClassName').
+ * @param opts - Options object to override any global options if needed.
+ * @throws Error when `ctor` is already decorated.
+ */
+export declare function decorateCtor(ctor: Function, label: string): void;
+/**
+ * Perform development-only inheritance checks to ensure no ancestor classes
+ * reuse the same sigil label.
+ *
+ * Behavior:
+ * - No-op if `ctor` is not a sigil constructor.
+ * - No-op in non-DEV builds.
+ * - No-op if inheritance checks were already performed or `OPTIONS.skipLabelInheritanceCheck` is true.
+ *
+ * When a duplicate label is detected:
+ * - If the class is explicitly decorated (`isDecorated`) or `OPTIONS.autofillLabels` is false,
+ *   an Error is thrown describing the label collision.
+ * - Otherwise (autofill enabled), a random label will be generated and assigned
+ *   to the offending constructor via `decorateCtor`.
+ *
+ * @internal
+ * @param ctor - The constructor to validate.
+ * @param opts - Options object to override any global options if needed.
+ * @throws Error when a decorated subclass re-uses an ancestor's sigil label.
+ */
+export declare function checkInheritance(ctor: Function, opts?: Pick<SigilOptions, 'skipLabelInheritanceCheck' | 'autofillLabels' | 'devMarker'>): void;
+/**
+ * Validate a sigil label at runtime and throw a helpful error if it is malformed.
+ *
+ * This is intentionally `void` and runs synchronously at class declaration time so
+ * invalid labels fail fast during development. Validation behavior follows `OPTIONS.labelValidation`:
+ * - If `OPTIONS.labelValidation` is `null` no validation is performed.
+ * - If it is a `RegExp`, the label must match the regex.
+ * - If it is a function, the function must return `true` for the label to be considered valid.
+ *
+ * @internal
+ * @typeParam L - Label string literal type.
+ * @param label - The label to validate.
+ * @param opts - Options object to override any global options if needed.
+ * @throws {Error} Throws when the label does not pass configured validation.
+ */
+export declare function verifyLabel<L extends string>(label: L, opts?: Pick<SigilOptions, 'labelValidation'>): void;
+/**
+ * Generate a random alphanumeric label of the requested length.
+ *
+ * This is used to auto-generate labels when `OPTIONS.autofillLabels` is enabled.
+ * It insures that generated label is not registered yet.
+ *
+ * @internal
+ * @param length - Desired length of the generated string (defaults to 16).
+ * @returns A random label.
+ */
+export declare function generateRandomLabel(length?: number): string;
+/** -----------------------------------------
+ *  Introspection helpers
+ * ----------------------------------------- */
+/**
+ * Mark a constructor as a sigil constructor by attaching an internal symbol.
+ *
+ * This function defines a non-enumerable, non-writable, non-configurable
+ * property on the constructor so subsequent checks can detect sigil
+ * constructors.
+ *
+ * @internal
+ * @param ctor - The constructor to mark.
+ */
+export declare function markSigil(ctor: Function): void;
+/**
+ * Mark a constructor as a "sigil base" constructor.
+ *
+ * A sigil base constructor indicates that the class is the base for
+ * other sigil classes. This writes a stable, non-enumerable property
+ * to the constructor.
+ *
+ * @internal
+ * @param ctor - The constructor to mark as sigil base.
+ */
+export declare function markSigilBase(ctor: Function): void;
+/**
+ * Mark a constructor as having been decorated with `WithSigil`.
+ *
+ * This is used to detect classes that were explicitly decorated rather
+ * than auto-filled by the library.
+ *
+ * @internal
+ * @param ctor - The constructor that was decorated.
+ */
+export declare function markDecorated(ctor: Function): void;
+/**
+ * Mark that inheritance checks for this constructor have already been performed.
+ *
+ * The library uses this to avoid repeating expensive inheritance validation
+ * during development.
+ *
+ * @internal
+ * @param ctor - The constructor that has been checked.
+ */
+export declare function markInheritanceChecked(ctor: Function): void;
+/**
+ * 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 value - Value to test.
+ * @returns `true` if `value` is a sigil constructor, otherwise `false`.
+ */
+export declare function isSigilCtor(value: unknown): value is ISigil;
+/**
+ * Runtime predicate that checks whether the provided object is an instance
+ * of a sigil class.
+ *
+ * The function is defensive: non-objects return `false`. If an object is
+ * passed, the object's constructor is resolved and tested with `isSigilCtor`.
+ *
+ * @param obj - The value to test.
+ * @returns `true` if `obj` is an instance produced by a sigil constructor.
+ */
+export declare function isSigilInstance(obj: unknown): obj is ISigilInstance;
+/**
+ * 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.
+ */
+export declare function isSigilBaseCtor(ctor: Function): boolean;
+/**
+ * Check whether the provided object is an instance of a sigil base constructor.
+ *
+ * This resolves the object's constructor and delegates to `isSigilBaseCtor`.
+ *
+ * @param obj - The object to test.
+ * @returns `true` if `obj` is an instance of a sigil base constructor.
+ */
+export declare function isSigilBaseInstance(obj: unknown): obj is ISigilInstance;
+/**
+ * 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.
+ */
+export 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.
+ */
+export declare function isInheritanceChecked(ctor: Function): boolean;
+/** -----------------------------------------
+ *  Generic helpers
+ * ----------------------------------------- */
+/**
+ * Retrieve the constructor function for a given instance.
+ *
+ * Returns `null` for non-objects or when a constructor cannot be resolved.
+ *
+ * @internal
+ * @param obj - The value that may be an instance whose constructor should be returned.
+ * @returns The constructor function or `null` if not available.
+ */
+export declare function getConstructor(obj: any): any;
+//# sourceMappingURL=helpers.d.ts.map

package/dist/core/helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../src/core/helpers.ts"],"names":[],"mappings":"AAAA,OAAO,EAAW,KAAK,YAAY,EAAE,MAAM,WAAW,CAAC;AAYvD,OAAO,KAAK,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAEtD;;+CAE+C;AAE/C;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,QA6CzD;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,QAAQ,EACd,IAAI,CAAC,EAAE,IAAI,CACT,YAAY,EACZ,2BAA2B,GAAG,gBAAgB,GAAG,WAAW,CAC7D,QA6CF;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,WAAW,CAAC,CAAC,SAAS,MAAM,EAC1C,KAAK,EAAE,CAAC,EACR,IAAI,CAAC,EAAE,IAAI,CAAC,YAAY,EAAE,iBAAiB,CAAC,GAC3C,IAAI,CAaN;AAED;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,SAAK,GAAG,MAAM,CAIvD;AAED;;+CAE+C;AAE/C;;;;;;;;;GASG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,QAAQ,QAOvC;AAED;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,QAAQ,QAO3C;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,QAAQ,QAO3C;AAED;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,QAAQ,QAOpD;AAED;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAE3D;AAED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,cAAc,CAInE;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAEvD;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,cAAc,CAIvE;AAED;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAEnD;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAE5D;AAED;;+CAE+C;AAE/C;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,GAAG,OAGtC"}