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

package/dist/facade/config-view.js

@@ -0,0 +1,96 @@
+// The facade's `generator.config`: a plain object whose keys follow the oracle `resolveConfig`
+// (core/config.ts:260-288), which spreads the merged config and then sets its own fields.
+import { tsNotReadyError } from "./errors.js";
+/** Fields the TypeScript generator provides; reading one before materialize throws `E_TS_REQUIRED`. */
+export const TS_ONLY_FIELDS = Object.freeze(["configResolved", "extendTheme", "preprocess", "postprocess", "preflights", "autocomplete", "rules", "rulesDynamic", "rulesStaticMap", "variants"]);
+/** Fields copied from the Rust `ResolvedConfigView`. */
+export const VIEW_FIELDS = Object.freeze(["layers", "theme", "shortcuts", "safelist", "blocklist", "separators", "envMode", "unmatched", "shortcutsLayer", "virtualModulePrefix", "mergeSelectors", "warn", "details", "outputToCssLayers", "rulesSize"]);
+/**
+ * The keys `resolveConfig` always sets, in its order (config.ts:262-288); `configResolved`,
+ * `extendTheme`, `extractorDefault` and `virtualModulePrefix` appear only through the spread.
+ */
+const RESOLVED_KEYS = Object.freeze([
+    "mergeSelectors",
+    "warn",
+    "unmatched",
+    "outputToCssLayers",
+    "sortLayers",
+    "blocklist",
+    "presets",
+    "envMode",
+    "shortcutsLayer",
+    "layers",
+    "theme",
+    "rules",
+    "rulesSize",
+    "rulesDynamic",
+    "rulesStaticMap",
+    "preprocess",
+    "postprocess",
+    "preflights",
+    "autocomplete",
+    "variants",
+    "shortcuts",
+    "extractors",
+    "safelist",
+    "separators",
+    "details",
+    "content",
+    "transformers",
+]);
+export function createConfigView({ view, presets, userConfig, transformers, host, fallback, engine }) {
+    const config = {};
+    const data = (key, value) => Object.defineProperty(config, key, { value, enumerable: true, configurable: true, writable: true });
+    const tsOnly = (key) => Object.defineProperty(config, key, {
+        enumerable: true,
+        configurable: true,
+        get() {
+            const ts = fallback.peek();
+            if (!ts)
+                throw tsNotReadyError(`config.${key}`);
+            return ts.config[key];
+        },
+    });
+    const extractors = host.core ? [host.core.extractorSplit] : [{ name: view.extractors?.[0]?.name ?? "@teacss/core/extractor-split" }];
+    const fields = {
+        presets: () => data("presets", presets),
+        content: () => data("content", view.content ?? {}),
+        transformers: () => data("transformers", transformers),
+        extractors: () => data("extractors", extractors),
+        extractorDefault: () => data("extractorDefault", extractors[0]),
+        sortLayers: () => data("sortLayers", (layers) => layers),
+    };
+    for (const key of VIEW_FIELDS)
+        fields[key] = () => data(key, view[key]);
+    if (engine) {
+        // compile-class.ts:84-106 pushes each definition onto `config.shortcuts` and splices it out
+        // when its last module drops it; the definitions live in the Engine, so one array is kept in
+        // step on every read.
+        const shortcuts = [...(view.shortcuts ?? [])];
+        const configured = shortcuts.length;
+        fields.shortcuts = () => Object.defineProperty(config, "shortcuts", {
+            enumerable: true,
+            configurable: true,
+            get() {
+                shortcuts.length = configured;
+                shortcuts.push(...engine.compileClassShortcuts());
+                return shortcuts;
+            },
+        });
+    }
+    for (const key of TS_ONLY_FIELDS)
+        fields[key] = () => tsOnly(key);
+    for (const key of Object.keys(userConfig ?? {})) {
+        if (key === "engine")
+            continue;
+        if (Object.hasOwn(fields, key))
+            fields[key]();
+        else
+            data(key, userConfig[key]);
+    }
+    // Redefining a spread key keeps its position, as the object literal does.
+    for (const key of RESOLVED_KEYS)
+        fields[key]();
+    return config;
+}
+//# sourceMappingURL=config-view.js.map

package/dist/facade/constants.d.ts

@@ -0,0 +1,22 @@
+/** `@teacss/engine`'s own package.json version; the facade `generator.version` without a host. */
+export declare const ENGINE_PACKAGE_VERSION: string;
+/** `package.json#engineCompat` (v02.11 §7.3); without it `core` is unrestricted and `defaultMode` is `"auto"`. */
+export declare const ENGINE_COMPAT: Readonly<{
+    core: string | undefined;
+    defaultMode: "opt-in" | "auto";
+    oracle: {
+        teacssTs: string;
+        commit: string;
+    } | undefined;
+}>;
+export declare const ENGINE_INSTANCE: unique symbol;
+export declare const ENGINE_MATERIALIZE: unique symbol;
+export declare const ENGINE_STATS: unique symbol;
+export declare const PRESET_OPTIONS: Readonly<{
+    standard: symbol;
+    icons: symbol;
+    official: symbol;
+}>;
+export declare const CONFIG_SOURCE_DECLARATIONS: unique symbol;
+export declare const CONFIG_ENTRY_PROVENANCE: unique symbol;
+//# sourceMappingURL=constants.d.ts.map

package/{src/facade/constants.mjs → dist/facade/constants.js}

@@ -1,24 +1,23 @@
-// @ts-check
 // The facade's symbols and package constants. It imports nothing from the facade, so every
-// facade module can import it without a cycle through `index.mjs`.
+// facade module can import it without a cycle through `index.ts`.
 import { createRequire } from "node:module";
-
-/** @type {{ version: string, engineCompat?: { core?: string, defaultMode?: "opt-in" | "auto" } }} */
 const pkg = createRequire(import.meta.url)("../../package.json");
-
 /** `@teacss/engine`'s own package.json version; the facade `generator.version` without a host. */
 export const ENGINE_PACKAGE_VERSION = pkg.version;
-
 /** `package.json#engineCompat` (v02.11 §7.3); without it `core` is unrestricted and `defaultMode` is `"auto"`. */
-export const ENGINE_COMPAT = Object.freeze({ core: pkg.engineCompat?.core, defaultMode: pkg.engineCompat?.defaultMode ?? "auto", oracle: /** @type {any} */ (pkg.engineCompat)?.oracle });
-
+export const ENGINE_COMPAT = Object.freeze({
+    core: pkg.engineCompat?.core,
+    defaultMode: pkg.engineCompat?.defaultMode ?? "auto",
+    oracle: pkg.engineCompat?.oracle,
+});
 export const ENGINE_INSTANCE = Symbol.for("@teacss/engine/instance");
 export const ENGINE_MATERIALIZE = Symbol.for("@teacss/engine/materialize");
 export const ENGINE_STATS = Symbol.for("@teacss/engine/stats");
 export const PRESET_OPTIONS = Object.freeze({
-  standard: Symbol.for("@teacss/preset-standard/options"),
-  icons: Symbol.for("@teacss/preset-icons/options"),
-  official: Symbol.for("@teacss/preset-official/options"),
+    standard: Symbol.for("@teacss/preset-standard/options"),
+    icons: Symbol.for("@teacss/preset-icons/options"),
+    official: Symbol.for("@teacss/preset-official/options"),
 });
 export const CONFIG_SOURCE_DECLARATIONS = Symbol.for("@teacss/config/source-declarations");
 export const CONFIG_ENTRY_PROVENANCE = Symbol.for("@teacss/config/entry-provenance");
+//# sourceMappingURL=constants.js.map

package/dist/facade/countable-set.d.ts

@@ -0,0 +1,43 @@
+export declare const MAX_RUNTIME_CACHE_ENTRIES = 10000;
+export declare class CountableSet<K> extends Set<K> {
+    _map: Map<K, number>;
+    constructor(values?: Iterable<K>);
+    add(key: K): this;
+    delete(key: K): boolean;
+    clear(): void;
+    getCount(key: K): number;
+    setCount(key: K, count: number): this;
+}
+export declare function isCountableSet(value: unknown): value is CountableSet<string>;
+export declare function copyCountableSet<K>(input: CountableSet<K>): CountableSet<K>;
+/**
+ * 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 declare function expandInputGroups<T extends Set<string>>(tokens: T): T;
+/**
+ * The part of the oracle `BoundedMap` the facade uses: ordinary keys are evicted oldest first,
+ * retained keys never count toward the limit.
+ */
+export declare class BoundedTokenCache<V> extends Map<string, V> {
+    #private;
+    maxEntries: number;
+    retained: Set<string>;
+    /** Ordinary keys in insertion order, the order the native map iterates them. */
+    order: Set<string>;
+    constructor(maxEntries?: number);
+    get retainedSize(): number;
+    isRetained(key: string): boolean;
+    set(key: string, value: V): this;
+    delete(key: string): boolean;
+    clear(): void;
+    /** Replaces the retained entries (bounded-cache.ts:188-205 without the revision check). */
+    replaceRetained(entries: Iterable<readonly [string, V]>): void;
+}
+/** FIFO bounded Set (the oracle `BoundedSet` without its `assumeNoPrototypeBypass` fast path). */
+export declare class BoundedSet extends Set<string> {
+    maxEntries: number;
+    constructor(maxEntries?: number, values?: Iterable<string>);
+    add(value: string): this;
+}
+//# sourceMappingURL=countable-set.d.ts.map

package/dist/facade/countable-set.js

@@ -0,0 +1,149 @@
+// 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 part of the oracle `BoundedMap` the facade uses: ordinary keys are evicted oldest first,
+ * retained keys never count toward the limit.
+ */
+export class BoundedTokenCache extends Map {
+    constructor(maxEntries = MAX_RUNTIME_CACHE_ENTRIES) {
+        super();
+        this.maxEntries = maxEntries;
+        this.retained = new Set();
+        this.order = new Set();
+    }
+    get retainedSize() {
+        return this.retained.size;
+    }
+    isRetained(key) {
+        return this.retained.has(key);
+    }
+    set(key, value) {
+        const exists = super.has(key);
+        super.set(key, value);
+        if (!exists && !this.retained.has(key))
+            this.order.add(key);
+        this.#enforceLimit();
+        return this;
+    }
+    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) {
+        const next = new Map(entries);
+        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);
+            super.set(key, value);
+            this.retained.add(key);
+        }
+        this.#enforceLimit();
+    }
+    #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/facade/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/facade/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/facade/generator.d.ts

@@ -0,0 +1,153 @@
+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;
+    } | 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