@teacss/engine 0.8.5-alpha.4 → 0.9.0-alpha.4

package/dist/countable-set.js

@@ -0,0 +1,205 @@
+// Token collections the facade shares with `@teacss/core`: CountableSet (core/utils/countable-set.ts),
+// expandInputGroups (core/generator.ts:517-535) and the FIFO caches of core/bounded-cache.ts.
+import { expandClassGroups, splitClassTokens } from "../binding.js";
+export const MAX_RUNTIME_CACHE_ENTRIES = 10_000;
+export class CountableSet extends Set {
+    _map = new Map();
+    constructor(values) {
+        super();
+        if (values)
+            for (const key of values)
+                this.add(key);
+    }
+    add(key) {
+        this._map.set(key, (this._map.get(key) ?? 0) + 1);
+        return super.add(key);
+    }
+    delete(key) {
+        if (!this._map.has(key))
+            return false;
+        this._map.delete(key);
+        return super.delete(key);
+    }
+    clear() {
+        this._map.clear();
+        super.clear();
+    }
+    getCount(key) {
+        return this._map.get(key) ?? 0;
+    }
+    setCount(key, count) {
+        this._map.set(key, count);
+        return super.add(key);
+    }
+}
+export function isCountableSet(value) {
+    return value instanceof CountableSet;
+}
+export function copyCountableSet(input) {
+    const copied = new CountableSet();
+    for (const key of input)
+        copied.setCount(key, input.getCount(key));
+    return copied;
+}
+/**
+ * Expands the tokens holding a `{…}` group in place; the parts go to the end, and a counted
+ * group's count carries over to each part.
+ */
+export function expandInputGroups(tokens) {
+    const expanded = [...tokens].filter((token) => token.includes("{"));
+    if (expanded.length === 0)
+        return tokens;
+    for (const token of expanded) {
+        const parts = splitClassTokens(expandClassGroups(token));
+        if (parts.length === 1 && parts[0] === token)
+            continue;
+        const count = isCountableSet(tokens) ? tokens.getCount(token) : 1;
+        tokens.delete(token);
+        for (const part of parts) {
+            if (isCountableSet(tokens))
+                tokens.setCount(part, tokens.getCount(part) + count);
+            else
+                tokens.add(part);
+        }
+    }
+    return tokens;
+}
+/** The value of an entry whose token has not been resolved yet; never a valid `V`. */
+const PENDING = Symbol("@teacss/engine/pending");
+function noResolver(token) {
+    throw new TypeError(`[@teacss/engine] pending cache entry "${token}" has no resolver`);
+}
+/**
+ * The part of the oracle `BoundedMap` the facade uses: ordinary keys are evicted oldest first,
+ * retained keys never count toward the limit. An entry can be pending (`setPending`,
+ * `replaceRetainedPending`): its value is `resolve(token)`, computed on the first read through
+ * `get`, `forEach` or iteration and kept in place; `has`, `size`, `delete` and eviction never
+ * resolve.
+ */
+export class BoundedTokenCache extends Map {
+    constructor(maxEntries = MAX_RUNTIME_CACHE_ENTRIES, resolve = noResolver) {
+        super();
+        this.maxEntries = maxEntries;
+        this.retained = new Set();
+        this.order = new Set();
+        this.resolve = resolve;
+    }
+    get retainedSize() {
+        return this.retained.size;
+    }
+    isRetained(key) {
+        return this.retained.has(key);
+    }
+    get(key) {
+        const stored = super.get(key);
+        return stored === PENDING ? this.#materialize(key) : stored;
+    }
+    *entries() {
+        for (const [key, stored] of super.entries())
+            yield [key, this.#value(key, stored)];
+    }
+    *values() {
+        for (const [key, stored] of super.entries())
+            yield this.#value(key, stored);
+    }
+    [Symbol.iterator]() {
+        return this.entries();
+    }
+    forEach(callback, thisArg) {
+        for (const [key, value] of this.entries())
+            callback.call(thisArg, value, key, this);
+    }
+    set(key, value) {
+        return this.#insert(key, value);
+    }
+    /** Caches `key` with the value `resolve` supplies on its first read. */
+    setPending(key) {
+        return this.#insert(key, PENDING);
+    }
+    delete(key) {
+        const deleted = super.delete(key);
+        this.order.delete(key);
+        this.retained.delete(key);
+        return deleted;
+    }
+    clear() {
+        super.clear();
+        this.order.clear();
+        this.retained.clear();
+    }
+    /** Replaces the retained entries (bounded-cache.ts:188-205 without the revision check). */
+    replaceRetained(entries) {
+        this.#replaceRetained(new Map(entries));
+    }
+    /** `replaceRetained` with every value pending. */
+    replaceRetainedPending(keys) {
+        const next = new Map();
+        for (const key of keys)
+            next.set(key, PENDING);
+        this.#replaceRetained(next);
+    }
+    #value(key, stored) {
+        return stored === PENDING ? this.#materialize(key) : stored;
+    }
+    #materialize(key) {
+        const value = this.resolve(key);
+        super.set(key, value);
+        return value;
+    }
+    #insert(key, value) {
+        const exists = super.has(key);
+        this.#store(key, value);
+        if (!exists && !this.retained.has(key))
+            this.order.add(key);
+        this.#enforceLimit();
+        return this;
+    }
+    #replaceRetained(next) {
+        for (const key of this.retained) {
+            if (next.has(key))
+                continue;
+            super.delete(key);
+            this.retained.delete(key);
+        }
+        for (const [key, value] of next) {
+            this.order.delete(key);
+            this.#store(key, value);
+            this.retained.add(key);
+        }
+        this.#enforceLimit();
+    }
+    /** The marker is stored as a `V`; every read path above resolves it before a caller sees it. */
+    #store(key, value) {
+        super.set(key, value);
+    }
+    #enforceLimit() {
+        while (this.size - this.retained.size > this.maxEntries) {
+            const oldest = this.order.values().next();
+            if (oldest.done)
+                break;
+            this.order.delete(oldest.value);
+            super.delete(oldest.value);
+        }
+    }
+}
+/** FIFO bounded Set (the oracle `BoundedSet` without its `assumeNoPrototypeBypass` fast path). */
+export class BoundedSet extends Set {
+    constructor(maxEntries = MAX_RUNTIME_CACHE_ENTRIES, values) {
+        super();
+        this.maxEntries = maxEntries;
+        if (values)
+            for (const value of values)
+                this.add(value);
+    }
+    add(value) {
+        super.add(value);
+        while (this.size > this.maxEntries) {
+            const oldest = this.values().next();
+            if (oldest.done)
+                break;
+            super.delete(oldest.value);
+        }
+        return this;
+    }
+}
+//# sourceMappingURL=countable-set.js.map

package/dist/errors.d.ts

@@ -0,0 +1,11 @@
+/** Errors the facade raises itself; an `Error` from napi (code `E_*`) passes through unwrapped. */
+export declare class TeacssEngineError extends Error {
+    code: string;
+    details: Record<string, unknown>;
+    constructor(code: string, message: string, details?: Record<string, unknown>);
+}
+/** v02.9 §2.1: the member needs `@teacss/core`, which is not installed. */
+export declare function tsRequiredError(member: string): TeacssEngineError;
+/** v02.9 §3.3: the member needs the TypeScript engine, which has not been materialized. */
+export declare function tsNotReadyError(member: string): TeacssEngineError;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.js

@@ -0,0 +1,18 @@
+/** Errors the facade raises itself; an `Error` from napi (code `E_*`) passes through unwrapped. */
+export class TeacssEngineError extends Error {
+    constructor(code, message, details = {}) {
+        super(message);
+        this.name = "TeacssEngineError";
+        this.code = code;
+        this.details = details;
+    }
+}
+/** v02.9 §2.1: the member needs `@teacss/core`, which is not installed. */
+export function tsRequiredError(member) {
+    return new TeacssEngineError("E_TS_REQUIRED", `[@teacss/engine] ${member} requires @teacss/core (optional peer) to be installed`, { member });
+}
+/** v02.9 §3.3: the member needs the TypeScript engine, which has not been materialized. */
+export function tsNotReadyError(member) {
+    return new TeacssEngineError("E_TS_REQUIRED", `[@teacss/engine] ${member} needs the TypeScript engine; await generator[Symbol.for('@teacss/engine/materialize')]() first or set engine: 'ts'`, { member });
+}
+//# sourceMappingURL=errors.js.map

package/dist/generator.d.ts

@@ -0,0 +1,155 @@
+import { ENGINE_INSTANCE, ENGINE_MATERIALIZE } from "./constants.js";
+/** Port of core/utils/events.ts:84-112. */
+export declare function createNanoEvents(): {
+    events: any;
+    emit(event: string, ...args: unknown[]): void;
+    on(event: string, cb: Function): () => void;
+};
+/** Port of core/utils/escape.ts:10-72 (CSSOM "serialize an identifier"). */
+export declare function escapeSelector(str: string): string;
+/** generator.ts:3722. */
+export declare function toEscapedSelector(raw: string): string;
+/**
+ * v02.9 §8.1: the process-wide counters, the same object the teacss-ts hook updates.
+ */
+export declare function engineStats(): {
+    rust: number;
+    ts: number;
+    fallbacks: Record<string, number>;
+};
+/**
+ * v02.9 §9: each reason and path prints once per process; the counter grows on every call. A
+ * host `report(reason, path, level)` (the hook's consola) replaces the stderr line.
+ */
+export declare function reportFallback(reason: string, path: string, host?: FacadeHost, level?: "info" | "warn"): void;
+export declare class FacadeGenerator {
+    #private;
+    /** The facade's own emitter; a TS backend's `events` are not forwarded. */
+    events: {
+        events: any;
+        emit(event: string, ...args: unknown[]): void;
+        on(event: string, cb: Function): () => void;
+    };
+    userConfig: Record<string, unknown>;
+    defaults: Record<string, unknown>;
+    /**
+     * An `engine` gives a Rust backend and `ts` a TypeScript one.
+     */
+    constructor({ engine, request, presets, transformers, ts, userConfig, defaults, host, transformer, }: {
+        engine?: any;
+        request?: object;
+        presets?: object[];
+        transformers?: object[];
+        ts?: any;
+        userConfig?: Record<string, unknown>;
+        defaults?: Record<string, unknown>;
+        host?: {
+            core?: any;
+        };
+        transformer?: object | null;
+    });
+    get version(): any;
+    get config(): any;
+    get cache(): any;
+    get blocked(): any;
+    get parentOrders(): any;
+    get activatedRules(): any;
+    set cache(value: any);
+    set blocked(value: any);
+    set parentOrders(value: any);
+    set activatedRules(value: any);
+    get [ENGINE_INSTANCE](): any;
+    /**
+     * The two overloads of generator.ts:2037-2040. With an `id` the Engine records the module's
+     * tokens; a counted set adds each token's occurrences.
+     */
+    applyExtractors(code: string, id?: string, extracted?: Set<string>): Promise<any>;
+    /**
+     * The overloads of generator.ts:2316-2318. String input is extracted here, as Rust's
+     * `{ kind: "code" }` would, so its tokens reach the cache and the unmatched check (the oracle
+     * runs `applyExtractors` on it, generator.ts:2378).
+     */
+    generate(input: string | string[] | Set<string>, options?: Record<string, any>): Promise<any>;
+    /**
+     * generator.ts:2113-2286. A tuple array, or `undefined` for a miss or a blocked token; a miss
+     * already cached reads back as `null`. With an `alias` nothing is cached.
+     */
+    parseToken(raw: string, alias?: string): Promise<any>;
+    /** generator.ts:3611. */
+    isBlocked(raw: string): any;
+    /** generator.ts:3623; the blocklist holds strings only (anything else falls back). */
+    getBlocked(raw: string): [string, undefined] | undefined;
+    /** generator.ts:2304-2314: cached tokens that emit the same output as `raw`. */
+    getCachedEquivalentTokens(raw: string): string[];
+    /** The TypeScript generator behind the tooling members, created on first call; a TS backend returns itself. */
+    [ENGINE_MATERIALIZE](): Promise<any>;
+    /** generator.ts:2105. */
+    makeContext(raw: string, applied: unknown): any;
+    /** generator.ts:2809. */
+    constructCustomCSS(context: unknown, body: unknown, overrideSelector?: string): any;
+    /** generator.ts:3160. */
+    stringifyUtil(parsed?: unknown, context?: unknown): any;
+    /** generator.ts:2635. */
+    matchVariants(raw: string, current?: string): Promise<any>;
+    /** generator.ts:2866. */
+    parseUtil(input: unknown, context: unknown, internal?: boolean, shortcutPrefix?: string | string[]): Promise<any>;
+    /** generator.ts:3208. */
+    expandShortcut(input: string, context: unknown, depth?: number): Promise<any>;
+    /** generator.ts:3409. */
+    stringifyShortcuts(parent: unknown, context: unknown, expanded: unknown[], meta?: unknown, matchedPrefixes?: unknown): Promise<any>;
+    /** generator.ts:1976-1980: a falsy config keeps the current one. */
+    setConfig(userConfig?: Record<string, unknown>, defaults?: Record<string, unknown>): Promise<void>;
+    /**
+     * generator.ts:1983-2008: a candidate generator for the configuration, without touching this
+     * one. A configuration Rust cannot serve gets a TypeScript candidate.
+     */
+    prepareConfig(userConfig: Record<string, unknown>, defaults?: Record<string, unknown>): Promise<Readonly<{
+        config: any;
+        defaults: Record<string, unknown>;
+        generator: FacadeGenerator;
+        userConfig: Record<string, unknown>;
+        version: number;
+    }>>;
+    /**
+     * generator.ts:2010-2035: switch to the prepared backend if no newer request superseded it. A
+     * superseded Rust candidate is disposed; so is the previous Engine once it is replaced.
+     */
+    commitConfig(prepared: {
+        config: unknown;
+        defaults: Record<string, unknown>;
+        generator: FacadeGenerator;
+        userConfig: Record<string, unknown>;
+        version: number;
+    }): boolean;
+}
+/**
+ * v02.9 §3.1: a Rust facade, or the reason the configuration needs TypeScript. Errors from
+ * `loadProject` (`E_*`) are thrown as they are, not turned into a fallback. The hook counts the
+ * initial creation, so this does not.
+ */
+export interface FacadeHost {
+    /** 挂钩注入的 @teacss/core 绑定；缺省时 facade 按需动态 import。 */
+    core?: {
+        version: string;
+        createGenerator: (config?: object, defaults?: object) => Promise<object>;
+        createTsGenerator?: (config?: object, defaults?: object) => Promise<object>;
+        extractorSplit: object;
+        isCountableSet?: (value: unknown) => boolean;
+        isTokenShaped?: (token: string) => boolean;
+        toEscapedSelector?: (raw: string) => string;
+        /** core/utils/warn.ts 的 warnOnce；传入时 shortcut 警告与 TS 引擎共用一个去重集合。 */
+        warnOnce?: (message: string) => void;
+    } | undefined;
+    /** 挂钩注入的日志出口；缺省时写 process.stderr。 */
+    report?: (reason: string, path: string, level: "info" | "warn") => void;
+}
+export type FacadeCreateResult = {
+    ok: true;
+    generator: FacadeGenerator;
+} | {
+    ok: false;
+    reason: string;
+    path: string;
+};
+export declare function createGenerator(config?: Record<string, unknown>, defaults?: Record<string, unknown>, host?: FacadeHost): Promise<FacadeCreateResult>;
+//# sourceMappingURL=generator.d.ts.map