rastack 0.0.16

package/provider/warehouse.ts

@@ -0,0 +1,167 @@
+/**
+ * Persistence for the in-browser warehouse blob produced by
+ * `RadApi.exportWarehouse()`. A single blob (the whole Iceberg warehouse)
+ * lives in a one-row IndexedDB store so `local` mode survives reloads; `s3`
+ * mode swaps this for a {@link WarehouseSource} over object storage.
+ */
+
+const STORE = "warehouse";
+const KEY = "blob";
+
+function openDb(name: string): Promise<IDBDatabase> {
+  return new Promise((resolve, reject) => {
+    const request = indexedDB.open(name, 1);
+    request.onupgradeneeded = () => {
+      const db = request.result;
+      if (!db.objectStoreNames.contains(STORE)) {
+        db.createObjectStore(STORE);
+      }
+    };
+    request.onsuccess = () => resolve(request.result);
+    request.onerror = () => reject(request.error);
+  });
+}
+
+export class WarehousePersistence {
+  private db: Promise<IDBDatabase> | null;
+
+  constructor(private databaseName: string) {
+    this.db =
+      typeof indexedDB !== "undefined" ? openDb(databaseName) : null;
+  }
+
+  get enabled(): boolean {
+    return this.db !== null;
+  }
+
+  async load(): Promise<Uint8Array | null> {
+    if (!this.db) return null;
+    const db = await this.db;
+    return new Promise((resolve, reject) => {
+      const tx = db.transaction(STORE, "readonly");
+      const request = tx.objectStore(STORE).get(KEY);
+      request.onsuccess = () => {
+        const value = request.result;
+        resolve(value ? new Uint8Array(value) : null);
+      };
+      request.onerror = () => reject(request.error);
+    });
+  }
+
+  async save(blob: Uint8Array): Promise<void> {
+    if (!this.db) return;
+    const db = await this.db;
+    await new Promise<void>((resolve, reject) => {
+      const tx = db.transaction(STORE, "readwrite");
+      // Store a copy of the bytes; the ArrayBuffer is structured-clonable.
+      tx.objectStore(STORE).put(blob.slice().buffer, KEY);
+      tx.oncomplete = () => resolve();
+      tx.onerror = () => reject(tx.error);
+    });
+  }
+}
+
+/** Fetch bytes, or `null` on 404. */
+async function fetchBytes(url: string): Promise<Uint8Array | null> {
+  const response = await fetch(url);
+  if (!response.ok) {
+    if (response.status === 404) return null;
+    throw new Error(`failed to fetch ${url} (${response.status})`);
+  }
+  return new Uint8Array(await response.arrayBuffer());
+}
+
+/** The engine surface the seeder needs. */
+interface Seedable {
+  seedFile(key: string, bytes: Uint8Array): Promise<void>;
+}
+
+/**
+ * Seed the engine by walking a committed Iceberg warehouse over HTTP — the
+ * database is a *list of Iceberg files*, not a bundled blob. For each resource
+ * it follows the Iceberg pointers: `version-hint.text` → the current snapshot
+ * metadata → that snapshot's `.parquet` data files, handing each raw file to
+ * `engine.seedFile`. This is the same walk the server does over object storage;
+ * no directory listing is needed because Iceberg metadata is self-describing.
+ *
+ * Returns the number of tables seeded.
+ */
+export async function seedFromIceberg(
+  engine: Seedable,
+  baseUrl: string,
+  resources: { app: string; model: string }[],
+): Promise<number> {
+  const base = baseUrl.endsWith("/") ? baseUrl : `${baseUrl}/`;
+  const decoder = new TextDecoder();
+  let tables = 0;
+
+  for (const { app, model } of resources) {
+    const prefix = `${app}.db/${model}`;
+    const hintKey = `${prefix}/metadata/version-hint.text`;
+    const hint = await fetchBytes(base + hintKey);
+    if (!hint) continue; // table has no committed data yet
+
+    await engine.seedFile(hintKey, hint);
+    const version = decoder.decode(hint).trim();
+
+    const metaKey = `${prefix}/metadata/v${version}.metadata.json`;
+    const metaBytes = await fetchBytes(base + metaKey);
+    if (!metaBytes) continue;
+    await engine.seedFile(metaKey, metaBytes);
+
+    const meta = JSON.parse(decoder.decode(metaBytes)) as { data_files?: string[] };
+    for (const rel of meta.data_files || []) {
+      const key = `${prefix}/${rel}`;
+      const bytes = await fetchBytes(base + key);
+      if (bytes) await engine.seedFile(key, bytes);
+    }
+    tables++;
+  }
+  return tables;
+}
+
+/** Read the `{app, model}` list out of a compiled manifest (object or string). */
+export function manifestResources(
+  manifest: object | string,
+): { app: string; model: string }[] {
+  const parsed = typeof manifest === "string" ? JSON.parse(manifest) : manifest;
+  return (parsed?.resources || []).map((r: any) => ({
+    app: r.app,
+    model: r.model,
+  }));
+}
+
+/** Trigger a browser download of the warehouse blob so it can be committed. */
+export function downloadBlob(blob: Uint8Array, filename: string): void {
+  const url = URL.createObjectURL(new Blob([blob.slice().buffer]));
+  const a = document.createElement("a");
+  a.href = url;
+  a.download = filename;
+  document.body.appendChild(a);
+  a.click();
+  a.remove();
+  URL.revokeObjectURL(url);
+}
+
+/** A trailing debounce that always fires a final call. */
+export function debounce<T extends (...args: any[]) => void>(
+  fn: T,
+  ms: number,
+): T & { flush: () => void } {
+  let timer: ReturnType<typeof setTimeout> | null = null;
+  const wrapped = ((...args: any[]) => {
+    if (timer) clearTimeout(timer);
+    timer = setTimeout(() => {
+      timer = null;
+      fn(...args);
+    }, ms);
+  }) as T & { flush: () => void };
+  wrapped.flush = () => {
+    if (timer) {
+      clearTimeout(timer);
+      timer = null;
+      fn();
+    }
+  };
+  return wrapped;
+}

package/provider/wasm.ts

@@ -0,0 +1,124 @@
+import { AxiosAdapter, AxiosError, AxiosResponse } from "axios";
+import { RadEngine, RadEngineLoader, RadWasmModule } from "./types";
+
+/**
+ * Default WASM loader: import the bundle `rad wasm` generates
+ * (`rastack/wasm/rad_wasm.js`) and run its init. The indirection through
+ * `new Function` keeps a genuine dynamic `import()` at runtime even when the
+ * package is transpiled to CommonJS, so the consumer's bundler resolves and
+ * code-splits the `.wasm`.
+ */
+const runtimeImport: (specifier: string) => Promise<any> =
+  // eslint-disable-next-line no-new-func
+  new Function("s", "return import(s)") as any;
+
+export const defaultEngineLoader: RadEngineLoader = async () => {
+  const mod: RadWasmModule = await runtimeImport("rastack/wasm/rad_wasm.js");
+  const init = mod.default || mod.init;
+  if (typeof init === "function") {
+    await init();
+  }
+  return mod;
+};
+
+/**
+ * Instantiate the engine from a loaded module and the compiled schema. The
+ * manifest/openapi are passed as JSON strings — the same `schema.rad.json` /
+ * `openapi.json` the Rust server reads.
+ */
+export function createEngine(
+  mod: RadWasmModule,
+  manifest: object | string,
+  openapi?: object | string,
+): RadEngine {
+  const manifestJson =
+    typeof manifest === "string" ? manifest : JSON.stringify(manifest);
+  const openapiJson =
+    openapi === undefined
+      ? undefined
+      : typeof openapi === "string"
+        ? openapi
+        : JSON.stringify(openapi);
+  return new mod.RadApi(manifestJson, openapiJson);
+}
+
+const MUTATING = new Set(["POST", "PUT", "PATCH", "DELETE"]);
+
+/**
+ * An axios adapter that dispatches requests into the in-browser WASM engine
+ * instead of over the network. Translates an axios request into the engine's
+ * `handle(method, path, query, body)` and maps the `{ status, body }` result
+ * back to an `AxiosResponse` — rejecting on non-2xx exactly as HTTP axios does,
+ * so `react-query` error handling is unchanged.
+ *
+ * `onWrite` fires after each successful mutation so the provider can debounce a
+ * persist of the warehouse.
+ */
+export function createWasmAdapter(
+  engine: RadEngine,
+  onWrite?: () => void,
+): AxiosAdapter {
+  return async (config: any): Promise<AxiosResponse> => {
+    const method = String(config.method || "get").toUpperCase();
+
+    const rawUrl = config.url || "";
+    const [rawPath, rawQuery] = rawUrl.split("?");
+    // Strip any origin so only the `/api/...` path reaches the engine.
+    const path = rawPath.replace(/^https?:\/\/[^/]+/i, "") || "/";
+
+    const query: Record<string, string> = {};
+    if (rawQuery) {
+      new URLSearchParams(rawQuery).forEach((value, key) => {
+        query[key] = value;
+      });
+    }
+    if (config.params && typeof config.params === "object") {
+      for (const [key, value] of Object.entries(config.params)) {
+        if (value !== undefined && value !== null) query[key] = String(value);
+      }
+    }
+
+    // axios has already run transformRequest, so JSON bodies arrive as strings.
+    let body: unknown;
+    if (typeof config.data === "string" && config.data.length > 0) {
+      try {
+        body = JSON.parse(config.data);
+      } catch {
+        body = config.data;
+      }
+    } else if (config.data && typeof config.data === "object") {
+      body = config.data;
+    }
+
+    const result = await engine.handle(
+      method,
+      path,
+      Object.keys(query).length ? query : undefined,
+      body,
+    );
+
+    const response: AxiosResponse = {
+      data: result.body,
+      status: result.status,
+      statusText: String(result.status),
+      headers: {},
+      config,
+      request: null,
+    };
+
+    const validate =
+      config.validateStatus || ((s: number) => s >= 200 && s < 300);
+    if (!validate(result.status)) {
+      throw new AxiosError(
+        `Request failed with status code ${result.status}`,
+        result.status >= 500 ? "ERR_BAD_RESPONSE" : "ERR_BAD_REQUEST",
+        config,
+        null,
+        response,
+      );
+    }
+
+    if (MUTATING.has(method) && onWrite) onWrite();
+    return response;
+  };
+}

package/runtime.ts

@@ -0,0 +1,3 @@
+export * from "./hooks";
+export * from "./types";
+export * from "./provider";

package/src/.prettierrc

@@ -0,0 +1,7 @@
+{
+  "tabWidth": 2,
+  "semi": true,
+  "bracketSpacing": true,
+  "arrowParens": "always",
+  "printWidth": 80
+}

package/src/compile/analyze.ts

@@ -0,0 +1,224 @@
+import * as ts from "typescript";
+import {
+  AdminModel,
+  FieldModel,
+  RelationModel,
+  ResourceModel,
+  ScalarType,
+  SyncModel,
+} from "./model";
+import { resourceSourceFiles } from "./program";
+
+/**
+ * Statically analyse resource definitions and produce the canonical model.
+ *
+ * The headline behaviour is **foreign-key inference from types**: for every
+ * field we ask the `TypeChecker` for the field's type and, if that type is a
+ * `Ref<App, Model>`, we recover the relation target from the `__app`/`__model`
+ * string-literal type arguments. No runtime execution, no string heuristics on
+ * the value — the relation is read straight out of the type system.
+ */
+export function analyze(
+  program: ts.Program,
+  fileNames: string[],
+): ResourceModel[] {
+  const checker = program.getTypeChecker();
+  const resources: ResourceModel[] = [];
+
+  for (const sourceFile of resourceSourceFiles(program, fileNames)) {
+    ts.forEachChild(sourceFile, function walk(node) {
+      if (isResourceCall(node)) {
+        const model = analyzeResourceCall(node, checker);
+        if (model) resources.push(model);
+      }
+      ts.forEachChild(node, walk);
+    });
+  }
+
+  // Deterministic order: app, then model.
+  resources.sort((a, b) =>
+    a.app === b.app ? a.model.localeCompare(b.model) : a.app.localeCompare(b.app),
+  );
+  return resources;
+}
+
+function isResourceCall(node: ts.Node): node is ts.CallExpression {
+  return (
+    ts.isCallExpression(node) &&
+    ts.isIdentifier(node.expression) &&
+    node.expression.text === "resource" &&
+    node.arguments.length >= 3
+  );
+}
+
+function analyzeResourceCall(
+  call: ts.CallExpression,
+  checker: ts.TypeChecker,
+): ResourceModel | undefined {
+  const app = stringLiteralArg(call.arguments[0]);
+  const model = stringLiteralArg(call.arguments[1]);
+  const fieldsArg = call.arguments[2];
+  if (!app || !model || !fieldsArg || !ts.isObjectLiteralExpression(fieldsArg)) {
+    return undefined;
+  }
+
+  const fields: FieldModel[] = [];
+  const relations: RelationModel[] = [];
+
+  for (const prop of fieldsArg.properties) {
+    if (!ts.isPropertyAssignment(prop)) continue;
+    const name = propertyName(prop.name);
+    if (!name) continue;
+
+    const field = analyzeField(name, prop.initializer, checker);
+    if (!field) continue;
+    fields.push(field);
+    if (field.type === "fk" && field.relation) {
+      relations.push({
+        field: name,
+        target: `${field.relation.app}.${field.relation.model}`,
+        kind: "fk",
+      });
+    }
+  }
+
+  const options = literalToValue(call.arguments[3]) ?? {};
+  return {
+    app,
+    model,
+    fields,
+    relations,
+    sync: normaliseSync(options.sync),
+    admin: normaliseAdmin(options.admin),
+    search: options.search,
+    ordering: options.ordering,
+    permission: options.permission,
+  };
+}
+
+/**
+ * Resolve a single field from its initializer. FK detection is type-driven:
+ * the initializer's *type* is inspected, and a `Ref` type yields a foreign key.
+ */
+function analyzeField(
+  name: string,
+  initializer: ts.Expression,
+  checker: ts.TypeChecker,
+): FieldModel | undefined {
+  const fieldType = checker.getTypeAtLocation(initializer);
+
+  // Foreign key: the field type is Ref<App, Model>. Recover the target from
+  // the string-literal type arguments — this is the "infer FK from types" step.
+  if (fieldType.getProperty("__radRef")) {
+    const app = literalTypeProp(fieldType, "__app", checker, initializer);
+    const model = literalTypeProp(fieldType, "__model", checker, initializer);
+    if (app && model) {
+      return { name, type: "fk", relation: { app, model } };
+    }
+    return undefined;
+  }
+
+  // Scalar: the field type carries a `__radScalar` string-literal discriminant.
+  const scalar = literalTypeProp(fieldType, "__radScalar", checker, initializer);
+  if (!scalar) return undefined;
+
+  const field: FieldModel = { name, type: scalar as ScalarType };
+  applyConstraints(field, initializer);
+  return field;
+}
+
+/** Read scalar constraints (maxLength, unique, …) from the builder call args. */
+function applyConstraints(field: FieldModel, initializer: ts.Expression): void {
+  if (!ts.isCallExpression(initializer)) return;
+  const opts = literalToValue(initializer.arguments[0]);
+  if (!opts || typeof opts !== "object") return;
+  if (typeof opts.maxLength === "number") field.maxLength = opts.maxLength;
+  if (opts.unique === true) field.unique = true;
+  if (opts.primaryKey === true) field.primaryKey = true;
+  if (opts.null === true) field.null = true;
+  if (opts.default !== undefined) field.default = opts.default;
+}
+
+// -- type/AST helpers -------------------------------------------------------
+
+/** Read a string-literal-typed property (e.g. `__app: "airports"`) off a type. */
+function literalTypeProp(
+  type: ts.Type,
+  name: string,
+  checker: ts.TypeChecker,
+  location: ts.Node,
+): string | undefined {
+  const symbol = type.getProperty(name);
+  if (!symbol) return undefined;
+  const propType = checker.getTypeOfSymbolAtLocation(symbol, location);
+  if (propType.isStringLiteral()) return propType.value;
+  return undefined;
+}
+
+function stringLiteralArg(node: ts.Expression | undefined): string | undefined {
+  if (node && ts.isStringLiteralLike(node)) return node.text;
+  return undefined;
+}
+
+function propertyName(name: ts.PropertyName): string | undefined {
+  if (ts.isIdentifier(name) || ts.isStringLiteralLike(name)) return name.text;
+  return undefined;
+}
+
+/**
+ * Evaluate a *static literal* AST node (string/number/bool/null/array/object)
+ * into a JS value. Anything non-literal (a function, an identifier) yields
+ * `undefined` — the options and constraint blocks are always literals.
+ */
+function literalToValue(node: ts.Expression | undefined): any {
+  if (!node) return undefined;
+  if (ts.isStringLiteralLike(node)) return node.text;
+  if (ts.isNumericLiteral(node)) return Number(node.text);
+  if (node.kind === ts.SyntaxKind.TrueKeyword) return true;
+  if (node.kind === ts.SyntaxKind.FalseKeyword) return false;
+  if (node.kind === ts.SyntaxKind.NullKeyword) return null;
+  if (
+    ts.isPrefixUnaryExpression(node) &&
+    node.operator === ts.SyntaxKind.MinusToken
+  ) {
+    const inner = literalToValue(node.operand);
+    return typeof inner === "number" ? -inner : undefined;
+  }
+  if (ts.isArrayLiteralExpression(node)) {
+    return node.elements.map((el) => literalToValue(el));
+  }
+  if (ts.isObjectLiteralExpression(node)) {
+    const obj: any = {};
+    for (const p of node.properties) {
+      if (ts.isPropertyAssignment(p)) {
+        const key = propertyName(p.name);
+        if (key) obj[key] = literalToValue(p.initializer);
+      }
+    }
+    return obj;
+  }
+  return undefined;
+}
+
+function normaliseSync(sync: any): SyncModel | undefined {
+  if (!sync || typeof sync !== "object") return undefined;
+  const mode = sync.mode === "local" ? "local" : "server";
+  if (mode === "server" && !sync.confirmed) {
+    // A bare server resource carries no sync semantics.
+    return undefined;
+  }
+  const model: SyncModel = { mode };
+  if (typeof sync.scope === "string") model.scope = sync.scope;
+  if (Array.isArray(sync.confirmed)) model.confirmed = sync.confirmed;
+  if (sync.load === "lazy") model.load = "lazy";
+  if (sync.clientIds === true) model.clientIds = true;
+  return model;
+}
+
+function normaliseAdmin(admin: any): AdminModel | false | undefined {
+  if (admin === false) return false;
+  if (!admin || typeof admin !== "object") return undefined;
+  const model: AdminModel = {};
+  if (Array.isArray(admin.listDisplay)) model.listDisplay = admin.listDisplay;
+  return model;
+}

package/src/compile/index.ts

@@ -0,0 +1,86 @@
+import * as fs from "fs";
+import * as path from "path";
+import { analyze } from "./analyze";
+import { buildManifest, manifestToJson } from "./manifest";
+import { Manifest, ResourceModel } from "./model";
+import { buildOpenApi, openApiToJson } from "./openapi";
+import { createProgram } from "./program";
+
+export { analyze } from "./analyze";
+export { buildManifest } from "./manifest";
+export { buildOpenApi } from "./openapi";
+export * from "./model";
+
+export interface CompileResult {
+  manifest: Manifest;
+  openapi: any;
+  files: string[];
+}
+
+/** List every `.ts` resource file under a directory (or accept explicit files). */
+export function resolveResourceFiles(input: string): string[] {
+  const stat = fs.existsSync(input) ? fs.statSync(input) : undefined;
+  if (stat?.isFile()) return [path.resolve(input)];
+  if (stat?.isDirectory()) {
+    return fs
+      .readdirSync(input)
+      .filter((f) => f.endsWith(".ts") && !f.endsWith(".d.ts"))
+      .map((f) => path.resolve(input, f))
+      .sort();
+  }
+  throw new Error(`No such resources path: ${input}`);
+}
+
+/** Analyse resource definitions into the canonical model (no file output). */
+export function analyzeResources(input: string): ResourceModel[] {
+  const files = resolveResourceFiles(input);
+  const program = createProgram(files);
+  return analyze(program, files);
+}
+
+/** Compile resource definitions to a manifest + OpenAPI, writing both to disk. */
+export function compile(input: string, outDir: string): CompileResult {
+  const resources = analyzeResources(input);
+  const manifest = buildManifest(resources);
+  const openapi = buildOpenApi(resources);
+
+  fs.mkdirSync(outDir, { recursive: true });
+  const manifestPath = path.join(outDir, "schema.rad.json");
+  const openapiPath = path.join(outDir, "openapi.json");
+  fs.writeFileSync(manifestPath, manifestToJson(manifest), { flag: "w" });
+  fs.writeFileSync(openapiPath, openApiToJson(openapi), { flag: "w" });
+
+  return { manifest, openapi, files: [manifestPath, openapiPath] };
+}
+
+// -- introspection (replaces `manage.py rastack check|list|urls`) -----------
+
+/** Detect duplicate `app.model` definitions and dangling FK targets. */
+export function collisions(resources: ResourceModel[]): string[] {
+  const errors: string[] = [];
+  const seen = new Map<string, number>();
+  const keys = new Set(resources.map((r) => `${r.app}.${r.model}`));
+
+  for (const r of resources) {
+    const key = `${r.app}.${r.model}`;
+    seen.set(key, (seen.get(key) ?? 0) + 1);
+    for (const rel of r.relations) {
+      if (!keys.has(rel.target)) {
+        errors.push(
+          `${key}.${rel.field} references unknown resource ${rel.target}.`,
+        );
+      }
+    }
+  }
+  for (const [key, count] of seen) {
+    if (count > 1) errors.push(`Duplicate resource ${key} defined ${count} times.`);
+  }
+  return errors;
+}
+
+export function urlsFor(resources: ResourceModel[]): string[] {
+  return resources.flatMap((r) => [
+    `/api/${r.app}/v1/${r.model}/`,
+    `/api/${r.app}/v1/${r.model}/{id}/`,
+  ]);
+}

package/src/compile/manifest.ts

@@ -0,0 +1,10 @@
+import { Manifest, ResourceModel } from "./model";
+
+/** Assemble the canonical manifest from analysed resources. */
+export function buildManifest(resources: ResourceModel[]): Manifest {
+  return { version: 1, resources };
+}
+
+export function manifestToJson(manifest: Manifest): string {
+  return JSON.stringify(manifest, null, 2) + "\n";
+}

package/src/compile/model.ts

@@ -0,0 +1,69 @@
+/**
+ * The canonical, backend-agnostic data model produced by the compiler. This is
+ * what `schema.rad.json` serializes and what both the OpenAPI emitter and the
+ * Rust API consume.
+ */
+
+export type ScalarType =
+  | "string"
+  | "int"
+  | "float"
+  | "bool"
+  | "datetime"
+  | "uuid";
+
+export type FieldType = ScalarType | "fk";
+
+export interface RelationTarget {
+  app: string;
+  model: string;
+}
+
+export interface FieldModel {
+  name: string;
+  type: FieldType;
+  maxLength?: number;
+  unique?: boolean;
+  primaryKey?: boolean;
+  null?: boolean;
+  default?: unknown;
+  /** Present iff `type === "fk"` — the resource this field points at. */
+  relation?: RelationTarget;
+}
+
+export interface RelationModel {
+  /** The field on *this* resource that holds the foreign key. */
+  field: string;
+  /** `"app.model"` of the referenced resource. */
+  target: string;
+  kind: "fk";
+}
+
+export interface SyncModel {
+  mode: "server" | "local";
+  scope?: string;
+  confirmed?: string[];
+  load?: "instant" | "lazy";
+  clientIds?: boolean;
+}
+
+export interface AdminModel {
+  listDisplay?: string[];
+}
+
+export interface ResourceModel {
+  app: string;
+  model: string;
+  fields: FieldModel[];
+  relations: RelationModel[];
+  sync?: SyncModel;
+  admin?: AdminModel | false;
+  search?: string[];
+  ordering?: string[];
+  permission?: string;
+}
+
+export interface Manifest {
+  version: 1;
+  resources: ResourceModel[];
+}