@cfasim-ui/docs 0.3.11

package/pyodide/pyodideWorkerApi.ts

@@ -0,0 +1,102 @@
+import type { TransferableResponse } from "@cfasim-ui/shared";
+import { unwrapResponse } from "@cfasim-ui/shared";
+
+interface PromiseResolver<T> {
+  promise: Promise<T>;
+  resolve: (value: T) => void;
+}
+
+function getPromiseAndResolve<T>(): PromiseResolver<T> {
+  let resolve: (value: T) => void;
+  const promise = new Promise<T>((res) => {
+    resolve = res;
+  });
+  return { promise, resolve: resolve! };
+}
+
+let lastId = 0;
+function getId(): number {
+  return ++lastId;
+}
+
+interface WorkerMessage {
+  id: number;
+  type?: "run" | "loadModule";
+  python?: string;
+  module?: string;
+  context?: Record<string, unknown>;
+}
+
+function requestResponse(
+  worker: Worker,
+  msg: Omit<WorkerMessage, "id">,
+): Promise<{ result?: unknown; error?: string }> {
+  const { promise, resolve } = getPromiseAndResolve<{
+    result?: unknown;
+    error?: string;
+  }>();
+  const idWorker = getId();
+
+  function listener(event: MessageEvent<TransferableResponse>) {
+    if (event.data?.id !== idWorker) {
+      return;
+    }
+    worker.removeEventListener("message", listener);
+    if (event.data.error) {
+      resolve({ error: event.data.error });
+    } else {
+      resolve({ result: unwrapResponse(event.data) });
+    }
+  }
+
+  worker.addEventListener("message", listener);
+  worker.postMessage({ id: idWorker, ...msg } as WorkerMessage);
+  return promise;
+}
+
+export type WorkerName = "baseline" | "intervention";
+
+function createWorker(): Worker {
+  return new Worker(new URL("./pyodide.worker.ts", import.meta.url), {
+    type: "module",
+  });
+}
+
+const workers: Record<WorkerName, Worker> = {
+  baseline: createWorker(),
+  intervention: createWorker(),
+};
+
+export async function loadModuleOnWorker(
+  moduleName: string,
+  worker: WorkerName,
+): Promise<{ result?: unknown; error?: string }> {
+  return requestResponse(workers[worker], {
+    type: "loadModule",
+    module: moduleName,
+  });
+}
+
+export async function loadModule(
+  moduleName: string,
+): Promise<{ result?: unknown; error?: string }> {
+  // Load module on all workers so any worker can run code that depends on it
+  const results = await Promise.all(
+    Object.values(workers).map((w) =>
+      requestResponse(w, { type: "loadModule", module: moduleName }),
+    ),
+  );
+  return results[0];
+}
+
+export async function asyncRunPython(
+  script: string,
+  context?: Record<string, unknown>,
+  worker?: WorkerName,
+): Promise<{ result?: unknown; error?: string }> {
+  const target = worker ? workers[worker] : workers.baseline;
+  return requestResponse(target, {
+    python: script,
+    context,
+  });
+}

package/pyodide/useModel.ts

@@ -0,0 +1,86 @@
+import { ref, toRaw, toValue, watch } from "vue";
+import type { MaybeRef } from "vue";
+import type { ModelOutput } from "@cfasim-ui/shared";
+import { asyncRunPython, loadModule } from "./pyodideWorkerApi.js";
+
+export function useModel<T = unknown>(moduleName: string) {
+  const result = ref<T>();
+  const error = ref<string>();
+  const loading = ref(true);
+
+  const loaded = loadModule(moduleName);
+  loaded.then(() => {
+    loading.value = false;
+  });
+
+  async function run(fn: string, context?: Record<string, unknown>) {
+    loading.value = true;
+    error.value = undefined;
+    try {
+      await loaded;
+      const argNames = context ? Object.keys(context) : [];
+      const callArgs = argNames.join(", ");
+      const plainContext = context
+        ? Object.fromEntries(
+            Object.entries(context).map(([k, v]) => [k, toRaw(v)]),
+          )
+        : undefined;
+      const response = await asyncRunPython(
+        `import ${moduleName}\n${moduleName}.${fn}(${callArgs})`,
+        plainContext,
+      );
+      if (response.error) {
+        error.value = response.error;
+      } else {
+        result.value = response.result as T;
+      }
+    } catch (e) {
+      error.value = e instanceof Error ? e.message : String(e);
+    } finally {
+      loading.value = false;
+    }
+  }
+
+  function useOutputs<P extends Record<string, unknown>>(
+    fn: string,
+    params: MaybeRef<P>,
+  ) {
+    const outputs = ref<Record<string, ModelOutput>>();
+    const outputsError = ref<string>();
+    const outputsLoading = ref(true);
+
+    watch(
+      () => toValue(params),
+      async (p) => {
+        outputsLoading.value = true;
+        outputsError.value = undefined;
+        try {
+          await loaded;
+          const plain = Object.fromEntries(
+            Object.entries(p).map(([k, v]) => [k, toRaw(v)]),
+          );
+          const argNames = Object.keys(plain);
+          const callArgs = argNames.join(", ");
+          const response = await asyncRunPython(
+            `import ${moduleName}\n${moduleName}.${fn}(${callArgs})`,
+            plain,
+          );
+          if (response.error) {
+            outputsError.value = response.error;
+          } else {
+            outputs.value = response.result as Record<string, ModelOutput>;
+          }
+        } catch (e) {
+          outputsError.value = e instanceof Error ? e.message : String(e);
+        } finally {
+          outputsLoading.value = false;
+        }
+      },
+      { immediate: true, deep: true },
+    );
+
+    return { outputs, error: outputsError, loading: outputsLoading };
+  }
+
+  return { run, result, error, loading, useOutputs };
+}

package/pyodide/vitePlugin.js

@@ -0,0 +1,51 @@
+import { execSync } from "node:child_process";
+import { readdirSync, writeFileSync, mkdirSync } from "node:fs";
+import { resolve } from "node:path";
+
+/**
+ * @typedef {object} CfasimPyodideOptions
+ * @property {string} [model] Path to the Python model directory (default: "model")
+ * @property {string[]} [pypiDeps] PyPI packages to download at build time and serve locally
+ * @property {string} [pipCommand] Command used to invoke pip for downloading `pypiDeps` (default: "uvx pip"). Override with e.g. "pip" or "uv run pip".
+ * @property {string} [pythonVersion] Python version passed to pip's --python-version flag when downloading `pypiDeps` (default: "3.12"). Should match the Python shipped by your Pyodide runtime.
+ */
+
+/**
+ * Vite plugin that builds a Python wheel from a local model directory
+ * and generates wheels.json in the public directory.
+ *
+ * Use `pypiDeps` to prebuild PyPI packages (like cfasim-model) as local
+ * wheels for faster browser runtime — avoids PyPI round-trips on page load.
+ *
+ * @param {CfasimPyodideOptions} [options]
+ * @returns {import("vite").Plugin}
+ */
+export function cfasimPyodide(options) {
+  const modelDir = options?.model ?? "model";
+  const pipCommand = options?.pipCommand ?? "uvx pip";
+  const pythonVersion = options?.pythonVersion ?? "3.12";
+
+  function build(root) {
+    const publicDir = resolve(root, "public");
+    mkdirSync(publicDir, { recursive: true });
+    for (const dep of options?.pypiDeps ?? []) {
+      execSync(
+        `${pipCommand} download ${dep} --dest public --no-deps --python-version ${pythonVersion} --platform any`,
+        { cwd: root, stdio: "pipe" },
+      );
+    }
+    execSync(`uv build ${modelDir} --wheel --out-dir public`, {
+      cwd: root,
+      stdio: "pipe",
+    });
+    const wheels = readdirSync(publicDir).filter((f) => f.endsWith(".whl"));
+    writeFileSync(resolve(publicDir, "wheels.json"), JSON.stringify(wheels));
+  }
+
+  return {
+    name: "cfasim-pyodide",
+    configResolved(config) {
+      build(config.root);
+    },
+  };
+}

package/shared/ModelOutput.ts

@@ -0,0 +1,88 @@
+export type ColumnType = "i32" | "u32" | "f64" | "bool" | "enum";
+
+export interface ColumnDescriptor {
+  name: string;
+  type: ColumnType;
+  enumLabels?: string[];
+}
+
+export type TypedColumn = Float64Array | Int32Array | Uint32Array | Uint8Array;
+
+export interface ModelOutputWire {
+  __modelOutput: true;
+  length: number;
+  columns: ColumnDescriptor[];
+  buffers: ArrayBuffer[];
+}
+
+export interface ModelOutputsWire {
+  __modelOutputs: true;
+  outputs: Record<string, ModelOutputWire>;
+}
+
+const COLUMN_TYPE_TO_CTOR: Record<
+  ColumnType,
+  new (buffer: ArrayBuffer) => TypedColumn
+> = {
+  f64: Float64Array,
+  i32: Int32Array,
+  u32: Uint32Array,
+  bool: Uint8Array,
+  enum: Uint32Array,
+};
+
+export class ModelOutput {
+  readonly length: number;
+  readonly columns: readonly ColumnDescriptor[];
+  readonly buffers: readonly TypedColumn[];
+
+  constructor(
+    length: number,
+    columns: ColumnDescriptor[],
+    buffers: TypedColumn[],
+  ) {
+    this.length = length;
+    this.columns = columns;
+    this.buffers = buffers;
+  }
+
+  column(name: string): TypedColumn {
+    const idx = this.columns.findIndex((c) => c.name === name);
+    if (idx === -1) throw new Error(`Unknown column: ${name}`);
+    return this.buffers[idx];
+  }
+
+  descriptor(name: string): ColumnDescriptor {
+    const idx = this.columns.findIndex((c) => c.name === name);
+    if (idx === -1) throw new Error(`Unknown column: ${name}`);
+    return this.columns[idx];
+  }
+
+  label(columnName: string, index: number): string {
+    const desc = this.descriptor(columnName);
+    if (desc.type !== "enum" || !desc.enumLabels) {
+      throw new Error(`Column ${columnName} is not an enum`);
+    }
+    return desc.enumLabels[index];
+  }
+
+  get names(): string[] {
+    return this.columns.map((c) => c.name);
+  }
+
+  static fromWire(wire: ModelOutputWire): ModelOutput {
+    const typed = wire.columns.map((col, i) => {
+      const Ctor = COLUMN_TYPE_TO_CTOR[col.type];
+      return new Ctor(wire.buffers[i]);
+    });
+    return new ModelOutput(wire.length, wire.columns, typed);
+  }
+
+  static recordFromWire(wire: ModelOutputsWire): Record<string, ModelOutput> {
+    const result: Record<string, ModelOutput> = {};
+    for (const [key, outputWire] of Object.entries(wire.outputs)) {
+      result[key] = ModelOutput.fromWire(outputWire);
+    }
+    return result;
+  }
+}

package/shared/csv.ts

@@ -0,0 +1,22 @@
+import type { ModelOutput } from "./ModelOutput.js";
+
+export function modelOutputToCSV(output: ModelOutput): string {
+  const header = output.names.join(",");
+  const rows: string[] = [header];
+  for (let r = 0; r < output.length; r++) {
+    const cells: string[] = [];
+    for (let c = 0; c < output.columns.length; c++) {
+      const desc = output.columns[c];
+      const val = output.buffers[c][r];
+      if (desc.type === "enum") {
+        cells.push(desc.enumLabels![val as number]);
+      } else if (desc.type === "bool") {
+        cells.push(val ? "true" : "false");
+      } else {
+        cells.push(String(val));
+      }
+    }
+    rows.push(cells.join(","));
+  }
+  return rows.join("\n");
+}

package/shared/index.ts

@@ -0,0 +1,24 @@
+export {
+  postWithTransfer,
+  postModelOutputsWithTransfer,
+  postErrorWithTransfer,
+  unwrapResponse,
+} from "./transferUtils.js";
+export type { TransferableResponse } from "./transferUtils.js";
+export { ModelOutput } from "./ModelOutput.js";
+export type {
+  ColumnDescriptor,
+  ColumnType,
+  TypedColumn,
+  ModelOutputWire,
+  ModelOutputsWire,
+} from "./ModelOutput.js";
+export { modelOutputToCSV } from "./csv.js";
+export {
+  useUrlParams,
+  serialize,
+  deserialize,
+  paramsToQuery,
+  queryToParams,
+} from "./useUrlParams.js";
+export type { UrlParamsOptions } from "./useUrlParams.js";

package/shared/transferUtils.ts

@@ -0,0 +1,126 @@
+import type { ColumnDescriptor, ModelOutputsWire } from "./ModelOutput.js";
+import { ModelOutput } from "./ModelOutput.js";
+
+interface ModelOutputsResponsePayload {
+  outputs: Record<
+    string,
+    { length: number; columns: ColumnDescriptor[]; buffers: ArrayBuffer[] }
+  >;
+}
+
+export interface TransferableResponse {
+  id: number;
+  result?: unknown;
+  buffer?: ArrayBuffer;
+  bufferType?: string;
+  modelOutputs?: ModelOutputsResponsePayload;
+  error?: string;
+}
+
+const TYPED_ARRAY_CONSTRUCTORS: Record<
+  string,
+  new (buffer: ArrayBuffer) => ArrayBufferView
+> = {
+  Int8Array,
+  Uint8Array,
+  Uint8ClampedArray,
+  Int16Array,
+  Uint16Array,
+  Int32Array,
+  Uint32Array,
+  Float32Array,
+  Float64Array,
+  BigInt64Array,
+  BigUint64Array,
+};
+
+function isTypedArray(value: unknown): value is ArrayBufferView {
+  return ArrayBuffer.isView(value) && !(value instanceof DataView);
+}
+
+export function postWithTransfer(
+  port: typeof globalThis,
+  id: number,
+  result: unknown,
+): void {
+  if (result instanceof ArrayBuffer) {
+    port.postMessage(
+      {
+        id,
+        buffer: result,
+        bufferType: "ArrayBuffer",
+      } satisfies TransferableResponse,
+      { transfer: [result] },
+    );
+  } else if (isTypedArray(result)) {
+    const buffer = result.buffer as ArrayBuffer;
+    port.postMessage(
+      {
+        id,
+        buffer,
+        bufferType: result.constructor.name,
+      } satisfies TransferableResponse,
+      { transfer: [buffer] },
+    );
+  } else {
+    port.postMessage({ id, result } satisfies TransferableResponse);
+  }
+}
+
+export function postModelOutputsWithTransfer(
+  port: typeof globalThis,
+  id: number,
+  wire: ModelOutputsWire,
+): void {
+  const transferList: ArrayBuffer[] = [];
+  const outputs: ModelOutputsResponsePayload["outputs"] = {};
+
+  for (const [key, outputWire] of Object.entries(wire.outputs)) {
+    outputs[key] = {
+      length: outputWire.length,
+      columns: outputWire.columns,
+      buffers: outputWire.buffers,
+    };
+    transferList.push(...outputWire.buffers);
+  }
+
+  port.postMessage(
+    { id, modelOutputs: { outputs } } satisfies TransferableResponse,
+    { transfer: transferList },
+  );
+}
+
+export function postErrorWithTransfer(
+  port: typeof globalThis,
+  id: number,
+  error: unknown,
+): void {
+  port.postMessage({
+    id,
+    error: error instanceof Error ? error.message : String(error),
+  } satisfies TransferableResponse);
+}
+
+export function unwrapResponse(data: TransferableResponse): unknown {
+  if (data.modelOutputs) {
+    return ModelOutput.recordFromWire({
+      __modelOutputs: true,
+      outputs: data.modelOutputs.outputs as Record<
+        string,
+        {
+          __modelOutput: true;
+          length: number;
+          columns: ColumnDescriptor[];
+          buffers: ArrayBuffer[];
+        }
+      >,
+    });
+  }
+  if (data.buffer != null) {
+    if (data.bufferType === "ArrayBuffer") return data.buffer;
+    const Ctor = TYPED_ARRAY_CONSTRUCTORS[data.bufferType!];
+    if (Ctor) return new Ctor(data.buffer);
+    return data.buffer;
+  }
+  return data.result;
+}