rastack 0.0.16 → 0.0.19

package/provider/provider.tsx

@@ -1,187 +1,187 @@
-import React, {
-  createContext,
-  ReactNode,
-  useContext,
-  useEffect,
-  useMemo,
-  useRef,
-  useState,
-} from "react";
-import { API, configureApi, resetApi } from "../hooks/query/api";
-import {
-  RadClient,
-  RadEngine,
-  RAStackProviderConfig,
-  RadStatus,
-  WarehouseSource,
-} from "./types";
-import { createEngine, createWasmAdapter, defaultEngineLoader } from "./wasm";
-import {
-  debounce,
-  downloadBlob,
-  manifestResources,
-  seedFromIceberg,
-  WarehousePersistence,
-} from "./warehouse";
-
-const RadContext = createContext<RadClient | null>(null);
-
-/**
- * The one place a React app configures *where the API runs* — over HTTP
- * (`remote`), in the browser via WebAssembly (`local`), or in the browser
- * against S3 (`s3`). It reconfigures the shared axios client in place, so every
- * generated hook keeps working with no changes.
- *
- * ```tsx
- * <RAStackProvider mode="local" manifest={schema} warehouseBaseUrl="/data/warehouse/">
- *   <App />
- * </RAStackProvider>
- * ```
- */
-export function RAStackProvider({
-  children,
-  ...config
-}: RAStackProviderConfig & { children: ReactNode }): JSX.Element {
-  const [status, setStatus] = useState<RadStatus>("idle");
-  const engineRef = useRef<RadEngine | null>(null);
-  const persistRef = useRef<(() => void) & { flush: () => void }>();
-
-  const setStatusSafe = (next: RadStatus) => {
-    setStatus(next);
-    config.onStatusChange?.(next);
-  };
-
-  useEffect(() => {
-    let cancelled = false;
-    let ejectToken: number | undefined;
-
-    async function setup() {
-      // Bearer-token interceptor works in every mode.
-      if (config.getToken) {
-        ejectToken = API.interceptors.request.use(async (request) => {
-          const token = await config.getToken!();
-          request.headers = request.headers || ({} as any);
-          (request.headers as any).Authorization = `Bearer ${token}`;
-          return request;
-        });
-      }
-
-      if (config.mode === "remote") {
-        configureApi({ baseURL: config.baseURL ?? "", adapter: null });
-        if (config.baseURL === undefined) resetApi();
-        setStatusSafe("ready");
-        return;
-      }
-
-      // -- WASM modes (local / s3) --
-      if (!config.manifest) {
-        throw new Error("RAStackProvider: `manifest` is required in local/s3 mode.");
-      }
-
-      setStatusSafe("loading");
-      const loader = config.loadEngine ?? defaultEngineLoader;
-      const mod = await loader();
-      if (cancelled) return;
-      const engine = createEngine(mod, config.manifest, config.openapi);
-
-      // Warehouse persistence: IndexedDB for `local`, an S3 sink for `s3`.
-      const persistence = pickPersistence(config);
-
-      setStatusSafe("seeding");
-      // A persisted local copy (with the user's edits) wins; otherwise seed
-      // from the committed Iceberg warehouse — a directory of files walked over
-      // HTTP, not a blob.
-      const existing = await persistence.load();
-      if (existing) {
-        await engine.importWarehouse(existing);
-      } else {
-        const base = config.warehouseBaseUrl ?? "/data/warehouse/";
-        await seedFromIceberg(engine, base, manifestResources(config.manifest));
-      }
-      if (cancelled) return;
-
-      const persist = debounce(() => {
-        void engine
-          .exportWarehouse()
-          .then((blob) => persistence.save(blob))
-          .catch((error) => config.onError?.(error));
-      }, 400);
-      persistRef.current = persist;
-
-      engineRef.current = engine;
-      configureApi({ baseURL: "", adapter: createWasmAdapter(engine, persist) });
-      setStatusSafe("ready");
-    }
-
-    setup().catch((error) => {
-      if (cancelled) return;
-      config.onError?.(error);
-      setStatusSafe("error");
-    });
-
-    return () => {
-      cancelled = true;
-      persistRef.current?.flush();
-      if (ejectToken !== undefined) API.interceptors.request.eject(ejectToken);
-      resetApi();
-      engineRef.current = null;
-    };
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [config.mode, config.baseURL, config.warehouseBaseUrl]);
-
-  const client = useMemo<RadClient>(
-    () => ({
-      mode: config.mode,
-      status,
-      get engine() {
-        return engineRef.current;
-      },
-      async exportWarehouse() {
-        if (!engineRef.current) {
-          throw new Error("exportWarehouse is only available in local/s3 mode.");
-        }
-        return engineRef.current.exportWarehouse();
-      },
-      async downloadWarehouse(filename = "warehouse-snapshot.json") {
-        const blob = await this.exportWarehouse();
-        downloadBlob(blob, filename);
-      },
-      async persistNow() {
-        persistRef.current?.flush();
-      },
-    }),
-    [config.mode, status],
-  );
-
-  return <RadContext.Provider value={client}>{children}</RadContext.Provider>;
-}
-
-function pickPersistence(config: RAStackProviderConfig): WarehouseSource {
-  if (config.mode === "s3") {
-    if (!config.warehouse) {
-      throw new Error(
-        "RAStackProvider: `warehouse` (a WarehouseSource over S3) is required in s3 mode.",
-      );
-    }
-    return config.warehouse;
-  }
-  if (config.persist === false) {
-    return { load: async () => null, save: async () => {} };
-  }
-  const store = new WarehousePersistence(config.databaseName || "rad-warehouse");
-  return { load: () => store.load(), save: (blob) => store.save(blob) };
-}
-
-/** Access the imperative Rad client (engine, status, warehouse helpers). */
-export function useRadClient(): RadClient {
-  const client = useContext(RadContext);
-  if (!client) {
-    throw new Error("useRadClient must be used within a <RAStackProvider>.");
-  }
-  return client;
-}
-
-/** Just the current status — handy for a loading gate while WASM boots. */
-export function useRadStatus(): RadStatus {
-  return useRadClient().status;
-}
+import React, {
+  createContext,
+  ReactNode,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+} from "react";
+import { API, configureApi, resetApi } from "../hooks/query/api";
+import {
+  RadClient,
+  RadEngine,
+  RAStackProviderConfig,
+  RadStatus,
+  WarehouseSource,
+} from "./types";
+import { createEngine, createWasmAdapter, defaultEngineLoader } from "./wasm";
+import {
+  debounce,
+  downloadBlob,
+  manifestResources,
+  seedFromIceberg,
+  WarehousePersistence,
+} from "./warehouse";
+
+const RadContext = createContext<RadClient | null>(null);
+
+/**
+ * The one place a React app configures *where the API runs* — over HTTP
+ * (`remote`), in the browser via WebAssembly (`local`), or in the browser
+ * against S3 (`s3`). It reconfigures the shared axios client in place, so every
+ * generated hook keeps working with no changes.
+ *
+ * ```tsx
+ * <RAStackProvider mode="local" manifest={schema} warehouseBaseUrl="/data/warehouse/">
+ *   <App />
+ * </RAStackProvider>
+ * ```
+ */
+export function RAStackProvider({
+  children,
+  ...config
+}: RAStackProviderConfig & { children: ReactNode }): JSX.Element {
+  const [status, setStatus] = useState<RadStatus>("idle");
+  const engineRef = useRef<RadEngine | null>(null);
+  const persistRef = useRef<(() => void) & { flush: () => void }>();
+
+  const setStatusSafe = (next: RadStatus) => {
+    setStatus(next);
+    config.onStatusChange?.(next);
+  };
+
+  useEffect(() => {
+    let cancelled = false;
+    let ejectToken: number | undefined;
+
+    async function setup() {
+      // Bearer-token interceptor works in every mode.
+      if (config.getToken) {
+        ejectToken = API.interceptors.request.use(async (request) => {
+          const token = await config.getToken!();
+          request.headers = request.headers || ({} as any);
+          (request.headers as any).Authorization = `Bearer ${token}`;
+          return request;
+        });
+      }
+
+      if (config.mode === "remote") {
+        configureApi({ baseURL: config.baseURL ?? "", adapter: null });
+        if (config.baseURL === undefined) resetApi();
+        setStatusSafe("ready");
+        return;
+      }
+
+      // -- WASM modes (local / s3) --
+      if (!config.manifest) {
+        throw new Error("RAStackProvider: `manifest` is required in local/s3 mode.");
+      }
+
+      setStatusSafe("loading");
+      const loader = config.loadEngine ?? defaultEngineLoader;
+      const mod = await loader();
+      if (cancelled) return;
+      const engine = createEngine(mod, config.manifest, config.openapi);
+
+      // Warehouse persistence: IndexedDB for `local`, an S3 sink for `s3`.
+      const persistence = pickPersistence(config);
+
+      setStatusSafe("seeding");
+      // A persisted local copy (with the user's edits) wins; otherwise seed
+      // from the committed Iceberg warehouse — a directory of files walked over
+      // HTTP, not a blob.
+      const existing = await persistence.load();
+      if (existing) {
+        await engine.importWarehouse(existing);
+      } else {
+        const base = config.warehouseBaseUrl ?? "/data/warehouse/";
+        await seedFromIceberg(engine, base, manifestResources(config.manifest));
+      }
+      if (cancelled) return;
+
+      const persist = debounce(() => {
+        void engine
+          .exportWarehouse()
+          .then((blob) => persistence.save(blob))
+          .catch((error) => config.onError?.(error));
+      }, 400);
+      persistRef.current = persist;
+
+      engineRef.current = engine;
+      configureApi({ baseURL: "", adapter: createWasmAdapter(engine, persist) });
+      setStatusSafe("ready");
+    }
+
+    setup().catch((error) => {
+      if (cancelled) return;
+      config.onError?.(error);
+      setStatusSafe("error");
+    });
+
+    return () => {
+      cancelled = true;
+      persistRef.current?.flush();
+      if (ejectToken !== undefined) API.interceptors.request.eject(ejectToken);
+      resetApi();
+      engineRef.current = null;
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [config.mode, config.baseURL, config.warehouseBaseUrl]);
+
+  const client = useMemo<RadClient>(
+    () => ({
+      mode: config.mode,
+      status,
+      get engine() {
+        return engineRef.current;
+      },
+      async exportWarehouse() {
+        if (!engineRef.current) {
+          throw new Error("exportWarehouse is only available in local/s3 mode.");
+        }
+        return engineRef.current.exportWarehouse();
+      },
+      async downloadWarehouse(filename = "warehouse-snapshot.json") {
+        const blob = await this.exportWarehouse();
+        downloadBlob(blob, filename);
+      },
+      async persistNow() {
+        persistRef.current?.flush();
+      },
+    }),
+    [config.mode, status],
+  );
+
+  return <RadContext.Provider value={client}>{children}</RadContext.Provider>;
+}
+
+function pickPersistence(config: RAStackProviderConfig): WarehouseSource {
+  if (config.mode === "s3") {
+    if (!config.warehouse) {
+      throw new Error(
+        "RAStackProvider: `warehouse` (a WarehouseSource over S3) is required in s3 mode.",
+      );
+    }
+    return config.warehouse;
+  }
+  if (config.persist === false) {
+    return { load: async () => null, save: async () => {} };
+  }
+  const store = new WarehousePersistence(config.databaseName || "rad-warehouse");
+  return { load: () => store.load(), save: (blob) => store.save(blob) };
+}
+
+/** Access the imperative Rad client (engine, status, warehouse helpers). */
+export function useRadClient(): RadClient {
+  const client = useContext(RadContext);
+  if (!client) {
+    throw new Error("useRadClient must be used within a <RAStackProvider>.");
+  }
+  return client;
+}
+
+/** Just the current status — handy for a loading gate while WASM boots. */
+export function useRadStatus(): RadStatus {
+  return useRadClient().status;
+}

package/provider/types.ts

@@ -1,114 +1,114 @@
-/**
- * Configuration for `<RAStackProvider>` — the single place a React app chooses
- * *where the API runs*:
- *
- * - `remote` — talk to the Rust API over HTTP (Lambda in prod, `rad serve`
- *   locally). The classic client/server split.
- * - `local`  — compile-free local development: the entire API runs in the
- *   browser via WebAssembly over an in-memory Iceberg warehouse, seeded from a
- *   repo `data/` folder and persisted to IndexedDB. No server, no network,
- *   instant reads/writes.
- * - `s3`     — full client mode: the same WASM engine, but the warehouse is
- *   loaded from and saved back to S3, so a static site reads and writes the
- *   object-storage database directly.
- */
-export type RadMode = "remote" | "local" | "s3";
-
-/** The subset of the WASM `RadApi` class the provider uses. */
-export interface RadEngine {
-  handle(
-    method: string,
-    path: string,
-    query: Record<string, string> | undefined,
-    body: unknown,
-  ): Promise<{ status: number; body: any }>;
-  /** Seed one Iceberg file (metadata or `.parquet` data file) at its key. */
-  seedFile(key: string, bytes: Uint8Array): Promise<void>;
-  importWarehouse(blob: Uint8Array): Promise<void>;
-  exportWarehouse(): Promise<Uint8Array>;
-}
-
-/** Constructor of the generated `RadApi` class. */
-export interface RadEngineCtor {
-  new (manifestJson: string, openapiJson?: string): RadEngine;
-}
-
-/** What a WASM bundle loader must resolve to. */
-export interface RadWasmModule {
-  /** wasm-pack `web` target exposes an init fn that fetches the `.wasm`. */
-  default?: (input?: any) => Promise<any>;
-  init?: (input?: any) => Promise<any>;
-  RadApi: RadEngineCtor;
-}
-
-/** Load and initialise the compiled WASM engine module. */
-export type RadEngineLoader = () => Promise<RadWasmModule>;
-
-/** Where to read/write the warehouse blob in `s3` mode (or any custom sink). */
-export interface WarehouseSource {
-  /** Fetch the current warehouse blob, or `null` if none exists yet. */
-  load(): Promise<Uint8Array | null>;
-  /** Persist the warehouse blob (called debounced after writes). */
-  save(blob: Uint8Array): Promise<void>;
-}
-
-export interface RAStackProviderConfig {
-  mode: RadMode;
-
-  // -- remote mode --
-  /** HTTP base URL. Defaults to `NEXT_PUBLIC_BASE_URL` or localhost:8000. */
-  baseURL?: string;
-  /** Attach a Bearer token to every request. */
-  getToken?: () => string | Promise<string>;
-
-  // -- local / s3 mode --
-  /** `schema.rad.json` — object or JSON string. Required for WASM modes. */
-  manifest?: object | string;
-  /** `openapi.json` — object or JSON string. Optional (`/api/schema/`). */
-  openapi?: object | string;
-  /**
-   * Base URL of the committed Iceberg warehouse (a *directory of files*, not a
-   * blob) to seed `local` mode from. The provider walks the tree —
-   * `version-hint.text` → snapshot metadata → `.parquet` data files — exactly
-   * as the server walks it over object storage. Defaults to `/data/warehouse/`.
-   * Ignored once a persisted local copy exists.
-   */
-  warehouseBaseUrl?: string;
-  /** Persist the local warehouse to IndexedDB between reloads (default true). */
-  persist?: boolean;
-  /** IndexedDB database name for the local warehouse. */
-  databaseName?: string;
-  /** `s3` mode: how to load/save the warehouse blob from object storage. */
-  warehouse?: WarehouseSource;
-  /**
-   * Override how the WASM module is loaded. Supply this from app code (where
-   * your bundler can resolve the generated bundle) if the default loader can't
-   * find it. Defaults to importing `rastack/wasm/rad_wasm.js`.
-   */
-  loadEngine?: RadEngineLoader;
-
-  // -- lifecycle --
-  onStatusChange?: (status: RadStatus) => void;
-  onError?: (error: unknown) => void;
-}
-
-export type RadStatus =
-  | "idle"
-  | "loading" // fetching/instantiating the WASM engine
-  | "seeding" // importing the warehouse
-  | "ready"
-  | "error";
-
-/** Imperative handle exposed via `useRadClient()`. */
-export interface RadClient {
-  mode: RadMode;
-  status: RadStatus;
-  /** The live WASM engine (null in `remote` mode). */
-  engine: RadEngine | null;
-  /** Snapshot the local warehouse to a portable blob (WASM modes only). */
-  exportWarehouse(): Promise<Uint8Array>;
-  /** Download that snapshot as a file — a portable backup of local edits. */
-  downloadWarehouse(filename?: string): Promise<void>;
-  /** Force-persist now (IndexedDB and/or the `s3` sink). */
-  persistNow(): Promise<void>;
-}
+/**
+ * Configuration for `<RAStackProvider>` — the single place a React app chooses
+ * *where the API runs*:
+ *
+ * - `remote` — talk to the Rust API over HTTP (Lambda in prod, `rad serve`
+ *   locally). The classic client/server split.
+ * - `local`  — compile-free local development: the entire API runs in the
+ *   browser via WebAssembly over an in-memory Iceberg warehouse, seeded from a
+ *   repo `data/` folder and persisted to IndexedDB. No server, no network,
+ *   instant reads/writes.
+ * - `s3`     — full client mode: the same WASM engine, but the warehouse is
+ *   loaded from and saved back to S3, so a static site reads and writes the
+ *   object-storage database directly.
+ */
+export type RadMode = "remote" | "local" | "s3";
+
+/** The subset of the WASM `RadApi` class the provider uses. */
+export interface RadEngine {
+  handle(
+    method: string,
+    path: string,
+    query: Record<string, string> | undefined,
+    body: unknown,
+  ): Promise<{ status: number; body: any }>;
+  /** Seed one Iceberg file (metadata or `.parquet` data file) at its key. */
+  seedFile(key: string, bytes: Uint8Array): Promise<void>;
+  importWarehouse(blob: Uint8Array): Promise<void>;
+  exportWarehouse(): Promise<Uint8Array>;
+}
+
+/** Constructor of the generated `RadApi` class. */
+export interface RadEngineCtor {
+  new (manifestJson: string, openapiJson?: string): RadEngine;
+}
+
+/** What a WASM bundle loader must resolve to. */
+export interface RadWasmModule {
+  /** wasm-pack `web` target exposes an init fn that fetches the `.wasm`. */
+  default?: (input?: any) => Promise<any>;
+  init?: (input?: any) => Promise<any>;
+  RadApi: RadEngineCtor;
+}
+
+/** Load and initialise the compiled WASM engine module. */
+export type RadEngineLoader = () => Promise<RadWasmModule>;
+
+/** Where to read/write the warehouse blob in `s3` mode (or any custom sink). */
+export interface WarehouseSource {
+  /** Fetch the current warehouse blob, or `null` if none exists yet. */
+  load(): Promise<Uint8Array | null>;
+  /** Persist the warehouse blob (called debounced after writes). */
+  save(blob: Uint8Array): Promise<void>;
+}
+
+export interface RAStackProviderConfig {
+  mode: RadMode;
+
+  // -- remote mode --
+  /** HTTP base URL. Defaults to `NEXT_PUBLIC_BASE_URL` or localhost:8000. */
+  baseURL?: string;
+  /** Attach a Bearer token to every request. */
+  getToken?: () => string | Promise<string>;
+
+  // -- local / s3 mode --
+  /** `schema.rad.json` — object or JSON string. Required for WASM modes. */
+  manifest?: object | string;
+  /** `openapi.json` — object or JSON string. Optional (`/api/schema/`). */
+  openapi?: object | string;
+  /**
+   * Base URL of the committed Iceberg warehouse (a *directory of files*, not a
+   * blob) to seed `local` mode from. The provider walks the tree —
+   * `version-hint.text` → snapshot metadata → `.parquet` data files — exactly
+   * as the server walks it over object storage. Defaults to `/data/warehouse/`.
+   * Ignored once a persisted local copy exists.
+   */
+  warehouseBaseUrl?: string;
+  /** Persist the local warehouse to IndexedDB between reloads (default true). */
+  persist?: boolean;
+  /** IndexedDB database name for the local warehouse. */
+  databaseName?: string;
+  /** `s3` mode: how to load/save the warehouse blob from object storage. */
+  warehouse?: WarehouseSource;
+  /**
+   * Override how the WASM module is loaded. Supply this from app code (where
+   * your bundler can resolve the generated bundle) if the default loader can't
+   * find it. Defaults to importing `rastack/wasm/rad_wasm.js`.
+   */
+  loadEngine?: RadEngineLoader;
+
+  // -- lifecycle --
+  onStatusChange?: (status: RadStatus) => void;
+  onError?: (error: unknown) => void;
+}
+
+export type RadStatus =
+  | "idle"
+  | "loading" // fetching/instantiating the WASM engine
+  | "seeding" // importing the warehouse
+  | "ready"
+  | "error";
+
+/** Imperative handle exposed via `useRadClient()`. */
+export interface RadClient {
+  mode: RadMode;
+  status: RadStatus;
+  /** The live WASM engine (null in `remote` mode). */
+  engine: RadEngine | null;
+  /** Snapshot the local warehouse to a portable blob (WASM modes only). */
+  exportWarehouse(): Promise<Uint8Array>;
+  /** Download that snapshot as a file — a portable backup of local edits. */
+  downloadWarehouse(filename?: string): Promise<void>;
+  /** Force-persist now (IndexedDB and/or the `s3` sink). */
+  persistNow(): Promise<void>;
+}