rastack 0.0.49 → 0.0.51

package/hooks/manifest.ts

@@ -0,0 +1,77 @@
+/**
+ * The manifest as React context — what lets `useData(Airport)` /
+ * `useForm(Flight)` resolve a plain TypeScript type to its resource at
+ * runtime with no generated code in between.
+ *
+ * `<RAStackProvider manifest={…}>` supplies it (in every mode — the manifest
+ * is required for the WASM engine anyway, and in `remote` mode it is the only
+ * schema the client needs). It accepts the compiled `schema.rastack.json`
+ * (object or JSON string) **or the `resource()` definitions themselves** — an
+ * array, or a whole module namespace — in which case the manifest is built at
+ * runtime and no compile step is involved. Hooks read it with
+ * {@link useRastackManifest}; tests and one-off callers can bypass the context
+ * by passing `manifest` directly in a hook's options.
+ */
+
+import { createContext, createElement, useContext, useMemo } from "react";
+import type { ReactNode } from "react";
+import type { Manifest } from "../src/compile/model";
+import { toManifest, type ManifestInput } from "../src/define/manifest";
+
+export const RastackManifestContext = createContext<Manifest | undefined>(
+  undefined,
+);
+
+export interface RastackManifestProviderProps {
+  /**
+   * `schema.rastack.json` (parsed object or JSON string), or `resource()`
+   * definitions (an array or a module namespace) to build it from at runtime.
+   */
+  manifest?: ManifestInput;
+  children?: ReactNode;
+}
+
+/** Provide the manifest to every `useData`/`useForm` beneath it. */
+export function RastackManifestProvider(props: RastackManifestProviderProps) {
+  const { manifest, children } = props;
+  const value = useMemo<Manifest | undefined>(
+    () => toManifest(manifest) ?? getGlobalManifest(),
+    [manifest],
+  );
+  return createElement(RastackManifestContext.Provider, { value }, children);
+}
+
+/**
+ * The manifest in effect: the nearest provider's, else the one the dev-server
+ * plugin registered globally (see {@link getGlobalManifest}) — which is what
+ * lets an app pass **no manifest anywhere**.
+ */
+export function useRastackManifest(): Manifest | undefined {
+  return useContext(RastackManifestContext) ?? getGlobalManifest();
+}
+
+// -- the auto-registered manifest -------------------------------------------
+
+/**
+ * The global the `rastack/plugin` dev-server plugin assigns before the app
+ * boots (its injected register module runs first): the manifest compiled
+ * from your TypeScript entities, refreshed on every save. With it in place,
+ * `<RAStackProvider mode="local">` needs no `manifest` prop and `useData` /
+ * `useForm` resolve entities with zero schema wiring in app code — the
+ * types are the only thing you author.
+ */
+export const GLOBAL_MANIFEST_KEY = "__RASTACK_MANIFEST__";
+
+let cachedRaw: unknown;
+let cachedManifest: Manifest | undefined;
+
+/** The plugin-registered manifest, normalised (and cached per assignment). */
+export function getGlobalManifest(): Manifest | undefined {
+  const raw = (globalThis as Record<string, unknown>)[GLOBAL_MANIFEST_KEY];
+  if (raw === undefined || raw === null) return undefined;
+  if (raw !== cachedRaw) {
+    cachedRaw = raw;
+    cachedManifest = toManifest(raw as ManifestInput);
+  }
+  return cachedManifest;
+}

package/hooks/registry.ts

@@ -0,0 +1,56 @@
+/**
+ * The type-level entity registry — what lets a bare string infer its rows:
+ *
+ * ```tsx
+ * const terminals = useData("airports.terminal");   // rows: Terminal[]
+ * ```
+ *
+ * TypeScript can't conjure an interface out of a string on its own, so the
+ * registry maps manifest keys (`"app.model"`) to your own types via ordinary
+ * declaration merging. Note that classes and `resource()` values never need
+ * it — they infer on their own; the registry only serves the string form.
+ * Two ways to populate it, **neither generating runtime code**:
+ *
+ * 1. **Hand-written, no compile step** — point `EntityTypesOf` at your
+ *    resources module once; it derives every `"app.model"` key and row type
+ *    from the definitions and tracks them forever:
+ *
+ * ```ts
+ * // rastack-env.d.ts — written once by you, never regenerated
+ * import type { EntityTypesOf } from "rastack/define";
+ * declare module "rastack/hooks/registry" {
+ *   interface EntityTypes
+ *     extends EntityTypesOf<typeof import("./resources/airports")> {}
+ * }
+ * ```
+ *
+ * 2. **Emitted by `rastack compile`** as `rastack-env.d.ts` beside the
+ *    manifest — one entry per class/interface entity in the compiled graph
+ *    (which have no runtime value for `EntityTypesOf` to read), pointing at
+ *    *your* declaration:
+ *
+ * ```ts
+ * declare module "rastack/hooks/registry" {
+ *   interface EntityTypes {
+ *     "airports.terminal": import("../resources/airports").Terminal;
+ *   }
+ * }
+ * ```
+ *
+ * With either file in the program, `useData` / `useRecord` / `useForm`
+ * overloads resolve `"app.model"` arguments through {@link EntityTypes};
+ * unregistered strings fall back to `any` (or an explicit
+ * `useData<ITerminal>(…)` argument, which always still works).
+ */
+
+/** `"app.model"` → row type. Populated by declaration merging — see above. */
+// eslint-disable-next-line @typescript-eslint/no-empty-interface
+export interface EntityTypes {}
+
+/** Every registered manifest key. `never` until the registry is augmented. */
+export type RegisteredEntityKey = Extract<keyof EntityTypes, string>;
+
+/** The row type behind a manifest key, else `any` for unregistered strings. */
+export type RowForKey<K extends string> = K extends keyof EntityTypes
+  ? EntityTypes[K]
+  : any;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rastack",
-  "version": "0.0.49",
+  "version": "0.0.51",
   "description": "",
   "main": "runtime.ts",
   "types": "runtime.ts",

package/plugin.ts

@@ -0,0 +1,8 @@
+/**
+ * `rastack/plugin` — the dev-server schema compiler. Add it to the bundler
+ * you already run (Vite/Rollup: `rastackPlugin()`; anything else:
+ * `startRastackWatcher()`) and class/interface entities compile to the
+ * manifest on every save — no `rastack compile` command in the loop.
+ * Node-only: import from build config, never from app code.
+ */
+export * from "./src/plugin";

package/provider/provider.tsx

@@ -8,6 +8,7 @@ import React, {
   useState,
 } from "react";
 import { API, configureApi, resetApi } from "../hooks/query/api";
+import { RastackManifestProvider } from "../hooks/manifest";
 import {
   RastackClient,
   RastackEngine,
@@ -32,6 +33,8 @@ import {
   isAccessRevoked,
   purgeIdentityCache,
 } from "../cache";
+import { toManifest } from "../src/define/manifest";
+import { getGlobalManifest } from "../hooks/manifest";
 
 const RastackContext = createContext<RastackClient | null>(null);
 
@@ -56,6 +59,16 @@ export function RAStackProvider({
   const persistRef = useRef<(() => void) & { flush: () => void }>();
   const cacheStorageRef = useRef<CacheStorage | null>(null);
 
+  // The `manifest` prop is optional: when the rastack dev-server plugin is
+  // in the bundler it registers the compiled schema globally before the app
+  // boots, so `<RAStackProvider mode="local">` needs no schema wiring at
+  // all. An explicit prop (schema.rastack.json object/string, or resource()
+  // definitions — array or module namespace) always wins.
+  const manifest = useMemo(
+    () => toManifest(config.manifest) ?? getGlobalManifest(),
+    [config.manifest],
+  );
+
   const setStatusSafe = (next: RadStatus) => {
     setStatus(next);
     config.onStatusChange?.(next);
@@ -109,15 +122,17 @@ export function RAStackProvider({
       }
 
       // -- WASM modes (local / s3) --
-      if (!config.manifest) {
-        throw new Error("RAStackProvider: `manifest` is required in local/s3 mode.");
+      if (!manifest) {
+        throw new Error(
+          "RAStackProvider: no manifest found for local/s3 mode — add rastackPlugin() to your bundler (rastack/plugin), or pass the `manifest` prop.",
+        );
       }
 
       setStatusSafe("loading");
       const loader = config.loadEngine ?? defaultEngineLoader;
       const mod = await loader();
       if (cancelled) return;
-      const engine = createEngine(mod, config.manifest, config.openapi);
+      const engine = createEngine(mod, manifest, config.openapi);
 
       // Run the in-browser engine as the signed-in identity so owner stamping
       // and row-level security match the server exactly.
@@ -139,7 +154,7 @@ export function RAStackProvider({
           await engine.importWarehouse(existing);
         } else {
           const base = config.warehouseBaseUrl ?? "/data/warehouse/";
-          const resources = manifestResources(config.manifest);
+          const resources = manifestResources(manifest);
           if (config.cache === false) {
             await seedFromIceberg(engine, base, resources);
           } else {
@@ -227,7 +242,13 @@ export function RAStackProvider({
     [config.mode, status, config.identity],
   );
 
-  return <RastackContext.Provider value={client}>{children}</RastackContext.Provider>;
+  return (
+    <RastackContext.Provider value={client}>
+      <RastackManifestProvider manifest={manifest}>
+        {children}
+      </RastackManifestProvider>
+    </RastackContext.Provider>
+  );
 }
 
 function pickPersistence(

package/provider/types.ts

@@ -96,9 +96,21 @@ export interface RAStackProviderConfig {
    */
   maxOfflineMs?: number;
 
-  // -- local / s3 mode --
-  /** `schema.rastack.json` — object or JSON string. Required for WASM modes. */
-  manifest?: object | string;
+  // -- all modes --
+  /**
+   * The schema — **usually omitted**: with the `rastack/plugin` dev-server
+   * plugin in the bundler, the manifest compiled from your entities is
+   * registered globally before the app boots and the provider picks it up
+   * automatically. Pass it explicitly to override: the compiled
+   * `schema.rastack.json` (object or JSON string), the
+   * `virtual:rastack-manifest` module, or `resource()` definitions (an array
+   * or a module namespace), from which the provider builds the identical
+   * manifest at runtime. One of the two (plugin or prop) is required for
+   * WASM modes (the manifest drives the in-browser engine); it is also what
+   * lets `useData(Entity)` / `useForm(Entity)` resolve a plain TypeScript
+   * type to its resource at runtime.
+   */
+  manifest?: object | readonly object[] | string;
   /** `openapi.json` — object or JSON string. Optional (`/api/schema/`). */
   openapi?: object | string;
   /**

package/src/compile/analyze.ts

@@ -1,14 +1,25 @@
+import * as path from "path";
 import * as ts from "typescript";
 import {
-  AccessModel,
-  AdminModel,
   FieldModel,
   RelationModel,
   ResourceModel,
   ScalarType,
-  SyncModel,
 } from "./model";
 import { resourceSourceFiles } from "./program";
+import {
+  applyTransitions,
+  normaliseAccess,
+  normaliseAdmin,
+  normaliseSync,
+} from "../define/manifest";
+import type { EntityTypeExport } from "./entities";
+
+// The option normalisers live beside the runtime manifest builder
+// (`define/manifest.ts`) and are shared with it, so a manifest built from
+// runtime `resource()` values and one compiled from the same source can
+// never disagree. Re-exported here for existing importers.
+export { applyTransitions } from "../define/manifest";
 
 /**
  * Statically analyse resource definitions and produce the canonical model.
@@ -23,14 +34,34 @@ export function analyze(
   program: ts.Program,
   fileNames: string[],
 ): ResourceModel[] {
+  return analyzeDsl(program, fileNames).resources;
+}
+
+/**
+ * Analyse the DSL surface, also collecting where each `resource()` const
+ * lives — `export const Flight = resource(…)` registers in the emitted
+ * `rastack-env.d.ts` as `RowOf<typeof Flight>`, so string references
+ * (`useData("airports.flight")`) infer rows for DSL resources too.
+ */
+export function analyzeDsl(
+  program: ts.Program,
+  fileNames: string[],
+): { resources: ResourceModel[]; types: EntityTypeExport[] } {
   const checker = program.getTypeChecker();
   const resources: ResourceModel[] = [];
+  const types: EntityTypeExport[] = [];
 
   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);
+        if (model) {
+          resources.push(model);
+          const constExport = resourceConstExport(node);
+          if (constExport) {
+            types.push({ key: `${model.app}.${model.model}`, ...constExport });
+          }
+        }
       }
       ts.forEachChild(node, walk);
     });
@@ -40,7 +71,31 @@ export function analyze(
   resources.sort((a, b) =>
     a.app === b.app ? a.model.localeCompare(b.model) : a.app.localeCompare(b.app),
   );
-  return resources;
+  types.sort((a, b) => a.key.localeCompare(b.key));
+  return { resources, types };
+}
+
+/** The `const X = resource(…)` binding a resource call is assigned to. */
+function resourceConstExport(
+  call: ts.CallExpression,
+): Omit<EntityTypeExport, "key"> | undefined {
+  const decl = call.parent;
+  if (!ts.isVariableDeclaration(decl) || !ts.isIdentifier(decl.name)) {
+    return undefined;
+  }
+  const statement = decl.parent?.parent;
+  const exported =
+    !!statement &&
+    ts.isVariableStatement(statement) &&
+    !!ts.getModifiers(statement)?.some(
+      (m) => m.kind === ts.SyntaxKind.ExportKeyword,
+    );
+  return {
+    typeName: decl.name.text,
+    fileName: path.resolve(call.getSourceFile().fileName),
+    exported,
+    kind: "resourceConst",
+  };
 }
 
 function isResourceCall(node: ts.Node): node is ts.CallExpression {
@@ -84,7 +139,7 @@ function analyzeResourceCall(
   }
 
   const options = literalToValue(call.arguments[3]) ?? {};
-  return {
+  const resource: ResourceModel = {
     app,
     model,
     fields,
@@ -96,6 +151,8 @@ function analyzeResourceCall(
     permission: options.permission,
     access: normaliseAccess(options.access),
   };
+  applyTransitions(resource, options.transitions);
+  return resource;
 }
 
 /**
@@ -171,9 +228,19 @@ function propertyName(name: ts.PropertyName): string | 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.
+ * Exported for the class-entity analyser, which reads `static transitions`
+ * blocks with the same evaluator.
  */
-function literalToValue(node: ts.Expression | undefined): any {
+export function literalToValue(node: ts.Expression | undefined): any {
   if (!node) return undefined;
+  // Look through `as const` / `satisfies` / parens — the value is unchanged.
+  if (
+    ts.isAsExpression(node) ||
+    ts.isSatisfiesExpression(node) ||
+    ts.isParenthesizedExpression(node)
+  ) {
+    return literalToValue(node.expression);
+  }
   if (ts.isStringLiteralLike(node)) return node.text;
   if (ts.isNumericLiteral(node)) return Number(node.text);
   if (node.kind === ts.SyntaxKind.TrueKeyword) return true;
@@ -201,41 +268,3 @@ function literalToValue(node: ts.Expression | undefined): any {
   }
   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 normaliseAccess(access: any): AccessModel | undefined {
-  if (!access || typeof access !== "object") return undefined;
-  const model: AccessModel = {};
-  if (typeof access.ownerField === "string") model.ownerField = access.ownerField;
-  if (access.scope === "owner" || access.scope === "shared") {
-    model.scope = access.scope;
-  }
-  if (Array.isArray(access.adminGroups)) {
-    model.adminGroups = access.adminGroups.filter(
-      (g: unknown) => typeof g === "string",
-    );
-  }
-  return Object.keys(model).length ? model : undefined;
-}
-
-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/entities.ts

@@ -2,6 +2,7 @@ import * as path from "path";
 import * as ts from "typescript";
 import { FieldModel, RelationModel, ResourceModel, ScalarType } from "./model";
 import { resourceSourceFiles } from "./program";
+import { applyTransitions, literalToValue } from "./analyze";
 
 /**
  * Type-driven resource inference — "the entities in the app are a list of
@@ -70,9 +71,29 @@ export interface EntityDiagnostic {
   message: string;
 }
 
+/**
+ * Where one entity's TypeScript type lives — what `rastack compile` needs to
+ * emit the `rastack-env.d.ts` registry (`"app.model"` → `import("…").Name`)
+ * that lets `useData("app.model")` infer its rows with no type argument.
+ */
+export interface EntityTypeExport {
+  /** `"app.model"`. */
+  key: string;
+  /** The declared class/interface name (or DSL const name). */
+  typeName: string;
+  /** Absolute path of the declaring source file. */
+  fileName: string;
+  /** Whether the declaration is exported (unexported types can't register). */
+  exported: boolean;
+  /** DSL consts register as `RowOf<typeof X>` rather than the type itself. */
+  kind: "type" | "resourceConst";
+}
+
 export interface EntityAnalysis {
   resources: ResourceModel[];
   diagnostics: EntityDiagnostic[];
+  /** Registry entries for the class/interface entities. */
+  types: EntityTypeExport[];
 }
 
 export function analyzeEntities(
@@ -105,12 +126,39 @@ export function analyzeEntities(
       roots.push(decl);
     }
   };
+  // Names of every candidate, for string-argument rooting.
+  const candidateNaming = new Map<EntityDecl, EntityNaming>();
+  const namingOf = (decl: EntityDecl): EntityNaming => {
+    let naming = candidateNaming.get(decl);
+    if (!naming) {
+      naming = entityNaming(decl);
+      candidateNaming.set(decl, naming);
+    }
+    return naming;
+  };
+
   for (const sf of sourceFiles) {
     ts.forEachChild(sf, function walk(node) {
-      if (ts.isCallExpression(node) && isHookCall(node)) {
-        for (const typeArg of node.typeArguments ?? []) {
-          const decl = entityBehindTypeNode(typeArg, checker, scanned);
-          if (decl && candidates.has(decl)) addRoot(decl);
+      if (ts.isCallExpression(node)) {
+        if (isHookCall(node)) {
+          for (const typeArg of node.typeArguments ?? []) {
+            const decl = entityBehindTypeNode(typeArg, checker, scanned);
+            if (decl && candidates.has(decl)) addRoot(decl);
+          }
+        }
+        // `useData("airports.terminal")` — the manifest-key string names the
+        // entity, so it roots the declaration exactly like a type argument
+        // would: the compiler resolves the dotted key against the same naming
+        // it compiles. (Only the dotted form roots — a bare string argument to
+        // some `use*` hook is far too often not an entity key.)
+        const key = hookEntityKeyArg(node);
+        if (key) {
+          for (const decl of candidates) {
+            const naming = namingOf(decl);
+            if (naming.app === key.app && naming.model === key.model) {
+              addRoot(decl);
+            }
+          }
         }
       }
       ts.forEachChild(node, walk);
@@ -153,9 +201,17 @@ export function analyzeEntities(
     included.map((decl) => [decl, entityNaming(decl)] as const),
   );
   const resources: ResourceModel[] = [];
+  const types: EntityTypeExport[] = [];
   for (const decl of included) {
     const naming = namingByDecl.get(decl)!;
     const key = `${naming.app}.${naming.model}`;
+    types.push({
+      key,
+      typeName: decl.name!.text,
+      fileName: path.resolve(decl.getSourceFile().fileName),
+      exported: !!(ts.getCombinedModifierFlags(decl) & ts.ModifierFlags.Export),
+      kind: "type",
+    });
     const fields: FieldModel[] = [];
     const relations: RelationModel[] = [];
 
@@ -185,34 +241,78 @@ export function analyzeEntities(
       }
     }
 
-    resources.push({
+    const resource: ResourceModel = {
       app: naming.app,
       model: naming.model,
       fields,
       relations,
       search: naming.search,
       permission: naming.permission,
-    });
+    };
+    // A class may declare its state machine inline: `static transitions =
+    // {...}`. Statics are never columns, so the block rides alongside the
+    // data properties — the class-authored twin of the DSL option.
+    applyTransitions(resource, staticTransitions(decl));
+    resources.push(resource);
   }
 
   resources.sort((a, b) =>
     a.app === b.app ? a.model.localeCompare(b.model) : a.app.localeCompare(b.app),
   );
-  return { resources, diagnostics };
+  return { resources, diagnostics, types };
+}
+
+/**
+ * The literal value of a class's `static transitions = {...}` block, when
+ * declared. Only static object literals qualify — the block is data, exactly
+ * like the DSL option, and is evaluated with the same literal evaluator.
+ */
+function staticTransitions(decl: EntityDecl): unknown {
+  if (!ts.isClassDeclaration(decl)) return undefined;
+  for (const member of decl.members) {
+    if (
+      ts.isPropertyDeclaration(member) &&
+      ts.getCombinedModifierFlags(member) & ts.ModifierFlags.Static &&
+      (ts.isIdentifier(member.name) || ts.isStringLiteralLike(member.name)) &&
+      member.name.text === "transitions" &&
+      member.initializer
+    ) {
+      return literalToValue(member.initializer);
+    }
+  }
+  return undefined;
 }
 
 // -- hooks -------------------------------------------------------------------
 
-/** A React-style hook call: `useX(...)` or `obj.useX(...)` with type args. */
-function isHookCall(call: ts.CallExpression): boolean {
-  if (!call.typeArguments?.length) return false;
+/** The `useX` name of a call's callee, if it is hook-shaped. */
+function hookCalleeName(call: ts.CallExpression): string | undefined {
   const callee = call.expression;
   const name = ts.isIdentifier(callee)
     ? callee.text
     : ts.isPropertyAccessExpression(callee)
       ? callee.name.text
       : undefined;
-  return !!name && /^use[A-Z0-9_]/.test(name);
+  return name && /^use[A-Z0-9_]/.test(name) ? name : undefined;
+}
+
+/** A React-style hook call: `useX(...)` or `obj.useX(...)` with type args. */
+function isHookCall(call: ts.CallExpression): boolean {
+  if (!call.typeArguments?.length) return false;
+  return hookCalleeName(call) !== undefined;
+}
+
+const ENTITY_KEY_RE = /^([A-Za-z_$][\w$]*)\.([A-Za-z_$][\w$]*)$/;
+
+/** The `{ app, model }` of a hook call's first-argument entity-key string. */
+function hookEntityKeyArg(
+  call: ts.CallExpression,
+): { app: string; model: string } | undefined {
+  if (!hookCalleeName(call)) return undefined;
+  const first = call.arguments[0];
+  if (!first || !ts.isStringLiteralLike(first)) return undefined;
+  const match = ENTITY_KEY_RE.exec(first.text);
+  return match ? { app: match[1], model: match[2] } : undefined;
 }
 
 /** Resolve a type node to a class/interface declared in a scanned file. */