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

package/src/facade/ts-fallback.mjs

@@ -0,0 +1,78 @@
+// @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));
+  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 binding.createGenerator(committed.userConfig, { ...committed.defaults, engine: "ts" });
+        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" };
+      // The base is built from the configuration itself: Rust cannot translate it, so it is a TS
+      // generator even when TEACSS_ENGINE overrides `engine: "ts"`, and no Engine is created.
+      const base = await binding.createGenerator(userConfig, tsDefaults);
+      if (ENGINE_INSTANCE in Object(base) || typeof base?.prepareConfig !== "function") return base;
+      return (await base.prepareConfig(userConfig, tsDefaults)).generator;
+    },
+  };
+}