rastack 0.0.16

package/hooks/query/update.ts

@@ -0,0 +1,88 @@
+import { AxiosResponse } from "axios";
+import { useMutation, useQueryClient } from "react-query";
+import { IUpdateQueryResult, WriteQueryVariables } from "./interfaces";
+import { API } from "./api";
+import { stringifyQueryParams } from "./url";
+
+interface UpdateQueryProps<TParam> {
+  putUrl?: ((params: TParam) => string) | string;
+  patchUrl?: ((params: TParam) => string) | string;
+  postUrl?: ((params: TParam) => string) | string;
+  listQueryCacheKey?: string | undefined;
+  itemQueryCacheKey?: string | undefined;
+}
+
+export function useUpdateQuery<TParams, TPayload, TResult>({
+  putUrl,
+  patchUrl,
+  postUrl,
+  listQueryCacheKey,
+  itemQueryCacheKey,
+}: UpdateQueryProps<TParams>): IUpdateQueryResult<TParams, TPayload, TResult> {
+  if (!putUrl && !patchUrl && !postUrl) {
+    throw new Error("Either putUrl, patchUrl, or postUrl must be provided");
+  }
+  const queryClient = useQueryClient();
+
+  return useMutation<
+    TResult,
+    unknown,
+    WriteQueryVariables<TParams, TPayload>,
+    unknown
+  >(({ params, payload }) => {
+    return new Promise((resolve, reject) => {
+      let urlType: "put" | "patch" | "post" = "patch";
+      let url: string | undefined;
+
+      if (putUrl) {
+        url = typeof putUrl === "function" ? putUrl(params) : putUrl;
+        urlType = "put";
+      } else if (patchUrl) {
+        url = typeof patchUrl === "function" ? patchUrl(params) : patchUrl;
+        urlType = "patch";
+      } else if (postUrl) {
+        url = typeof postUrl === "function" ? postUrl(params) : postUrl;
+        urlType = "post";
+      }
+
+      if (!url) {
+        throw new Error("URL must be provided for the API call");
+      }
+
+      // @ts-ignore
+      const urlParams = stringifyQueryParams([], params);
+      const serverURL = `${url}${urlParams ? `?${urlParams}` : ""}`;
+
+      const getAPIFunction = (
+        urlType: string,
+        url: string,
+        payload: TPayload,
+      ) => {
+        switch (urlType) {
+          case "put":
+            return API.put(serverURL, payload);
+          case "patch":
+            return API.patch(serverURL, payload);
+          case "post":
+            return API.post(serverURL, payload);
+          default:
+            throw new Error("Invalid URL type");
+        }
+      };
+
+      getAPIFunction(urlType, url, payload)
+        .then((response: AxiosResponse<TResult>) => {
+          if (itemQueryCacheKey) {
+            queryClient.invalidateQueries([itemQueryCacheKey]);
+          }
+          if (listQueryCacheKey) {
+            queryClient.invalidateQueries(listQueryCacheKey);
+          }
+          resolve(response.data);
+        })
+        .catch((error) => {
+          reject(error);
+        });
+    });
+  });
+}

package/hooks/query/url.ts

@@ -0,0 +1,31 @@
+export function stringifyQueryParams<TParam>(
+  pathParameters: (keyof TParam)[],
+  filteredQueryParams?: Partial<TParam>,
+): string | undefined {
+  if (!filteredQueryParams) return undefined;
+
+  const urlParams = new URLSearchParams();
+
+  for (const key in filteredQueryParams) {
+    if (pathParameters.includes(key as any)) {
+      continue;
+    }
+    if (Object.prototype.hasOwnProperty.call(filteredQueryParams, key)) {
+      const value = filteredQueryParams[key];
+
+      if (Array.isArray(value)) {
+        value.forEach((item) => {
+          if (item !== undefined && item !== null) {
+            urlParams.append(key, item.toString());
+          }
+        });
+      } else {
+        if (value !== undefined && value !== null) {
+          urlParams.set(key, value.toString());
+        }
+      }
+    }
+  }
+
+  return urlParams.toString();
+}

package/hooks/real-time/index.ts

@@ -0,0 +1 @@
+export { usePusher } from "./pusher";

package/hooks/real-time/pusher.ts

@@ -0,0 +1,43 @@
+import { useEffect } from "react";
+import { useSyncEngineOptional } from "../../sync/provider";
+
+export interface PusherWakeOptions {
+  /** Channel to subscribe to. Defaults to "rad-sync". */
+  channel?: string;
+  /** Event name carrying sync notifications. Defaults to "sync". */
+  event?: string;
+  /** A connected Pusher client instance. */
+  client?: any;
+}
+
+/**
+ * Optional push transport for the sync engine. Given a connected Pusher
+ * client (passed in, or found on `window.Pusher.instances`), subscribes to
+ * a channel and wakes the engine whenever a sync event arrives — the engine
+ * then pulls the actual changes over HTTP. Push is a latency optimization
+ * only; the long-poll `/changes` loop stays the source of truth, so this
+ * hook is always safe to omit.
+ */
+export function usePusher(options?: PusherWakeOptions) {
+  const engine = useSyncEngineOptional();
+  const channelName = options?.channel || "rad-sync";
+  const eventName = options?.event || "sync";
+  const client =
+    options?.client ??
+    (typeof window !== "undefined"
+      ? (window as any).Pusher?.instances?.[0]
+      : undefined);
+
+  useEffect(() => {
+    if (!engine || !client) {
+      return;
+    }
+    const channel = client.subscribe(channelName);
+    const handler = () => engine.wake();
+    channel.bind(eventName, handler);
+    return () => {
+      channel.unbind(eventName, handler);
+      client.unsubscribe(channelName);
+    };
+  }, [engine, client, channelName, eventName]);
+}

package/jest.config.cjs

@@ -0,0 +1,6 @@
+module.exports = {
+  preset: 'ts-jest',
+  testEnvironment: 'node',
+  testMatch: ['**/test/**/*.spec.ts'],
+  moduleFileExtensions: ['ts', 'js'],
+};

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "rastack",
+  "version": "0.0.16",
+  "description": "",
+  "main": "runtime.ts",
+  "types": "runtime.ts",
+  "bin": {
+    "rastack": "dist/index.js",
+    "rad": "dist/rad.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "format": "prettier --write \"**/*.{ts,tsx,md}\"",
+    "build": "tsc && cp src/.prettierrc dist/.prettierrc",
+    "start": "node dist/index.js",
+    "test": "jest"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "dependencies": {
+    "@apidevtools/json-schema-ref-parser": "^15.4.0",
+    "@tanstack/react-query": "^5.101.2",
+    "@ts-stack/openapi-spec": "^3.1.5",
+    "@types/json-schema": "^7.0.15",
+    "@types/react": "^19.2.17",
+    "ajv": "^8.20.0",
+    "ajv-formats": "^3.0.1",
+    "axios": "^1.16.0",
+    "formik": "^2.4.9",
+    "js-yaml": "^5.2.1",
+    "json-schema": "^0.4.0",
+    "json-schema-to-typescript": "^15.0.4",
+    "jsonschema": "^1.5.0",
+    "lodash": "^4.18.0",
+    "luxon": "^3.7.2",
+    "minimatch": "^10.2.5",
+    "prettier": "^3.9.4",
+    "react-query": "^3.39.3",
+    "typescript": "^6.0.3",
+    "usehooks-ts": "^3.1.1"
+  },
+  "peerDependencies": {
+    "react": "^19.2.7"
+  },
+  "devDependencies": {
+    "@types/jest": "^30.0.0",
+    "@types/js-yaml": "^4.0.9",
+    "@types/mocha": "^10.0.6",
+    "@types/node": "^26.1.0",
+    "eslint": "^10.6.0",
+    "jest": "^30.4.2",
+    "ts-jest": "^29.4.11"
+  }
+}

package/provider/index.ts

@@ -0,0 +1,13 @@
+export * from "./types";
+export * from "./provider";
+export {
+  createWasmAdapter,
+  createEngine,
+  defaultEngineLoader,
+} from "./wasm";
+export {
+  WarehousePersistence,
+  seedFromIceberg,
+  manifestResources,
+  downloadBlob,
+} from "./warehouse";

package/provider/provider.tsx

@@ -0,0 +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;
+}

package/provider/types.ts

@@ -0,0 +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>;
+}