@vicin/sigil 1.0.0

package/dist/core/helpers.js

@@ -0,0 +1,349 @@
+import { OPTIONS } from './options';
+import { REGISTRY } from './registry';
+import { __DECORATED__, __INHERITANCE_CHECKED__, __LABEL__, __SIGIL_BASE__, __SIGIL__, __TYPE_LINEAGE__, __TYPE_SET__, __TYPE__, } from './symbols';
+/** -----------------------------------------
+ *  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 function decorateCtor(ctor, label) {
+    // if already decorated throw error
+    if (isDecorated(ctor))
+        throw new Error(`Constructor ${ctor} is already decorated. if you are using 'withSigilTyped()' & '@WithSigil()' at the same time remove one of them.`);
+    // get symbol for the label and update registry
+    const symbol = Symbol.for(label);
+    REGISTRY.register(label, ctor);
+    // attach basic runtime statics
+    Object.defineProperty(ctor, __LABEL__, {
+        value: label,
+        configurable: false,
+        enumerable: false,
+        writable: false,
+    });
+    Object.defineProperty(ctor, __TYPE__, {
+        value: symbol,
+        configurable: false,
+        enumerable: false,
+        writable: false,
+    });
+    // compute type chain from parent (safe if parent hasn't been augmented yet — uses existing value or empty)
+    const parent = Object.getPrototypeOf(ctor);
+    const parentChain = parent && parent[__TYPE_LINEAGE__] ? parent[__TYPE_LINEAGE__] : [];
+    const ctorChain = [...parentChain, symbol];
+    Object.defineProperty(ctor, __TYPE_LINEAGE__, {
+        value: ctorChain,
+        configurable: false,
+        enumerable: false,
+        writable: false,
+    });
+    Object.defineProperty(ctor, __TYPE_SET__, {
+        value: new Set(ctorChain),
+        configurable: false,
+        enumerable: false,
+        writable: false,
+    });
+    // mark as decorated
+    markDecorated(ctor);
+}
+/**
+ * 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 function checkInheritance(ctor, opts) {
+    if (!(opts?.devMarker ?? OPTIONS.devMarker))
+        return;
+    if (!isSigilCtor(ctor))
+        return;
+    if (isInheritanceChecked(ctor) ||
+        (opts?.skipLabelInheritanceCheck ?? OPTIONS.skipLabelInheritanceCheck))
+        return;
+    /** Array of all sigil constructors in the chain (starting with the provided ctor) */
+    const ctors = [ctor];
+    // go through prototype chain to get all sigil ancestors
+    let ancestor = Object.getPrototypeOf(ctor);
+    while (isSigilCtor(ancestor)) {
+        ctors.push(ancestor);
+        ancestor = Object.getPrototypeOf(ancestor);
+    }
+    /** Map<label, className> to record the owner of each label. */
+    const labelOwner = new Map();
+    // loop ctors from base to current and make sure no label is reused
+    for (let i = ctors.length - 1; i >= 0; i--) {
+        const ctor = ctors[i];
+        if (!ctor)
+            continue;
+        let label = ctor.SigilLabel;
+        if (labelOwner.has(label)) {
+            if (isDecorated(ctor) ||
+                !(opts?.autofillLabels ?? OPTIONS.autofillLabels)) {
+                const ancestorName = labelOwner.get(label);
+                throw new Error(`[Sigil Error] Class "${ctor.name}" re-uses Sigil label "${label}" from ancestor "${ancestorName}". ` +
+                    `Each Sigil subclass must use a unique label. Did you forget to use "WithSigil(newLabel)" on the subclass?`);
+            }
+            label = generateRandomLabel();
+            decorateCtor(ctor, label);
+        }
+        labelOwner.set(label, ctor.name);
+    }
+    markInheritanceChecked(ctor);
+}
+/**
+ * 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 function verifyLabel(label, opts) {
+    const labelValidation = opts?.labelValidation ?? OPTIONS.labelValidation;
+    if (labelValidation) {
+        let valid;
+        if (labelValidation instanceof RegExp)
+            valid = labelValidation.test(label);
+        else
+            valid = labelValidation(label);
+        if (!valid)
+            throw new Error(`[Sigil] Invalid identity label "${label}". Make sure that supplied label matches validation regex or function.`);
+    }
+}
+/**
+ * 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 function generateRandomLabel(length = 16) {
+    let label = generateRandomString(length);
+    while (REGISTRY.has(label))
+        label = generateRandomLabel();
+    return `@Sigil.auto-${label}`;
+}
+/** -----------------------------------------
+ *  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 function markSigil(ctor) {
+    Object.defineProperty(ctor, __SIGIL__, {
+        value: true,
+        configurable: false,
+        enumerable: false,
+        writable: false,
+    });
+}
+/**
+ * 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 function markSigilBase(ctor) {
+    Object.defineProperty(ctor, __SIGIL_BASE__, {
+        value: true,
+        configurable: false,
+        enumerable: false,
+        writable: false,
+    });
+}
+/**
+ * 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 function markDecorated(ctor) {
+    Object.defineProperty(ctor, __DECORATED__, {
+        value: true,
+        configurable: false,
+        enumerable: false,
+        writable: false,
+    });
+}
+/**
+ * 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 function markInheritanceChecked(ctor) {
+    Object.defineProperty(ctor, __INHERITANCE_CHECKED__, {
+        value: true,
+        configurable: false,
+        enumerable: false,
+        writable: false,
+    });
+}
+/**
+ * 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 function isSigilCtor(value) {
+    return typeof value === 'function' && value[__SIGIL__] === true;
+}
+/**
+ * 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 function isSigilInstance(obj) {
+    if (!obj || typeof obj !== 'object')
+        return false;
+    const ctor = getConstructor(obj);
+    return isSigilCtor(ctor);
+}
+/**
+ * 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 function isSigilBaseCtor(ctor) {
+    return Object.hasOwn(ctor, __SIGIL_BASE__);
+}
+/**
+ * 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 function isSigilBaseInstance(obj) {
+    if (!obj || typeof obj !== 'object')
+        return false;
+    const ctor = getConstructor(obj);
+    return isSigilBaseCtor(ctor);
+}
+/**
+ * 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 function isDecorated(ctor) {
+    return Object.hasOwn(ctor, __DECORATED__);
+}
+/**
+ * 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 function isInheritanceChecked(ctor) {
+    return Object.hasOwn(ctor, __INHERITANCE_CHECKED__);
+}
+/** -----------------------------------------
+ *  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 function getConstructor(obj) {
+    if (!obj || typeof obj !== 'object')
+        return null;
+    return obj.constructor ?? Object.getPrototypeOf(obj)?.constructor ?? null;
+}
+/**
+ * Generate a random alphanumeric string of the requested length.
+ *
+ * @internal
+ * @param length - Desired length of the generated string (defaults to 16).
+ * @returns A random string consisting of upper/lower letters and digits.
+ */
+function generateRandomString(length = 16) {
+    const chars = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';
+    let result = '';
+    for (let i = 0; i < length; i++) {
+        result += chars.charAt(Math.floor(Math.random() * chars.length));
+    }
+    return result;
+}
+//# sourceMappingURL=helpers.js.map

package/dist/core/helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.js","sourceRoot":"","sources":["../../src/core/helpers.ts"],"names":[],"mappings":"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"}

package/dist/core/index.d.ts

@@ -0,0 +1,9 @@
+export { Sigil, SigilError } from './classes';
+export { WithSigil } from './decorator';
+export { typed, withSigil, withSigilTyped } from './enhancers';
+export { isDecorated, isInheritanceChecked, isSigilBaseCtor, isSigilBaseInstance, isSigilCtor, isSigilInstance, } from './helpers';
+export { Sigilify } from './mixin';
+export { updateOptions, type SigilOptions, DEFAULT_LABEL_REGEX, } from './options';
+export { REGISTRY } from './registry';
+export type { GetInstance, ISigil, ISigilInstance, ISigilStatic, SigilBrandOf, TypedSigil, } from './types';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAC9C,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC/D,OAAO,EACL,WAAW,EACX,oBAAoB,EACpB,eAAe,EACf,mBAAmB,EACnB,WAAW,EACX,eAAe,GAChB,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AACnC,OAAO,EACL,aAAa,EACb,KAAK,YAAY,EACjB,mBAAmB,GACpB,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,YAAY,EACV,WAAW,EACX,MAAM,EACN,cAAc,EACd,YAAY,EACZ,YAAY,EACZ,UAAU,GACX,MAAM,SAAS,CAAC"}

package/dist/core/index.js

@@ -0,0 +1,8 @@
+export { Sigil, SigilError } from './classes';
+export { WithSigil } from './decorator';
+export { typed, withSigil, withSigilTyped } from './enhancers';
+export { isDecorated, isInheritanceChecked, isSigilBaseCtor, isSigilBaseInstance, isSigilCtor, isSigilInstance, } from './helpers';
+export { Sigilify } from './mixin';
+export { updateOptions, DEFAULT_LABEL_REGEX, } from './options';
+export { REGISTRY } from './registry';
+//# sourceMappingURL=index.js.map

package/dist/core/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAC9C,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC/D,OAAO,EACL,WAAW,EACX,oBAAoB,EACpB,eAAe,EACf,mBAAmB,EACnB,WAAW,EACX,eAAe,GAChB,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AACnC,OAAO,EACL,aAAa,EAEb,mBAAmB,GACpB,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC"}

package/dist/core/mixin.d.ts

@@ -0,0 +1,115 @@
+import { type SigilOptions } from './options';
+import type { Constructor, ISigil } from './types';
+/**
+ * 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.
+ */
+export 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>;
+};
+//# sourceMappingURL=mixin.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"mixin.d.ts","sourceRoot":"","sources":["../../src/core/mixin.ts"],"names":[],"mappings":"AAWA,OAAO,EAAW,KAAK,YAAY,EAAE,MAAM,WAAW,CAAC;AAEvD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AAEnD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,QAAQ,CACtB,IAAI,EAAE,WAAW,EACjB,KAAK,CAAC,EAAE,MAAM,EACd,IAAI,CAAC,EAAE,YAAY;kBA4DI,GAAG,EAAE;kCAFQ,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC;QAuFtD;;;;WAIG;yBACc,MAAM;QAYvB;;;;WAIG;wBACa,MAAM;QAYtB;;;;WAIG;+BACoB,SAAS,MAAM,EAAE;QAYxC;;;;WAIG;2BACgB,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;;8BA1LC,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC;IAE7D;;OAEG;sBACsB,MAAM;IAI/B;;;;;OAKG;qBACqB,MAAM;IAI9B;;;;;;OAMG;4BAC4B,SAAS,MAAM,EAAE;IAIhD;;;;;;OAMG;wBACwB,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IA6BhD;;;;;OAKG;sBACsB,OAAO,GAAG,GAAG,IAAI,MAAM;IAIhD;;;;;;;;;;;;;;OAcG;aACa,CAAC,SAAS,MAAM,QACxB,CAAC,SACA,OAAO,GACb,KAAK,IAAI,YAAY,CAAC,CAAC,CAAC;IAS3B;;;;;;;;;;;OAWG;mBACmB,CAAC,SAAS,MAAM,QAC9B,CAAC,SACA,OAAO,GACb,KAAK,IAAI,YAAY,CAAC,CAAC,CAAC;EAyF9B"}