rastack 0.0.50 → 0.0.52

package/dist/define/markers.js

@@ -0,0 +1,37 @@
+"use strict";
+/**
+ * Entity-level authorization markers — auth as *TypeScript types*.
+ *
+ * Class and interface entities have no options bag, so their access policy is
+ * expressed the same way their columns are: in the type system. Attach a
+ * marker with `implements` (classes) or `extends` (interfaces) and the
+ * compiler reads the policy straight off the heritage clause:
+ *
+ * ```ts
+ * import { AdminGroups, IsAuthenticated, Owner, Group } from "rastack/auth";
+ *
+ * // Per-user rows: RLS on `owner`, staff sees everything.
+ * export class Itinerary implements IsAuthenticated, AdminGroups<"staff"> {
+ *   owner!: string & Owner;
+ *   notes!: string;
+ * }
+ *
+ * // Group-owned dataset: rows belong to a team and are *physically stored*
+ * // under that team's own storage prefix (groups/{team}/…).
+ * export class Report implements IsAuthenticated, AdminGroups<"staff"> {
+ *   team!: string & Group;
+ *   title!: string;
+ * }
+ * ```
+ *
+ * The markers are phantom types: every property is optional and never exists
+ * at runtime, so `implements` needs no members and instances stay plain data.
+ * Each marker family uses its own phantom key, so markers combine freely —
+ * while two *permission* markers on one entity conflict in the type checker,
+ * which is exactly right.
+ *
+ * JSDoc equivalents exist for every marker (`@rastackPermission`,
+ * `@rastackAdminGroups staff, ops`, `@rastackScope owner|group|shared`, and
+ * field-level `@owner` / `@group`), mirroring the column-constraint tags.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/define/types.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The `rastack/types` compatibility surface — one module aliasing the two
+ * split authoring subpaths: `rastack/db` (the `DbConfig` column brands) and
+ * `rastack/auth` (the entity-level auth markers + `Owner`/`Group` brands).
+ * Prefer those; everything stays re-exported here so existing imports keep
+ * working. The compiler maps all three specifiers (see `compile/program.ts`);
+ * the published package re-exports the same modules from `tools/types.ts`.
+ */
+export * from "./db";
+export * from "./markers";

package/dist/define/types.js

@@ -0,0 +1,26 @@
+"use strict";
+/**
+ * The `rastack/types` compatibility surface — one module aliasing the two
+ * split authoring subpaths: `rastack/db` (the `DbConfig` column brands) and
+ * `rastack/auth` (the entity-level auth markers + `Owner`/`Group` brands).
+ * Prefer those; everything stays re-exported here so existing imports keep
+ * working. The compiler maps all three specifiers (see `compile/program.ts`);
+ * the published package re-exports the same modules from `tools/types.ts`.
+ */
+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 __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./db"), exports);
+__exportStar(require("./markers"), exports);

package/dist/plugin/core.d.ts

@@ -0,0 +1,108 @@
+/**
+ * The dev-server schema compiler — the way around "classes need a compile
+ * step".
+ *
+ * Class/interface entities have no runtime shape (TypeScript erases their
+ * types), so *something* must run the `ts.Program` + `TypeChecker` to read
+ * fields, `DbConfig` brands and FK types off them. The insight is that it
+ * doesn't have to be a command the developer runs: this module packages the
+ * same `analyzeProject`/`compile` pass the CLI uses so it can live **inside
+ * the dev server that is already running** — a bundler plugin
+ * (`rastackPlugin`, Vite/Rollup-compatible) or a bare filesystem watcher
+ * (`startRastackWatcher`, for anything else). The schema recompiles on every
+ * save, the app imports it as the `virtual:rastack-manifest` module, and
+ * `rastack-env.d.ts` is rewritten so string-key row types stay fresh — the
+ * developer never runs `rastack compile`.
+ *
+ * Design mirrors the rest of `tools/src`: the decisions live here as pure
+ * (or thin-IO) functions, tested in `tools/test/plugin.spec.ts`; the plugin
+ * object in `./index.ts` is a shell over {@link createSchemaState}.
+ */
+import type { EntityDiagnostic, Manifest } from "../compile";
+/** The module id apps import the live manifest from. */
+export declare const VIRTUAL_MANIFEST_ID = "virtual:rastack-manifest";
+/** The resolved (bundler-internal) id — Rollup convention: `\0` prefix. */
+export declare const RESOLVED_MANIFEST_ID: string;
+/**
+ * The auto-registration module the plugin injects into `index.html`: it sets
+ * `globalThis.__RASTACK_MANIFEST__` before the app boots, which is what lets
+ * `<RAStackProvider mode="local">` (and bare `useData(Airport)`) run with
+ * **no manifest wiring in app code at all**. Kept un-prefixed (no `\0`) so
+ * its dev-server URL is a plain `/@id/…`.
+ */
+export declare const VIRTUAL_REGISTER_ID = "virtual:rastack-manifest/register";
+/** The key the register module assigns (mirrored in `rastack/hooks`). */
+export declare const GLOBAL_MANIFEST_KEY = "__RASTACK_MANIFEST__";
+export interface RastackPluginOptions {
+    /**
+     * Directory (or single file) scanned for entities — classes, interfaces
+     * and `resource()` calls alike, recursively (co-located definitions work).
+     * Default `"resources"`; pass `"src"` (or `"."`) for co-located entities.
+     */
+    resourcesDir?: string;
+    /**
+     * Where the artifacts land: `schema.rastack.json`, `openapi.json`,
+     * `rastack-env.d.ts` (the string-key type registry) and
+     * `rastack-plugin.d.ts` (types for the virtual module). Default
+     * `".rastack"` — include it in `tsconfig.json` once.
+     */
+    outDir?: string;
+    /** Skip writing the artifacts to disk (virtual module only). Default false. */
+    emitFiles?: boolean;
+    /** Where compile problems are reported. Default `console.error`. */
+    onError?: (error: unknown) => void;
+}
+export interface ResolvedPluginOptions {
+    resourcesDir: string;
+    outDir: string;
+    emitFiles: boolean;
+    onError: (error: unknown) => void;
+}
+export declare function resolveOptions(options?: RastackPluginOptions, root?: string): ResolvedPluginOptions;
+/**
+ * Whether a changed file should trigger a schema recompile: a `.ts`/`.tsx`
+ * source under the scanned directory that is not itself an emitted artifact.
+ */
+export declare function isEntitySource(file: string, options: Pick<ResolvedPluginOptions, "resourcesDir" | "outDir">): boolean;
+/** The virtual module's source — the manifest as a plain ES module. */
+export declare function manifestModuleCode(manifest: Manifest): string;
+/**
+ * The register module's source: import the live manifest, publish it on the
+ * global the runtime falls back to. A separate module (rather than a side
+ * effect of the manifest module) so explicit `virtual:rastack-manifest`
+ * importers stay side-effect-free.
+ */
+export declare function registerModuleCode(): string;
+/** Types for the virtual module, written once beside `rastack-env.d.ts`. */
+export declare function virtualModuleDts(): string;
+export interface SchemaState {
+    /**
+     * The virtual module's current source. Compiles (lazily) when stale; on a
+     * compile error reports via `onError` and keeps serving the last good
+     * manifest — a half-typed entity must not blank the running app.
+     */
+    code(): string;
+    /** The current manifest (same laziness/fallback as {@link code}). */
+    manifest(): Manifest;
+    /** Mark the schema stale — the next `code()`/`manifest()` recompiles. */
+    invalidate(): void;
+    /** The error from the most recent failed compile, if it is still failing. */
+    error(): unknown;
+    /** Non-error diagnostics from the last successful compile. */
+    diagnostics(): EntityDiagnostic[];
+    options: ResolvedPluginOptions;
+}
+/**
+ * The plugin's whole brain: lazy compile, invalidation, keep-last-good.
+ * Both the bundler plugin and the bare watcher drive this one object.
+ */
+export declare function createSchemaState(options?: RastackPluginOptions, root?: string): SchemaState;
+/**
+ * One compile pass: the same artifacts `rastack compile` writes (manifest,
+ * OpenAPI, `rastack-env.d.ts`), plus the virtual module's type declaration.
+ * With `emitFiles: false` it only analyses (nothing touches disk).
+ */
+export declare function runCompile(options: ResolvedPluginOptions): {
+    manifest: Manifest;
+    diagnostics: EntityDiagnostic[];
+};

package/dist/plugin/core.js

@@ -0,0 +1,198 @@
+"use strict";
+/**
+ * The dev-server schema compiler — the way around "classes need a compile
+ * step".
+ *
+ * Class/interface entities have no runtime shape (TypeScript erases their
+ * types), so *something* must run the `ts.Program` + `TypeChecker` to read
+ * fields, `DbConfig` brands and FK types off them. The insight is that it
+ * doesn't have to be a command the developer runs: this module packages the
+ * same `analyzeProject`/`compile` pass the CLI uses so it can live **inside
+ * the dev server that is already running** — a bundler plugin
+ * (`rastackPlugin`, Vite/Rollup-compatible) or a bare filesystem watcher
+ * (`startRastackWatcher`, for anything else). The schema recompiles on every
+ * save, the app imports it as the `virtual:rastack-manifest` module, and
+ * `rastack-env.d.ts` is rewritten so string-key row types stay fresh — the
+ * developer never runs `rastack compile`.
+ *
+ * Design mirrors the rest of `tools/src`: the decisions live here as pure
+ * (or thin-IO) functions, tested in `tools/test/plugin.spec.ts`; the plugin
+ * object in `./index.ts` is a shell over {@link createSchemaState}.
+ */
+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.GLOBAL_MANIFEST_KEY = exports.VIRTUAL_REGISTER_ID = exports.RESOLVED_MANIFEST_ID = exports.VIRTUAL_MANIFEST_ID = void 0;
+exports.resolveOptions = resolveOptions;
+exports.isEntitySource = isEntitySource;
+exports.manifestModuleCode = manifestModuleCode;
+exports.registerModuleCode = registerModuleCode;
+exports.virtualModuleDts = virtualModuleDts;
+exports.createSchemaState = createSchemaState;
+exports.runCompile = runCompile;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const compile_1 = require("../compile");
+/** The module id apps import the live manifest from. */
+exports.VIRTUAL_MANIFEST_ID = "virtual:rastack-manifest";
+/** The resolved (bundler-internal) id — Rollup convention: `\0` prefix. */
+exports.RESOLVED_MANIFEST_ID = "\0" + exports.VIRTUAL_MANIFEST_ID;
+/**
+ * The auto-registration module the plugin injects into `index.html`: it sets
+ * `globalThis.__RASTACK_MANIFEST__` before the app boots, which is what lets
+ * `<RAStackProvider mode="local">` (and bare `useData(Airport)`) run with
+ * **no manifest wiring in app code at all**. Kept un-prefixed (no `\0`) so
+ * its dev-server URL is a plain `/@id/…`.
+ */
+exports.VIRTUAL_REGISTER_ID = "virtual:rastack-manifest/register";
+/** The key the register module assigns (mirrored in `rastack/hooks`). */
+exports.GLOBAL_MANIFEST_KEY = "__RASTACK_MANIFEST__";
+function resolveOptions(options = {}, root = process.cwd()) {
+    return {
+        resourcesDir: path.resolve(root, options.resourcesDir ?? "resources"),
+        outDir: path.resolve(root, options.outDir ?? ".rastack"),
+        emitFiles: options.emitFiles !== false,
+        onError: options.onError ??
+            ((error) => console.error(`[rastack] schema compile failed — serving the last good manifest\n` +
+                `${error instanceof Error ? error.message : String(error)}`)),
+    };
+}
+/**
+ * Whether a changed file should trigger a schema recompile: a `.ts`/`.tsx`
+ * source under the scanned directory that is not itself an emitted artifact.
+ */
+function isEntitySource(file, options) {
+    const resolved = path.resolve(file);
+    if (!/\.tsx?$/.test(resolved) || resolved.endsWith(".d.ts"))
+        return false;
+    if (within(resolved, options.outDir))
+        return false;
+    return (within(resolved, options.resourcesDir) || resolved === options.resourcesDir);
+}
+function within(file, dir) {
+    const rel = path.relative(dir, file);
+    return rel !== "" && !rel.startsWith("..") && !path.isAbsolute(rel);
+}
+/** The virtual module's source — the manifest as a plain ES module. */
+function manifestModuleCode(manifest) {
+    const json = JSON.stringify(manifest);
+    return (`// virtual:rastack-manifest — compiled by the rastack dev-server plugin.\n` +
+        `const manifest = ${json};\n` +
+        `export default manifest;\n` +
+        `export { manifest };\n`);
+}
+/**
+ * The register module's source: import the live manifest, publish it on the
+ * global the runtime falls back to. A separate module (rather than a side
+ * effect of the manifest module) so explicit `virtual:rastack-manifest`
+ * importers stay side-effect-free.
+ */
+function registerModuleCode() {
+    return (`// ${exports.VIRTUAL_REGISTER_ID} — auto-injected by the rastack plugin.\n` +
+        `import manifest from ${JSON.stringify(exports.VIRTUAL_MANIFEST_ID)};\n` +
+        `globalThis.${exports.GLOBAL_MANIFEST_KEY} = manifest;\n` +
+        `export default manifest;\n`);
+}
+/** Types for the virtual module, written once beside `rastack-env.d.ts`. */
+function virtualModuleDts() {
+    return ("// Generated by the rastack plugin — do not edit.\n" +
+        `declare module "${exports.VIRTUAL_MANIFEST_ID}" {\n` +
+        '  const manifest: import("rastack/define").Manifest;\n' +
+        "  export default manifest;\n" +
+        "  export { manifest };\n" +
+        "}\n");
+}
+/**
+ * The plugin's whole brain: lazy compile, invalidation, keep-last-good.
+ * Both the bundler plugin and the bare watcher drive this one object.
+ */
+function createSchemaState(options = {}, root) {
+    const resolved = resolveOptions(options, root);
+    let current = null;
+    let stale = true;
+    let lastError = undefined;
+    const recompile = () => {
+        try {
+            const result = runCompile(resolved);
+            current = { manifest: result.manifest, diagnostics: result.diagnostics };
+            lastError = undefined;
+        }
+        catch (error) {
+            lastError = error;
+            resolved.onError(error);
+            if (!current)
+                throw error; // no last-good manifest to fall back to
+        }
+        finally {
+            stale = false;
+        }
+    };
+    const ensure = () => {
+        if (stale || !current)
+            recompile();
+        return current;
+    };
+    return {
+        code: () => manifestModuleCode(ensure().manifest),
+        manifest: () => ensure().manifest,
+        invalidate: () => {
+            stale = true;
+        },
+        error: () => lastError,
+        diagnostics: () => ensure().diagnostics,
+        options: resolved,
+    };
+}
+/**
+ * One compile pass: the same artifacts `rastack compile` writes (manifest,
+ * OpenAPI, `rastack-env.d.ts`), plus the virtual module's type declaration.
+ * With `emitFiles: false` it only analyses (nothing touches disk).
+ */
+function runCompile(options) {
+    if (!options.emitFiles) {
+        // compile() always writes to disk; the analyse-only path applies the
+        // same error gate without touching the filesystem.
+        const { resources, diagnostics } = (0, compile_1.analyzeProject)(options.resourcesDir);
+        const errors = diagnostics.filter((d) => d.severity === "error");
+        if (errors.length)
+            throw new Error(errors.map((e) => e.message).join("\n"));
+        return { manifest: (0, compile_1.buildManifest)(resources), diagnostics };
+    }
+    const result = (0, compile_1.compile)(options.resourcesDir, options.outDir);
+    const dtsPath = path.join(options.outDir, "rastack-plugin.d.ts");
+    if (!fs.existsSync(dtsPath)) {
+        fs.writeFileSync(dtsPath, virtualModuleDts());
+    }
+    return { manifest: result.manifest, diagnostics: result.diagnostics };
+}

package/dist/plugin/index.d.ts

@@ -0,0 +1,112 @@
+/**
+ * `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.
+ */
+import { type RastackPluginOptions, type SchemaState } from "./core";
+export { createSchemaState, GLOBAL_MANIFEST_KEY, isEntitySource, manifestModuleCode, registerModuleCode, resolveOptions, RESOLVED_MANIFEST_ID, runCompile, VIRTUAL_MANIFEST_ID, VIRTUAL_REGISTER_ID, virtualModuleDts, } from "./core";
+export type { RastackPluginOptions, ResolvedPluginOptions, SchemaState, } from "./core";
+/** One HTML tag descriptor in Vite's `transformIndexHtml` shape. */
+export interface HtmlTagDescriptor {
+    tag: string;
+    attrs?: Record<string, string>;
+    children?: string;
+    injectTo?: "head" | "head-prepend" | "body" | "body-prepend";
+}
+/** The minimal bundler-plugin surface we emit (Vite superset of Rollup). */
+export interface RastackBundlerPlugin {
+    name: string;
+    buildStart(): void;
+    resolveId(id: string): string | undefined;
+    load(id: string): string | undefined;
+    watchChange(id: string): void;
+    /**
+     * Vite-only: auto-register the schema. Injects a module script that sets
+     * `globalThis.__RASTACK_MANIFEST__` before the app boots, so the provider
+     * and hooks need no `manifest` wiring at all. Object form with
+     * `order: "pre"` — the tag must be injected *before* Vite scans the HTML
+     * entry, or the build ships the virtual import verbatim.
+     */
+    transformIndexHtml: {
+        order: "pre";
+        handler(html: string, ctx?: {
+            server?: unknown;
+        }): HtmlTagDescriptor[];
+    };
+    /** Vite-only: recompile + hot-invalidate the virtual manifest module. */
+    handleHotUpdate(ctx: {
+        file: string;
+        server: {
+            moduleGraph: {
+                getModuleById(id: string): unknown;
+                invalidateModule(mod: any): void;
+            };
+        };
+        modules: unknown[];
+    }): unknown[] | void;
+    /** The live schema state — exposed for tests and advanced callers. */
+    api: SchemaState;
+}
+/**
+ * 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.
+ */
+export declare function rastackPlugin(options?: RastackPluginOptions): RastackBundlerPlugin;
+/** Alias so `import { rastack } from "rastack/plugin"` reads naturally. */
+export declare const rastack: typeof rastackPlugin;
+export interface RastackWatcher {
+    /** Stop watching. */
+    close(): void;
+    /** The live schema state (same object the recompiles flow through). */
+    state: SchemaState;
+}
+/**
+ * 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.
+ */
+export declare function startRastackWatcher(options?: RastackPluginOptions): RastackWatcher;