@teacss/engine 0.0.0-stage → 0.8.5-alpha.1

package/src/facade/countable-set.mjs

@@ -0,0 +1,179 @@
+// @ts-check
+// 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;
+
+/** @template K @extends {Set<K>} */
+export class CountableSet extends Set {
+  /** @type {Map<K, number>} */
+  _map = new Map();
+
+  /** @param {Iterable<K>} [values] */
+  constructor(values) {
+    super();
+    if (values) for (const key of values) this.add(key);
+  }
+
+  /** @param {K} key */
+  add(key) {
+    this._map.set(key, (this._map.get(key) ?? 0) + 1);
+    return super.add(key);
+  }
+
+  /** @param {K} key */
+  delete(key) {
+    if (!this._map.has(key)) return false;
+    this._map.delete(key);
+    return super.delete(key);
+  }
+
+  clear() {
+    this._map.clear();
+    super.clear();
+  }
+
+  /** @param {K} key */
+  getCount(key) {
+    return this._map.get(key) ?? 0;
+  }
+
+  /** @param {K} key @param {number} count */
+  setCount(key, count) {
+    this._map.set(key, count);
+    return super.add(key);
+  }
+}
+
+/** @param {unknown} value @returns {value is CountableSet<string>} */
+export function isCountableSet(value) {
+  return value instanceof CountableSet;
+}
+
+/** @template K @param {CountableSet<K>} input */
+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.
+ * @template {Set<string>} T @param {T} tokens @returns {T}
+ */
+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.
+ * @template V @extends {Map<string, V>}
+ */
+export class BoundedTokenCache extends Map {
+  /** @param {number} [maxEntries] */
+  constructor(maxEntries = MAX_RUNTIME_CACHE_ENTRIES) {
+    super();
+    this.maxEntries = maxEntries;
+    /** @type {Set<string>} */
+    this.retained = new Set();
+    /** Ordinary keys in insertion order, the order the native map iterates them. @type {Set<string>} */
+    this.order = new Set();
+  }
+
+  get retainedSize() {
+    return this.retained.size;
+  }
+
+  /** @param {string} key */
+  isRetained(key) {
+    return this.retained.has(key);
+  }
+
+  /** @param {string} key @param {V} value */
+  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;
+  }
+
+  /** @param {string} key */
+  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).
+   * @param {Iterable<readonly [string, V]>} entries
+   */
+  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). @extends {Set<string>} */
+export class BoundedSet extends Set {
+  /** @param {number} [maxEntries] @param {Iterable<string>} [values] */
+  constructor(maxEntries = MAX_RUNTIME_CACHE_ENTRIES, values) {
+    super();
+    this.maxEntries = maxEntries;
+    if (values) for (const value of values) this.add(value);
+  }
+
+  /** @param {string} 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;
+  }
+}

package/src/facade/errors.mjs

@@ -0,0 +1,22 @@
+// @ts-check
+
+/** Errors the facade raises itself; an `Error` from napi (code `E_*`) passes through unwrapped. */
+export class TeacssEngineError extends Error {
+  /** @param {string} code @param {string} message @param {Record<string, unknown>} [details] */
+  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. @param {string} member */
+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. @param {string} member */
+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 });
+}