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

package/src/facade/ts-fallback.mjs

@@ -0,0 +1,88 @@
+// @ts-check
+// The lazily created TypeScript generator behind the facade (v02.9 §3.3).
+
+import { ENGINE_INSTANCE } from "./constants.mjs";
+import { tsRequiredError } from "./errors.mjs";
+
+/** @typedef {{ version: string, createGenerator: (config?: object, defaults?: object) => Promise<any>, extractorSplit: object }} CoreBinding */
+
+/** Test seam that replaces the dynamic import of `@teacss/core`. */
+export const coreLoader = {
+  /** @type {(() => Promise<CoreBinding>) | null} */
+  load: null,
+};
+
+/** @param {string} member @returns {Promise<CoreBinding>} rejects with `E_TS_REQUIRED` when the peer is missing */
+export async function importCore(member) {
+  try {
+    // @ts-ignore optional peer
+    return await (coreLoader.load ? coreLoader.load() : import("@teacss/core"));
+  } catch {
+    throw tsRequiredError(member);
+  }
+}
+
+/**
+ * `engine: "ts"` goes into the defaults, which take precedence over `config.engine`, so the TS
+ * generator does not enter the hook again.
+ * @param {{ core?: CoreBinding | undefined }} host
+ * @param {{ userConfig: object, defaults: object }} committed the configuration committed at construction
+ */
+export function createTsFallback(host, committed) {
+  /** @type {Promise<any> | null} */
+  let generatorPromise = null;
+  /** @type {any} */
+  let resolved = null;
+  /** @param {string} member */
+  const core = (member) => (host.core ? Promise.resolve(host.core) : importCore(member));
+  /**
+   * A TypeScript generator. The hook's `createTsGenerator` bypasses it; `createGenerator` (an older
+   * core, or `@teacss/core` imported without a hook) re-enters it when TEACSS_ENGINE overrides
+   * `engine: "ts"`, and returns a facade for a configuration Rust can serve.
+   * @param {any} binding @param {object} userConfig @param {object} defaults
+   */
+  const createTs = (binding, userConfig, defaults) => {
+    const tsDefaults = { ...defaults, engine: "ts" };
+    return typeof binding.createTsGenerator === "function" ? binding.createTsGenerator(userConfig, tsDefaults) : binding.createGenerator(userConfig, tsDefaults);
+  };
+  return {
+    /** Called after a successful `commitConfig`; drops the lazy instance. @param {object} userConfig @param {object} defaults */
+    invalidate(userConfig, defaults) {
+      committed = { userConfig, defaults };
+      generatorPromise = null;
+      resolved = null;
+    },
+    /** The lazy TS generator; a rejection is not cached. @param {string} [member] */
+    generator(member = "materialize") {
+      generatorPromise ??= (async () => {
+        const binding = await core(member);
+        const generator = await createTs(binding, committed.userConfig, committed.defaults);
+        resolved = generator;
+        return generator;
+      })().catch((error) => {
+        generatorPromise = null;
+        throw error;
+      });
+      return generatorPromise;
+    },
+    /** The ready instance, or `null` before `generator()` resolves. */
+    peek() {
+      return resolved;
+    },
+    /**
+     * A TS candidate for a configuration (v02.9 §5.2), made by the TS generator's own
+     * `prepareConfig` so it tracks in-place edits of its config as an oracle candidate does
+     * (generator.ts:1986-2011). The lazy instance is untouched.
+     * @param {object} userConfig @param {object} defaults
+     */
+    async create(userConfig, defaults) {
+      const binding = await core("prepareConfig");
+      const tsDefaults = { ...defaults, engine: "ts" };
+      // Without `createTsGenerator` the base is built from the configuration itself: Rust cannot
+      // translate it, so `createGenerator` resolves to TS and creates no Engine.
+      const base = await createTs(binding, typeof binding.createTsGenerator === "function" ? {} : userConfig, defaults);
+      if (ENGINE_INSTANCE in Object(base) || typeof base?.prepareConfig !== "function") return base;
+      return (await base.prepareConfig(userConfig, tsDefaults)).generator;
+    },
+  };
+}