@vicin/sigil 1.0.1 → 1.1.0

package/dist/index.d.mts

@@ -0,0 +1,777 @@
+/**
+ * Small wrapper around a shared registry Set that provides safe operations
+ * and hot-reload-friendly behavior.
+ *
+ * Responsibilities:
+ * - Query the current registry (may be `null` to indicate disabled checks).
+ * - Register / unregister labels in a controlled manner.
+ * - Query class constructors using their 'SigilLabel'.
+ * - Support hot-reload tolerant registration (avoid throwing in DEV).
+ */
+declare class SigilRegistry {
+    /** Internal private registry map. */
+    private _registry;
+    /**
+     * @param map - Map used to register 'Sigil' classes. if not passed it will be auto-generated internally.
+     */
+    constructor(map?: Map<string, ISigil | null>);
+    /**
+     * Return a readonly view (array) of the current registry entries.
+     *
+     * @returns An array containing all registered labels, or an empty array when registry is disabled.
+     */
+    listLabels(): string[];
+    /**
+     * Determine whether the registry currently contains `label`.
+     *
+     * @param label - The label to test.
+     * @returns `true` if present; `false` otherwise.
+     */
+    has(label: string): boolean;
+    /**
+     * Get class constructor using its label.
+     *
+     * @param label - Label appended to Sigil class.
+     * @returns Reference to Sigil class constructor or null if stored with 'SigilOptions.storeConstructor = false'.
+     */
+    get(label: string): ISigil | null;
+    /**
+     * Register a label and class constructor in the active registry.
+     *
+     * If the label already exists then:
+     *   - In DEV builds: prints a console warning (HMR friendly) and returns early.
+     *   - In non-DEV builds: throws an Error to prevent duplicate registration.
+     *
+     * @param label - Label string to register (e.g. '@scope/pkg.ClassName').
+     * @param Class - Constructor of the class being registered.
+     * @param opts - Optional per-call overrides.
+     */
+    register(label: string, Class: ISigil | null, opts?: Pick<SigilOptions, 'devMarker' | 'storeConstructor'>): void;
+    /**
+     * Alias for 'SigilRegistry.register'.
+     *
+     * @param label - Label string to register (e.g. '@scope/pkg.ClassName').
+     * @param Class - Constructor of the class being registered.
+     * @param opts - Optional per-call overrides.
+     */
+    set(label: string, Class: ISigil | null, opts?: Pick<SigilOptions, 'devMarker' | 'storeConstructor'>): void;
+    /**
+     * Unregister a previously registered class.
+     *
+     * @param label - The label to remove from the registry.
+     * @returns `true` if the label was present and removed; `false` otherwise (or when registry is disabled).
+     */
+    unregister(label: string): boolean;
+    /**
+     * Alias for 'SigilRegistry.unregister'.
+     *
+     * @param label - The label to remove from the registry.
+     * @returns `true` if the label was present and removed; `false` otherwise (or when registry is disabled).
+     */
+    delete(label: string): boolean;
+    /**
+     * Replace active registry with new one. deprecated use 'updateOptions({ registry: newRegistry })' instead.
+     *
+     * @deprecated Will be removed in v2.0.0, check https://www.npmjs.com/package/@vicin/sigil?activeTab=readme#registry for more details.
+     * @param newRegistry - New Set<string> instance to use as the active registry, or `null` to disable checks.
+     */
+    replaceRegistry(newRegistry: Map<string, ISigil | null> | null): void;
+    /**
+     * Clear the registry completely.
+     *
+     * Useful for test teardown, or when explicitly resetting state during development.
+     * No-op when the registry is disabled.
+     */
+    clear(): void;
+    /**
+     * Merge another SigilRegistry into this one.
+     *
+     * Entries from `other` will be registered into this registry. Duplicate labels
+     * are handled via this registry's `register` logic (i.e., will warn in DEV or
+     * throw in production).
+     *
+     * @param other - Another `SigilRegistry` whose entries will be merged into this registry.
+     */
+    merge(other: SigilRegistry): void;
+    /**
+     * Return a Map-style iterator over entries: `[label, constructor]`.
+     * Equivalent to calling `registry[Symbol.iterator]()`.
+     *
+     * @returns IterableIterator of `[label, ISigil]`.
+     */
+    entries(): IterableIterator<[string, ISigil | null]>;
+    /**
+     * Return an iterator over registered constructors.
+     *
+     * @returns IterableIterator of `ISigil` constructors.
+     */
+    values(): IterableIterator<ISigil | null>;
+    /**
+     * Return an iterator over registered labels (keys).
+     *
+     * @returns IterableIterator of `string` labels.
+     */
+    keys(): IterableIterator<string>;
+    /**
+     * Execute a provided function once per registry entry.
+     *
+     * @param callback - Function invoked with `(ctor, label)` for each entry.
+     * @param thisArg - Optional `this` context for the callback.
+     */
+    forEach(callback: (ctor: ISigil | null, label: string) => void, thisArg?: any): void;
+    /**
+     * Get the size (number of entries) of the active registry.
+     *
+     * @returns The number of registered labels, or 0 when registry is disabled.
+     */
+    get size(): number;
+    /**
+     * Return an iterator over `[label, constructor]` pairs.
+     *
+     * This makes the registry compatible with `for..of` and other iterable helpers:
+     * ```ts
+     * for (const [label, ctor] of registry) { ... }
+     * ```
+     *
+     * @returns An iterable iterator that yields `[label, ISigil]` tuples.
+     */
+    [Symbol.iterator](): IterableIterator<[string, ISigil | null]>;
+}
+/**
+ * Returns the currently configured SigilRegistry instance (or `null` if no registry is active).
+ *
+ * IMPORTANT: this function reflects the live `OPTIONS.registry` value and therefore
+ * will reflect any changes made via `updateOptions(...)`. Consumers that need a stable
+ * registry instance for mutation should call this function each time rather than
+ * holding a long-lived reference to the previously returned object.
+ *
+ * It gets global registry if defined, otherwise returns registry stored in SigilOptions.
+ *
+ * @returns {SigilRegistry | null} The active registry or `null` when no registry is in use.
+ */
+declare const getActiveRegistry: () => SigilRegistry | null;
+/** -----------------------------------------
+ *  Deprecated registry
+ * ----------------------------------------- */
+/**
+ * Old 'REGISTRY' alias to interact with registy.
+ *
+ * 'REGISTRY' is a live binding for compat; prefer getActiveRegistry() to avoid manual sync.
+ * @deprecated Will be removed in v2.0.0, check https://www.npmjs.com/package/@vicin/sigil?activeTab=readme#registry for more details.
+ */
+declare let REGISTRY: SigilRegistry;
+/** -----------------------------------------
+ *  Label validation
+ * ----------------------------------------- */
+/**
+ * Label validation regex. Labels must follow the pattern
+ * `@scope/package.ClassName` where `ClassName` begins with an uppercase
+ * letter. This avoids collisions across packages and helps debugging.
+ *
+ * It's advised to use this regex in 'SigilOptions.labelValidation'.
+ */
+declare const DEFAULT_LABEL_REGEX: RegExp;
+/** -----------------------------------------
+ *  Deprecated registry
+ * ----------------------------------------- */
+/**
+ * Update runtime options for the Sigil library.
+ * Call this early during application startup if you want non-default behavior.
+ *
+ * Example:
+ * ```ts
+ * updateOptions({ autofillLabels: true, labelValidation: /^@[\w-]+\/[\w-]+\.[A-Za-z0-9]+$/ });
+ * ```
+ *
+ * @param opts - Partial options to merge into the global `OPTIONS` object.
+ * @param mergeRegistries - Boolean to merge old registry into new one directly, default is 'true'.
+ */
+declare const updateOptions: (opts: SigilOptions, mergeRegistries?: boolean) => void;
+
+/** -----------------------------------------
+ *  Options
+ * ----------------------------------------- */
+/**
+ * Configuration options for the Sigil library.
+ *
+ * These options control runtime validation, inheritance checks, label autofill behavior,
+ * and whether duplicate labels are permitted globally.
+ *
+ * Note: these options are read by runtime code during class decoration and inheritance
+ * checks. Some behaviors (like `skipLabelInheritanceCheck`) are meant primarily for
+ * development/test scenarios and may weaken type/identity guarantees when changed.
+ */
+interface SigilOptions {
+    /**
+     * Validation rule applied to sigil labels before registration.
+     *
+     * - A function receives the label and must return `true` if valid.
+     * - A `RegExp` must match the label.
+     * - `null` disables validation entirely.
+     *
+     * Defaults to `null`.
+     */
+    labelValidation?: ((label: string) => boolean) | RegExp | null;
+    /**
+     * Skips the runtime check that prevents subclasses from inheriting
+     * the same sigil label as their ancestors.
+     *
+     * When `false` (default), extending a sigil class without
+     * using `WithSigil(newLabel)` decorator will throw an error if the label
+     * is reused and `OPTIONS.autofillLabels` is set to `false`.
+     *
+     * Set this to `true` only if you intentionally want subclasses to inherit labels
+     * from their ancestors (this weakens the uniqueness guarantees).
+     *
+     * WARNING:
+     * Disabling inheritanceCheck removes guaranties by 'Sigil' or unique label for
+     * each class and allow multiple child classes to use the same label which can
+     * result on false 'isOfType' result. this options should be used in debugging
+     * only to silence all errors but never in production.
+     */
+    skipLabelInheritanceCheck?: boolean;
+    /**
+     * When enabled, non-decorated subclasses that would otherwise inherit an ancestor's label
+     * will be assigned an autogenerated random label (so that explicit labels stay unique).
+     */
+    autofillLabels?: boolean;
+    /**
+     * Marker used internally to control dev only checks to optimize performace while preserving
+     * consistency for things like inheritance checks.
+     * defaults to 'process.env.NODE_ENV !== "production'.
+     */
+    devMarker?: boolean;
+    /**
+     * Registry instance used to store and resolve sigil labels at runtime.
+     *
+     * - When `useGlobalRegistry` is `true` (default), this registry will be
+     *   registered as the active global registry via `updateGlobalRegistry(...)`.
+     * - When `useGlobalRegistry` is `false`, this registry is kept local and will
+     *   not participate in global identity checks.
+     *
+     * IMPORTANT:
+     * Replacing the registry via `updateOptions({ registry })` changes the active
+     * registry used by Sigil, but consumers should always retrieve the registry
+     * through `getRegistry()` rather than holding a long-lived reference.
+     *
+     * Defaults to a new `SigilRegistry` instance.
+     *
+     * WARNING:
+     * Setting registry to null disables:
+     * - Label re-use checks entirly.
+     * - Feature relying on get(label) → class (e.g., deserialization)
+     */
+    registry?: SigilRegistry | null;
+    /**
+     * Controls whether the configured `registry` is stored in 'globalThis'.
+     *
+     * When `true` (default):
+     * - The registry is registered globally
+     * - All sigilized classes participate in the same identity space
+     *
+     * When `false`:
+     * - No global registry is used
+     * - Identity checks are limited to explicitly provided registry
+     *
+     * WARNING:
+     * Disabling the global registry may lead to duplicate labels across
+     * isolated registries and should only be done in advanced or test scenarios.
+     */
+    useGlobalRegistry?: boolean;
+    /**
+     * Controls whether the configured 'registry' should store class constructors.
+     * This is useful if you want to use 'Sigil' while keeping the constructor private.
+     *
+     * Note that any feature relying on get(label) → class (e.g., deserialization) will
+     * not work if set to 'true' as class is replaced with 'null'.
+     *
+     * When 'true' (default):
+     * - Class passed will be stored in the registry map under its label.
+     *
+     * When 'false':
+     * - Registry map stored only label key and class constructor is replaced with null ([label, null])
+     */
+    storeConstructor?: boolean;
+}
+/** -----------------------------------------
+ *  Class and instance
+ * ----------------------------------------- */
+/**
+ * Static-side interface describing methods and properties added to a class
+ * constructor when it is sigilized.
+ *
+ * The properties and methods described here mirror the getters and static
+ * predicates implemented by the `Sigilify` mixin.
+ *
+ * @template L - Narrow string literal type representing the label.
+ * @template US - Optinal original Untyped Sigil constructor type being augmented.
+ */
+interface ISigilStatic<L extends string = string, US extends Function = never> {
+    /**
+     * Compile-time nominal brand that encodes the class label `L` plus parent's brand keys `BrandOf<P>`.
+     *
+     * - Provides a *type-only* unique marker that makes instances nominally
+     *   distinct by label and allows propagation/merging of brand keys across inheritance.
+     * - Runtime: **no runtime value is required**; this property exists only for the type system.
+     *
+     * @remarks
+     * Consumers should not read or set this property at runtime. It is used by helper
+     * types (e.g. `SigilBrandOf`, `TypedSigil`) to extract/propagate compile-time brands.
+     */
+    readonly __SIGIL_BRAND__: Prettify<{
+        [k in L]: true;
+    } & SigilBrandOf<US>>;
+    /** Class-level label constant (human readable). */
+    readonly SigilLabel: string;
+    /** Class-level unique symbol used as the runtime type identifier. */
+    readonly SigilType: symbol;
+    /**
+     * Copy of the linearized sigil type symbol chain for the current constructor.
+     * Useful for debugging and strict lineage comparisons.
+     */
+    readonly SigilTypeLineage: readonly symbol[];
+    /**
+     * Copy of the sigil type symbol set for the current constructor. Useful for
+     * O(1) membership checks and debugging.
+     */
+    readonly SigilTypeSet: Readonly<Set<symbol>>;
+    /**
+     * Runtime check that determines whether `obj` is an instance produced by a
+     * sigil class.
+     *
+     * Note: the concrete implementation provided by the mixin delegates to
+     * `isSigilInstance`.
+     *
+     * @param obj - Value to test.
+     * @returns Type guard narrowing `obj` to `ISigil`.
+     */
+    isSigilified(obj: unknown): obj is ISigil;
+    /**
+     * Check whether `other` is (or inherits from) the type represented by the
+     * calling constructor. Uses the other instance's `SigilTypeSet` to check
+     * membership. Works in O(1) and is reliable as long as `OPTIONS.skipLabelInheritanceCheck` is `false`.
+     *
+     * This replaces `instanceof` so that checks remain valid across bundles/realms
+     * and when subclassing.
+     *
+     * @typeParam T - The specific sigil constructor (`this`).
+     * @param this - The constructor performing the type check.
+     * @param other - The object to test.
+     * @returns A type guard asserting `other` is an instance of the constructor.
+     */
+    isOfType<T extends ISigil>(this: T, other: unknown): other is InstanceType<T>;
+    /**
+     * Strict lineage comparison: verifies that the calling constructor's type
+     * lineage (by symbol) matches the `other`'s lineage element-by-element.
+     *
+     * Works in O(n) where `n` is the lineage length and is useful when order
+     * and exact ancestry must be confirmed. reliable when `OPTIONS.skipLabelInheritanceCheck` is `false`.
+     *
+     * @typeParam T - The specific sigil constructor (`this`).
+     * @param this - The constructor performing the strict check.
+     * @param other - The object to test.
+     * @returns A type guard asserting `other` is an instance whose lineage matches exactly.
+     */
+    isOfTypeStrict<T extends ISigil>(this: T, other: unknown): other is InstanceType<T>;
+}
+/**
+ * Instance-side interface describing properties present on sigil instances.
+ * The methods mirror the instance helpers injected by the mixin.
+ *
+ * @template L - Narrow string literal type for the label returned by `getSigilLabel`.
+ * @template US - Optinal original Untyped Sigil constructor type being augmented.
+ */
+interface ISigilInstance<L extends string = string, US extends Function = never> {
+    /**
+     * Compile-time nominal brand that encodes the class label `L` plus parent's brand keys `BrandOf<P>`.
+     *
+     * - Provides a *type-only* unique marker that makes instances nominally
+     *   distinct by label and allows propagation/merging of brand keys across inheritance.
+     * - Runtime: **no runtime value is required**; this property exists only for the type system.
+     *
+     * @remarks
+     * Consumers should not read or set this property at runtime. It is used by helper
+     * types (e.g. `SigilBrandOf`, `TypedSigil`) to extract/propagate compile-time brands.
+     */
+    readonly __SIGIL_BRAND__: Prettify<{
+        [k in L]: true;
+    } & SigilBrandOf<US>>;
+    /** Returns human-readable sigil label of the class constructor. */
+    getSigilLabel(): string;
+    /** Returns runtime sigil type symbol of the class constructor. */
+    getSigilType(): symbol;
+    /** Returns copy of sigil type symbol lineage of the class constructor. */
+    getSigilTypeLineage(): readonly symbol[];
+    /** Returns copy of sigil type symbol set of the class constructor. */
+    getSigilTypeSet(): Readonly<Set<symbol>>;
+}
+/**
+ * Combined constructor + static interface for a sigil class.
+ *
+ * This composes the instance-side shape (Constructor<ISigilInstance<L>>) with
+ * the static-side interface (ISigilStatic<L>), matching the runtime shape added
+ * by `Sigilify`.
+ *
+ * @template L - Narrow string literal type for the label.
+ * @template US - Optinal original Untyped Sigil constructor type being augmented.
+ */
+type ISigil<L extends string = string, US extends Function = never> = Constructor<ISigilInstance<L, US>> & ISigilStatic<L, US>;
+/** -----------------------------------------
+ *  Helper sigil types
+ * ----------------------------------------- */
+/**
+ * Extract the compile-time brand map from a sigil constructor `S`.
+ *
+ * @typeParam S - A sigil constructor type (e.g. `typeof SomeSigilClass`).
+ * @returns The brand record carried on the constructor's instance type (e.g. `{ User: true, Admin: true }`).
+ *
+ * @remarks
+ * - This helper is used purely at the type level to compute the set of brand keys
+ *   that should be propagated to derived sigils.
+ * - If `S` does not carry a `__SIGIL_BRAND__`, the resulting type is `never` and `IfNever<>`
+ *   collapses it to an empty record.
+ */
+type SigilBrandOf<S> = IfNever<S extends {
+    readonly __SIGIL_BRAND__: infer Brand;
+} ? Prettify<Brand> : never, Record<string, true>>;
+/**
+ * Combine an existing sigil constructor type `S` with a **new** label `L`,
+ * while inheriting/propagating compile-time brands from an optional parent sigil `P`.
+ *
+ * @template US - The original Untyped Sigil constructor type being augmented.
+ * @template L - The new label literal to associate with the resulting constructor.
+ */
+type TypedSigil<US extends Function, L extends string = string> = US & ISigil<L, US>;
+/**
+ * Generic helper extract instance of the class even in protected and private constructors.
+ */
+type GetInstance<T> = T extends {
+    prototype: infer R;
+} ? Prettify<R & {
+    __SIGIL_BRAND__: SigilBrandOf<T>;
+}> : never;
+/** -----------------------------------------
+ *  Generic types
+ * ----------------------------------------- */
+/**
+ * Generic type for class constructors used by the Sigil utilities.
+ *
+ * - `T` is the instance type produced by the constructor.
+ * - `P` is the tuple of parameter types accepted by the constructor.
+ *
+ * @template T - Instance type produced by the constructor (defaults to `object`).
+ * @template P - Parameter tuple type for the constructor.
+ */
+type Constructor<T = object, P extends any[] = any[]> = new (...args: P) => T;
+/** Helper type to prettify value. */
+type Prettify<T> = {
+    [K in keyof T]: T[K];
+} & {};
+/** Helper type to replace 'never' with another type */
+type IfNever<T, R = {}> = [T] extends [never] ? R : T;
+
+/**
+ * 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.
+ */
+declare const Sigil: {
+    new (...args: any[]): {
+        readonly __SIGIL_BRAND__: Record<string, true>;
+        getSigilLabel(): string;
+        getSigilType(): symbol;
+        getSigilTypeLineage(): readonly symbol[];
+        getSigilTypeSet(): Readonly<Set<symbol>>;
+    };
+    readonly __SIGIL_BRAND__: Record<string, true>;
+    get SigilLabel(): string;
+    get SigilType(): symbol;
+    get SigilTypeLineage(): readonly symbol[];
+    get SigilTypeSet(): Readonly<Set<symbol>>;
+    isSigilified(obj: unknown): obj is ISigil;
+    isOfType<T extends ISigil>(this: T, other: unknown): other is InstanceType<T>;
+    isOfTypeStrict<T extends ISigil>(this: T, other: unknown): other is InstanceType<T>;
+};
+/**
+ * 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)`).
+ */
+declare const SigilError: {
+    new (...args: any[]): {
+        readonly __SIGIL_BRAND__: Record<string, true>;
+        getSigilLabel(): string;
+        getSigilType(): symbol;
+        getSigilTypeLineage(): readonly symbol[];
+        getSigilTypeSet(): Readonly<Set<symbol>>;
+    };
+    readonly __SIGIL_BRAND__: Record<string, true>;
+    get SigilLabel(): string;
+    get SigilType(): symbol;
+    get SigilTypeLineage(): readonly symbol[];
+    get SigilTypeSet(): Readonly<Set<symbol>>;
+    isSigilified(obj: unknown): obj is ISigil;
+    isOfType<T extends ISigil>(this: T, other: unknown): other is InstanceType<T>;
+    isOfTypeStrict<T extends ISigil>(this: T, other: unknown): other is InstanceType<T>;
+};
+
+/**
+ * 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.
+ */
+declare function WithSigil<L extends string>(label?: L, opts?: SigilOptions): (value: Function, context: ClassDecoratorContext) => void;
+
+/**
+ * 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.
+ */
+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>`.
+ */
+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>`.
+ */
+declare function withSigilTyped<S extends Function, L extends string = string>(Class: S, label?: L, opts?: SigilOptions): TypedSigil<S, L>;
+
+/**
+ * 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`.
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+declare function isInheritanceChecked(ctor: Function): boolean;
+
+/**
+ * Mixin factory that augments an existing class with Sigil runtime metadata and
+ * helpers. The returned class:
+ * - registers a stable symbol for the provided `label` (via `WithSigil`)
+ * - exposes static helpers such as `SigilLabel`, `SigilType`, `isOfType`, and `isOfTypeStrict`
+ * - exposes instance helpers such as `getSigilLabel`, `getSigilType`, etc.
+ *
+ * Notes:
+ * - Uses `Symbol.for(label)` internally so symbols are stable across bundles/realms
+ *   that share the global symbol registry.
+ * - Throws if `Base` is already a sigil constructor.
+ *
+ * @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.
+ */
+declare function Sigilify(Base: Constructor, label?: string, opts?: SigilOptions): {
+    new (...args: any[]): {
+        readonly __SIGIL_BRAND__: Record<string, true>;
+        /**
+         * Returns the human-readable 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.
+         */
+        getSigilLabel(): string;
+        /**
+         * Returns the runtime sigil type symbol of this instance's constructor.
+         *
+         * @returns The symbol that identifies this type at runtime.
+         */
+        getSigilType(): symbol;
+        /**
+         * Returns a copy of the sigil type symbol lineage for this instance's constructor.
+         *
+         * @returns readonly array of symbols representing the type lineage.
+         */
+        getSigilTypeLineage(): readonly symbol[];
+        /**
+         * Returns a readonly copy of the sigil type symbol set for this instance's constructor.
+         *
+         * @returns A Readonly Set of symbols representing the type lineage for O(1) membership tests.
+         */
+        getSigilTypeSet(): Readonly<Set<symbol>>;
+    };
+    readonly __SIGIL_BRAND__: Record<string, true>;
+    /**
+     * Class-level human-readable label constant for this sigil constructor.
+     */
+    get SigilLabel(): string;
+    /**
+     * Class-level unique runtime symbol used as the type identifier.
+     *
+     * This symbol is created with `Symbol.for(label)` during decoration so it is
+     * stable across realms that share the same global symbol registry.
+     */
+    get SigilType(): symbol;
+    /**
+     * Copy of the linearized sigil type symbol chain for the current constructor.
+     *
+     * Useful for debugging and performing strict lineage comparisons.
+     *
+     * @returns An array of symbols representing parent → child type symbols.
+     */
+    get SigilTypeLineage(): readonly symbol[];
+    /**
+     * Copy of the sigil type symbol set for the current constructor.
+     *
+     * Useful for quick membership checks (O(1) lookups) and debugging.
+     *
+     * @returns A Readonly Set of symbols that represent the type lineage.
+     */
+    get SigilTypeSet(): Readonly<Set<symbol>>;
+    /**
+     * Runtime predicate indicating whether `obj` is an instance produced by a sigil class.
+     *
+     * @param obj - The value to test.
+     * @returns `true` if `obj` is a sigil instance.
+     */
+    isSigilified(obj: unknown): obj is ISigil;
+    /**
+     * Check whether `other` is (or inherits from) the type represented by the calling constructor.
+     *
+     * Implementation detail:
+     * - Uses the other instance's `__TYPE_SET__` for O(1) membership test.
+     * - O(1) and reliable as long as `OPTIONS.skipLabelInheritanceCheck` is `false`.
+     *
+     * This replaces `instanceof` so that checks remain valid across bundles/realms
+     * and when subclassing.
+     *
+     * @typeParam T - The calling constructor type (narrowing the returned instance type).
+     * @param this - The constructor performing the check.
+     * @param other - The object to test.
+     * @returns `true` if `other` is an instance of this type or a subtype.
+     */
+    isOfType<T extends ISigil>(this: T, other: unknown): other is InstanceType<T>;
+    /**
+     * Strict lineage check: compares the type symbol lineage arrays element-by-element.
+     *
+     * Implementation detail:
+     * - Works in O(n) time where n is the depth of the lineage.
+     * - Reliable when `OPTIONS.skipLabelInheritanceCheck` is `false`.
+     *
+     * @typeParam T - The calling constructor type.
+     * @param this - The constructor performing the check.
+     * @param other - The object to test.
+     * @returns `true` if `other` has an identical lineage up to the length of this constructor's lineage.
+     */
+    isOfTypeStrict<T extends ISigil>(this: T, other: unknown): other is InstanceType<T>;
+};
+
+export { DEFAULT_LABEL_REGEX, type GetInstance, type ISigil, type ISigilInstance, type ISigilStatic, REGISTRY, Sigil, type SigilBrandOf, SigilError, type SigilOptions, SigilRegistry, Sigilify, type TypedSigil, WithSigil, getActiveRegistry, isDecorated, isInheritanceChecked, isSigilBaseCtor, isSigilBaseInstance, isSigilCtor, isSigilInstance, typed, updateOptions, withSigil, withSigilTyped };