rastack 0.0.50 → 0.0.52

package/dist/plugin/index.js

@@ -0,0 +1,203 @@
+"use strict";
+/**
+ * `rastack/plugin` — the schema compiles itself inside your dev server.
+ *
+ * Class and interface entities are pure types, so the manifest has to be
+ * derived by the TypeScript checker — but not by a command you run. Add the
+ * plugin to the bundler you already use and the whole `rastack compile`
+ * pass disappears into the dev loop:
+ *
+ * ```ts
+ * // vite.config.ts
+ * import { rastackPlugin } from "rastack/plugin";
+ * export default defineConfig({
+ *   plugins: [rastackPlugin({ resourcesDir: "src/entities" })],
+ * });
+ * ```
+ *
+ * ```tsx
+ * // app — the manifest is a live import, recompiled on every save
+ * import manifest from "virtual:rastack-manifest";
+ * <RAStackProvider mode="local" manifest={manifest}>…</RAStackProvider>
+ * ```
+ *
+ * What it does on your behalf, on every relevant file save:
+ * - recompiles the entity graph (classes, interfaces, `resource()` calls);
+ * - serves the manifest as the `virtual:rastack-manifest` module and
+ *   hot-invalidates it;
+ * - rewrites `.rastack/rastack-env.d.ts` (string-key row types) and
+ *   `schema.rastack.json`/`openapi.json`, so the committed artifacts and the
+ *   registry never go stale;
+ * - on a broken in-progress edit, reports the error and keeps serving the
+ *   last good manifest.
+ *
+ * The plugin object is Vite/Rollup-compatible (Vite-specific hooks are
+ * ignored by plain Rollup). For dev servers with other plugin systems
+ * (Next/webpack, Metro/Expo), `startRastackWatcher` does the same
+ * recompile-on-save against the filesystem — call it once from your config —
+ * and `rastack dev` remains the zero-config path.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.rastack = exports.virtualModuleDts = exports.VIRTUAL_REGISTER_ID = exports.VIRTUAL_MANIFEST_ID = exports.runCompile = exports.RESOLVED_MANIFEST_ID = exports.resolveOptions = exports.registerModuleCode = exports.manifestModuleCode = exports.isEntitySource = exports.GLOBAL_MANIFEST_KEY = exports.createSchemaState = void 0;
+exports.rastackPlugin = rastackPlugin;
+exports.startRastackWatcher = startRastackWatcher;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const core_1 = require("./core");
+var core_2 = require("./core");
+Object.defineProperty(exports, "createSchemaState", { enumerable: true, get: function () { return core_2.createSchemaState; } });
+Object.defineProperty(exports, "GLOBAL_MANIFEST_KEY", { enumerable: true, get: function () { return core_2.GLOBAL_MANIFEST_KEY; } });
+Object.defineProperty(exports, "isEntitySource", { enumerable: true, get: function () { return core_2.isEntitySource; } });
+Object.defineProperty(exports, "manifestModuleCode", { enumerable: true, get: function () { return core_2.manifestModuleCode; } });
+Object.defineProperty(exports, "registerModuleCode", { enumerable: true, get: function () { return core_2.registerModuleCode; } });
+Object.defineProperty(exports, "resolveOptions", { enumerable: true, get: function () { return core_2.resolveOptions; } });
+Object.defineProperty(exports, "RESOLVED_MANIFEST_ID", { enumerable: true, get: function () { return core_2.RESOLVED_MANIFEST_ID; } });
+Object.defineProperty(exports, "runCompile", { enumerable: true, get: function () { return core_2.runCompile; } });
+Object.defineProperty(exports, "VIRTUAL_MANIFEST_ID", { enumerable: true, get: function () { return core_2.VIRTUAL_MANIFEST_ID; } });
+Object.defineProperty(exports, "VIRTUAL_REGISTER_ID", { enumerable: true, get: function () { return core_2.VIRTUAL_REGISTER_ID; } });
+Object.defineProperty(exports, "virtualModuleDts", { enumerable: true, get: function () { return core_2.virtualModuleDts; } });
+/**
+ * The bundler plugin. Works as-is in Vite and Rollup; the returned object is
+ * plain data + closures, so any bundler with resolve/load/watch hooks can
+ * adapt it.
+ */
+function rastackPlugin(options = {}) {
+    const state = (0, core_1.createSchemaState)(options);
+    return {
+        name: "rastack",
+        buildStart() {
+            // Compile eagerly so authoring errors surface at server start, and the
+            // artifacts (env.d.ts, schema.rastack.json) exist before first load.
+            state.manifest();
+        },
+        resolveId(id) {
+            if (id === core_1.VIRTUAL_MANIFEST_ID)
+                return core_1.RESOLVED_MANIFEST_ID;
+            if (id === core_1.VIRTUAL_REGISTER_ID)
+                return core_1.VIRTUAL_REGISTER_ID;
+            return undefined;
+        },
+        load(id) {
+            if (id === core_1.RESOLVED_MANIFEST_ID)
+                return state.code();
+            if (id === core_1.VIRTUAL_REGISTER_ID)
+                return (0, core_1.registerModuleCode)();
+            return undefined;
+        },
+        watchChange(id) {
+            if ((0, core_1.isEntitySource)(id, state.options))
+                state.invalidate();
+        },
+        handleHotUpdate(ctx) {
+            if (!(0, core_1.isEntitySource)(ctx.file, state.options))
+                return;
+            state.invalidate();
+            const mod = ctx.server.moduleGraph.getModuleById(core_1.RESOLVED_MANIFEST_ID);
+            if (mod) {
+                ctx.server.moduleGraph.invalidateModule(mod);
+                return [...ctx.modules, mod];
+            }
+        },
+        transformIndexHtml: {
+            order: "pre",
+            handler(_html, ctx) {
+                // Dev serves resolved ids at /@id/<id>; build gets an inline module
+                // script that (because this runs `pre`, before Vite scans the HTML
+                // entry) is bundled, its import resolving back through
+                // resolveId/load above.
+                const attrs = { type: "module" };
+                const tag = ctx?.server
+                    ? {
+                        tag: "script",
+                        attrs: { ...attrs, src: `/@id/${core_1.VIRTUAL_REGISTER_ID}` },
+                    }
+                    : {
+                        tag: "script",
+                        attrs,
+                        children: `import ${JSON.stringify(core_1.VIRTUAL_REGISTER_ID)};`,
+                    };
+                return [{ ...tag, injectTo: "head-prepend" }];
+            },
+        },
+        api: state,
+    };
+}
+/** Alias so `import { rastack } from "rastack/plugin"` reads naturally. */
+exports.rastack = rastackPlugin;
+/**
+ * The plugin for everything that isn't Rollup-shaped: watch the resources
+ * directory and rewrite the artifacts (`schema.rastack.json`,
+ * `openapi.json`, `rastack-env.d.ts`) on every save. Call once from any
+ * Node-side config (next.config.js, metro.config.js, a dev script):
+ *
+ * ```js
+ * // next.config.js
+ * const { startRastackWatcher } = require("rastack/plugin");
+ * if (process.env.NODE_ENV === "development") startRastackWatcher();
+ * ```
+ *
+ * The app then imports `.rastack/schema.rastack.json` directly (a plain JSON
+ * import every bundler hot-reloads) instead of the virtual module.
+ */
+function startRastackWatcher(options = {}) {
+    const state = (0, core_1.createSchemaState)(options);
+    state.manifest(); // initial compile (writes the artifacts)
+    let timer;
+    const watcher = fs.watch(state.options.resourcesDir, { recursive: true }, (_event, filename) => {
+        // fs.watch reports paths relative to the watched directory.
+        const file = filename
+            ? path.join(state.options.resourcesDir, String(filename))
+            : undefined;
+        if (!file || !(0, core_1.isEntitySource)(file, state.options)) {
+            return;
+        }
+        state.invalidate();
+        // Debounce bursts (editors write twice, git checkouts touch many files).
+        if (timer)
+            clearTimeout(timer);
+        timer = setTimeout(() => {
+            state.manifest();
+        }, 100);
+    });
+    return {
+        close: () => {
+            if (timer)
+                clearTimeout(timer);
+            watcher.close();
+        },
+        state,
+    };
+}

package/dist/wasm/rastack_wasm.js

@@ -375,7 +375,7 @@ function __wbg_get_imports() {
             return ret;
         },
         __wbindgen_cast_0000000000000001: function(arg0, arg1) {
-            // Cast intrinsic for `Closure(Closure { owned: true, function: Function { arguments: [Externref], shim_idx: 85, ret: Result(Unit), inner_ret: Some(Result(Unit)) }, mutable: true }) -> Externref`.
+            // Cast intrinsic for `Closure(Closure { owned: true, function: Function { arguments: [Externref], shim_idx: 83, ret: Result(Unit), inner_ret: Some(Result(Unit)) }, mutable: true }) -> Externref`.
             const ret = makeMutClosure(arg0, arg1, wasm_bindgen_1a7aa9db5392c486___convert__closures_____invoke___wasm_bindgen_1a7aa9db5392c486___JsValue__core_7d5f0a2ba6a62c33___result__Result_____wasm_bindgen_1a7aa9db5392c486___JsError___true_);
             return ret;
         },

package/hooks/data.ts

@@ -49,14 +49,18 @@ import {
 } from "./entity";
 import { useRastackManifest } from "./manifest";
 import type { EntityTypes, RegisteredEntityKey } from "./registry";
-import type { Manifest, ResourceModel } from "../src/compile/model";
+import type { ResourceModel } from "../src/compile/model";
+import { toManifest, type ManifestInput } from "../src/define/manifest";
 
 export interface UseDataOptions<TRow>
   extends ListQueryOptions<Record<string, unknown>, TRow> {
   /** Gate the query (replaces the generated hooks' auth wiring). Default on. */
   enabled?: boolean;
-  /** Manifest override — tests, or callers outside `<RAStackProvider>`. */
-  manifest?: Manifest;
+  /**
+   * Manifest override — tests, or callers outside `<RAStackProvider>`.
+   * Accepts a compiled manifest or `resource()` definitions (array/module).
+   */
+  manifest?: ManifestInput;
 }
 
 /**
@@ -114,7 +118,11 @@ export function useData(
   options?: UseDataOptions<any>,
 ): UseDataResult<any> {
   const contextManifest = useRastackManifest();
-  const manifest = options?.manifest ?? contextManifest;
+  const optionManifest = useMemo(
+    () => toManifest(options?.manifest),
+    [options?.manifest],
+  );
+  const manifest = optionManifest ?? contextManifest;
   const resolvedEntity = useMemo(
     () => resolveEntityRef(entity, manifest),
     [entity, manifest],
@@ -165,7 +173,7 @@ export function useData(
 
 export interface UseRecordOptions {
   enabled?: boolean;
-  manifest?: Manifest;
+  manifest?: ManifestInput;
 }
 
 /** One record by id — the generic twin of the generated detail hooks. */
@@ -190,7 +198,11 @@ export function useRecord(
   options?: UseRecordOptions,
 ): IGetQueryResult<any> & { entity: ResolvedEntity } {
   const contextManifest = useRastackManifest();
-  const manifest = options?.manifest ?? contextManifest;
+  const optionManifest = useMemo(
+    () => toManifest(options?.manifest),
+    [options?.manifest],
+  );
+  const manifest = optionManifest ?? contextManifest;
   const resolvedEntity = useMemo(
     () => resolveEntityRef(entity, manifest),
     [entity, manifest],

package/hooks/entity.ts

@@ -27,6 +27,7 @@ import type {
   TransitionsModel,
 } from "../src/compile/model";
 import type { ResourceType, RowOf } from "../src/define";
+import { isResourceValue, resourceModel } from "../src/define/manifest";
 import type { EntityTypes } from "./registry";
 import { normalizeTransitions } from "../src/validate/transitions";
 
@@ -46,7 +47,9 @@ export type EntityRef<TRow = any> =
  * The row type an entity reference implies — every reference form infers:
  * classes carry it (`InstanceType`), `resource()` values derive it from their
  * fields ({@link RowOf}), and `"app.model"` strings resolve through the
- * {@link EntityTypes} registry `rastack compile` emits (`rastack-env.d.ts`).
+ * {@link EntityTypes} registry — populated by a one-line hand-written
+ * `EntityTypesOf<…>` declaration, or by the `rastack-env.d.ts` that
+ * `rastack compile` emits. No path involves generated runtime code.
  */
 export type EntityRow<E> =
   E extends EntityClass<infer R>
@@ -116,7 +119,10 @@ export function resolveEntityRef(
   manifest?: Manifest,
 ): ResolvedEntity {
   // `{ app, model }` — a `resource()` value, an EntityDescriptor, or a plain
-  // object. The manifest enriches it (fields, transitions) when available.
+  // object. The manifest enriches it (fields, transitions) when available;
+  // a `resource()` value that a manifest doesn't cover is **its own
+  // manifest** — the definition carries its fields/options at runtime, so no
+  // compile step (and no provider config) is needed for the DSL path.
   if (typeof ref === "object" && ref !== null) {
     const { app, model } = ref as { app?: unknown; model?: unknown };
     if (typeof app !== "string" || typeof model !== "string") {
@@ -124,9 +130,9 @@ export function resolveEntityRef(
         "useData/useForm: an object entity reference needs string `app` and `model` properties",
       );
     }
-    const resource = manifest?.resources.find(
-      (r) => r.app === app && r.model === model,
-    );
+    const resource =
+      manifest?.resources.find((r) => r.app === app && r.model === model) ??
+      (isResourceValue(ref) ? resourceModel(ref) : undefined);
     const opts = (ref as { options?: { transitions?: unknown } }).options;
     return resolved(app, model, resource, opts?.transitions);
   }

package/hooks/form/entity-form.ts

@@ -51,11 +51,8 @@ import {
 import { useRastackManifest } from "../manifest";
 import type { EntityTypes, RegisteredEntityKey } from "../registry";
 import { writeSchema } from "../../src/compile/openapi";
-import type {
-  FieldModel,
-  Manifest,
-  ResourceModel,
-} from "../../src/compile/model";
+import type { FieldModel, ResourceModel } from "../../src/compile/model";
+import { toManifest, type ManifestInput } from "../../src/define/manifest";
 import {
   allowedTransitions,
   applyTransition,
@@ -71,8 +68,11 @@ export interface UseEntityFormOptions<TRow> {
   /** `"put"` to save with PUT; default is POST on create / PATCH on update. */
   updateType?: FormUpdate;
   onSuccess?: (row: TRow) => void;
-  /** Manifest override — tests, or callers outside `<RAStackProvider>`. */
-  manifest?: Manifest;
+  /**
+   * Manifest override — tests, or callers outside `<RAStackProvider>`.
+   * Accepts a compiled manifest or `resource()` definitions (array/module).
+   */
+  manifest?: ManifestInput;
 }
 
 /** One transition available from the record's current state. */
@@ -144,7 +144,11 @@ export function useEntityForm<TRow = any, TName extends string = string>(
   options: UseEntityFormOptions<TRow> = {},
 ): EntityFormResult<TRow, TName> {
   const contextManifest = useRastackManifest();
-  const manifest = options.manifest ?? contextManifest;
+  const optionManifest = useMemo(
+    () => toManifest(options.manifest),
+    [options.manifest],
+  );
+  const manifest = optionManifest ?? contextManifest;
   const resolvedEntity = useMemo(
     () => resolveEntityRef(entity, manifest),
     [entity, manifest],

package/hooks/manifest.ts

@@ -1,11 +1,14 @@
 /**
- * The compiled manifest (`schema.rastack.json`) 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.
+ * 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
- * piece of compiler output the client needs). Hooks read it with
+ * 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.
  */
@@ -13,29 +16,62 @@
 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. */
-  manifest?: Manifest | object | string;
+  /**
+   * `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 compiled manifest to every `useData`/`useForm` beneath it. */
+/** Provide the manifest to every `useData`/`useForm` beneath it. */
 export function RastackManifestProvider(props: RastackManifestProviderProps) {
   const { manifest, children } = props;
-  const value = useMemo<Manifest | undefined>(() => {
-    if (manifest === undefined || manifest === null) return undefined;
-    if (typeof manifest === "string") return JSON.parse(manifest) as Manifest;
-    return manifest as Manifest;
-  }, [manifest]);
+  const value = useMemo<Manifest | undefined>(
+    () => toManifest(manifest) ?? getGlobalManifest(),
+    [manifest],
+  );
   return createElement(RastackManifestContext.Provider, { value }, children);
 }
 
-/** The compiled manifest, when a provider supplies one. */
+/**
+ * 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);
+  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

@@ -7,8 +7,27 @@
  *
  * 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. **You don't write it by hand**: `rastack compile`
- * emits `rastack-env.d.ts` alongside the manifest —
+ * 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" {
@@ -18,12 +37,10 @@
  * }
  * ```
  *
- * — one entry per class/interface entity in the compiled graph, pointing at
- * *your* declaration (types only, no runtime code, nothing to import). With
- * the 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).
+ * 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. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rastack",
-  "version": "0.0.50",
+  "version": "0.0.52",
   "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/index.ts

@@ -1,10 +1,6 @@
 export * from "./types";
 export * from "./provider";
-export {
-  createWasmAdapter,
-  createEngine,
-  defaultEngineLoader,
-} from "./wasm";
+export { createWasmAdapter, createEngine, defaultEngineLoader } from "./wasm";
 export {
   WarehousePersistence,
   seedFromIceberg,