rastack 0.0.50 → 0.0.52

package/src/define/index.ts

@@ -23,14 +23,32 @@
  * ```
  */
 
+/**
+ * Every constraint a scalar builder may be handed, merged — the shape the
+ * runtime value carries so a manifest can be assembled without the compiler.
+ */
+export interface ScalarFieldOptions {
+  maxLength?: number;
+  unique?: boolean;
+  primaryKey?: boolean;
+  default?: unknown;
+  null?: boolean;
+  autoNow?: boolean;
+  autoNowAdd?: boolean;
+}
+
 /**
  * A scalar field. The literal `__rastackScalar` type is what the compiler
  * reads; `Nullable` phantom-carries the `null: true` option so {@link RowOf}
- * can add `| null` to the inferred row type.
+ * can add `| null` to the inferred row type. The authored options ride along
+ * on the runtime value too, so `manifestFromResources()` can build the same
+ * manifest `rastack compile` emits — with no compile step at all.
  */
 export interface Scalar<T extends string, Nullable extends boolean = boolean> {
   readonly __rastackScalar: T;
   readonly __rastackNullable?: Nullable;
+  /** The constraint options as authored — carried at runtime. */
+  readonly options?: ScalarFieldOptions;
 }
 
 /** Whether an options literal declares `null: true` (as a type). */
@@ -38,12 +56,16 @@ type NullOf<O> = O extends { null: true } ? true : false;
 
 /**
  * A foreign-key field. `App`/`Model` are carried as string-literal type
- * arguments so the compiler can recover the relation target purely from types.
+ * arguments so the compiler can recover the relation target purely from
+ * types; the target thunk is *also* kept on the runtime value so
+ * `manifestFromResources()` can recover the relation with no compiler.
  */
 export interface Ref<App extends string, Model extends string> {
   readonly __rastackRef: true;
   readonly __app: App;
   readonly __model: Model;
+  /** The authored `() => Resource` thunk — carried at runtime. */
+  readonly target?: () => ResourceType<App, Model, any>;
 }
 
 export interface StringOptions {
@@ -73,51 +95,66 @@ export interface DateOptions {
 }
 
 /**
- * Field builders. Each returns a phantom value whose *type* encodes the field
- * kind; the runtime object is never used at compile time (the compiler analyses
- * the source, it does not execute it) but is real so the DSL is also usable at
- * runtime if a consumer wants it.
+ * Field builders. Each returns a value whose *type* encodes the field kind
+ * (what the compiler reads — it analyses the source, it does not execute it)
+ * and whose runtime shape keeps the authored options/target, so the same
+ * definition doubles as its own manifest via `manifestFromResources()`.
  */
 export const s = {
   string<const O extends StringOptions = StringOptions>(
-    _opts?: O,
+    opts?: O,
   ): Scalar<"string", NullOf<O>> {
-    return { __rastackScalar: "string" } as Scalar<"string", NullOf<O>>;
+    return { __rastackScalar: "string", options: opts } as Scalar<
+      "string",
+      NullOf<O>
+    >;
   },
   int<const O extends NumberOptions = NumberOptions>(
-    _opts?: O,
+    opts?: O,
   ): Scalar<"int", NullOf<O>> {
-    return { __rastackScalar: "int" } as Scalar<"int", NullOf<O>>;
+    return { __rastackScalar: "int", options: opts } as Scalar<"int", NullOf<O>>;
   },
   float<const O extends NumberOptions = NumberOptions>(
-    _opts?: O,
+    opts?: O,
   ): Scalar<"float", NullOf<O>> {
-    return { __rastackScalar: "float" } as Scalar<"float", NullOf<O>>;
+    return { __rastackScalar: "float", options: opts } as Scalar<
+      "float",
+      NullOf<O>
+    >;
   },
   bool<const O extends BoolOptions = BoolOptions>(
-    _opts?: O,
+    opts?: O,
   ): Scalar<"bool", NullOf<O>> {
-    return { __rastackScalar: "bool" } as Scalar<"bool", NullOf<O>>;
+    return { __rastackScalar: "bool", options: opts } as Scalar<
+      "bool",
+      NullOf<O>
+    >;
   },
   datetime<const O extends DateOptions = DateOptions>(
-    _opts?: O,
+    opts?: O,
   ): Scalar<"datetime", NullOf<O>> {
-    return { __rastackScalar: "datetime" } as Scalar<"datetime", NullOf<O>>;
+    return { __rastackScalar: "datetime", options: opts } as Scalar<
+      "datetime",
+      NullOf<O>
+    >;
   },
   uuid<const O extends StringOptions = StringOptions>(
-    _opts?: O,
+    opts?: O,
   ): Scalar<"uuid", NullOf<O>> {
-    return { __rastackScalar: "uuid" } as Scalar<"uuid", NullOf<O>>;
+    return { __rastackScalar: "uuid", options: opts } as Scalar<
+      "uuid",
+      NullOf<O>
+    >;
   },
   /**
    * A foreign key. The target is `() => SomeResource`; the compiler resolves
-   * the relation from the *type* `Ref<App, Model>` this returns — it does not
-   * need to run the thunk.
+   * the relation from the *type* `Ref<App, Model>` this returns, and the
+   * runtime keeps the thunk so `manifestFromResources()` can resolve it too.
    */
   ref<A extends string, M extends string>(
-    _thunk: () => ResourceType<A, M, any>,
+    thunk: () => ResourceType<A, M, any>,
   ): Ref<A, M> {
-    return { __rastackRef: true } as Ref<A, M>;
+    return { __rastackRef: true, target: thunk } as Ref<A, M>;
   },
 };
 
@@ -140,18 +177,36 @@ export interface SyncOptions {
  * - `ownerField` — the field that records the owning identity (the verified
  *   token `sub`). Rows are only listed/read/written by their owner; the field
  *   is stamped from the token on create and immutable on update.
+ * - `groupField` — the field that records the owning *group* (a verified
+ *   `cognito:groups` value). Rows are only visible to members of their group,
+ *   and the dataset defaults to per-group physical partitioning.
  * - `scope: "owner"` — additionally *physically* partitions the resource's
  *   Iceberg table per identity (`tenants/{sub}/{app}.db/{model}/…`), so
  *   object-storage credentials (e.g. Cognito Identity Pool temp creds) can be
  *   IAM-restricted to `tenants/${"${cognito-identity.amazonaws.com:sub}"}/*`.
+ *   `scope: "group"` partitions per group instead (`groups/{name}/…`);
+ *   `scope: "shared"` keeps one table.
  * - `adminGroups` — token groups (`cognito:groups`) that bypass row filters.
+ *
+ * Class/interface entities express the same policy in the type system — the
+ * `Owner`/`Group` field brands and `IsAuthenticated`/`AdminGroups<…>`/
+ * `OwnerScoped` markers from `rastack/auth`.
  */
 export interface AccessOptions {
   ownerField?: string;
-  scope?: "owner" | "shared";
+  groupField?: string;
+  scope?: "owner" | "group" | "shared";
   adminGroups?: string[];
 }
 
+/**
+ * The resource-level permission gate — which paths an identity may hit at all.
+ * Enforced by `rastack-api-core` before any row is read; mirrored client-side
+ * by `rastack/auth`'s `can()` so components hide what the server would reject.
+ * Unset means `authenticated` — secure by default.
+ */
+export type Permission = "authenticatedOrReadOnly" | "authenticated" | "public";
+
 /**
  * One edge of a resource's state machine. `from` is the state (or states) the
  * transition may fire from, `to` the state it enters, and `set` the effect —
@@ -210,7 +265,7 @@ export interface ResourceOptions {
   /** Local-first replication config. */
   sync?: SyncOptions;
   /** Access policy (secure by default). */
-  permission?: "authenticatedOrReadOnly" | "authenticated" | "public";
+  permission?: Permission;
   /** Row-level security + physical tenant partitioning. */
   access?: AccessOptions;
   /** Declarative state machine over one field, enforced on every write surface. */
@@ -310,3 +365,42 @@ export type RowOf<R> =
   R extends ResourceType<string, string, infer F, ResourceOptions>
     ? { id: number | string } & { [K in keyof F]: FieldValueOf<F[K]> }
     : never;
+
+/** The `"app.model"` registry key a `resource()` definition implies. */
+export type EntityKeyOf<R> =
+  R extends ResourceType<infer A, infer M, any, ResourceOptions>
+    ? `${A}.${M}`
+    : never;
+
+/**
+ * The `EntityTypes` registry entries a module of `resource()` definitions
+ * implies — the *hand-written* alternative to the `rastack-env.d.ts` that
+ * `rastack compile` emits. Point it at your resources module once and the
+ * registry tracks it forever, with no compile step in the loop:
+ *
+ * ```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")> {}
+ * }
+ * ```
+ *
+ * Non-resource exports are dropped, so `typeof import("…")` over a whole
+ * module is safe. (Class entities carry their own row type — they never need
+ * the registry; interfaces still register via the compile-emitted file.)
+ */
+export type EntityTypesOf<M> = {
+  [K in keyof M as EntityKeyOf<M[K]>]: RowOf<M[K]>;
+};
+
+// The runtime manifest builder — a resource() definition is its own manifest.
+export {
+  isResourceValue,
+  manifestFromResources,
+  resourceModel,
+  toManifest,
+} from "./manifest";
+export type { AnyResourceValue, ManifestInput } from "./manifest";
+export type { Manifest, ResourceModel } from "../compile/model";

package/src/define/manifest.ts

@@ -0,0 +1,287 @@
+/**
+ * The runtime manifest builder — `resource()` definitions are their own
+ * manifest, **no `rastack compile` step required**.
+ *
+ * The DSL values carry everything the canonical manifest needs at runtime
+ * (field kinds, constraint options, FK target thunks, resource options), so
+ * this module assembles the exact `schema.rastack.json` shape the compiler
+ * emits — same fields, same relations, same normalisation — as a pure
+ * function:
+ *
+ * ```tsx
+ * import { Airport, Terminal, Flight } from "./resources/airports";
+ *
+ * <RAStackProvider mode="local" manifest={[Airport, Terminal, Flight]}>
+ * ```
+ *
+ * The compiler (`tools/src/compile/analyze.ts`) imports the option
+ * normalisers below, so the two paths cannot drift: `rastack compile` remains
+ * the way to get class/interface entities, `openapi.json`, and the artifacts
+ * the Rust backend and admin read — but the typed hooks and the in-browser
+ * engine need only this.
+ *
+ * Everything here is browser-safe: no `typescript`, no filesystem.
+ */
+
+import type {
+  AccessModel,
+  AdminModel,
+  FieldModel,
+  Manifest,
+  RelationModel,
+  ResourceModel,
+  ScalarType,
+  SyncModel,
+} from "../compile/model";
+import { normalizeTransitions } from "../validate/transitions";
+import type { ResourceOptions, ResourceType } from "./index";
+
+/** Any `resource()` value, generics erased. */
+export type AnyResourceValue = ResourceType<string, string, any, any>;
+
+/** Everything `toManifest()` understands — see {@link toManifest}. */
+export type ManifestInput =
+  | Manifest
+  | object
+  | string
+  | AnyResourceValue
+  | readonly AnyResourceValue[];
+
+/** Whether a value is a `resource()` definition. */
+export function isResourceValue(value: unknown): value is AnyResourceValue {
+  return (
+    !!value &&
+    typeof value === "object" &&
+    (value as { __rastack?: unknown }).__rastack === "resource"
+  );
+}
+
+/**
+ * One `resource()` value → its canonical {@link ResourceModel} — the same
+ * shape `rastack compile` derives from the source, produced from the runtime
+ * value instead.
+ */
+export function resourceModel(res: AnyResourceValue): ResourceModel {
+  const fields: FieldModel[] = [];
+  const relations: RelationModel[] = [];
+
+  for (const [name, value] of Object.entries(
+    (res.fields ?? {}) as Record<string, unknown>,
+  )) {
+    const field = runtimeField(res, name, value);
+    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 = (res.options ?? {}) as ResourceOptions;
+  const model: ResourceModel = {
+    app: res.app,
+    model: res.model,
+    fields,
+    relations,
+    sync: normaliseSync(options.sync),
+    admin: normaliseAdmin(options.admin),
+    search: options.search,
+    ordering: options.ordering,
+    permission: options.permission,
+    access: normaliseAccess(options.access),
+  };
+  applyTransitions(model, options.transitions);
+  return model;
+}
+
+/** Resolve one runtime field value to its {@link FieldModel}. */
+function runtimeField(
+  res: AnyResourceValue,
+  name: string,
+  value: unknown,
+): FieldModel | undefined {
+  if (!value || typeof value !== "object") return undefined;
+  const field = value as {
+    __rastackRef?: unknown;
+    __rastackScalar?: unknown;
+    target?: () => AnyResourceValue;
+    options?: Record<string, unknown>;
+  };
+
+  // Foreign key: the runtime value keeps the `() => Resource` thunk, so the
+  // relation target is recovered by calling it — the runtime twin of the
+  // compiler's "read the Ref<App, Model> type arguments" step.
+  if (field.__rastackRef === true) {
+    const target = field.target?.();
+    if (!isResourceValue(target)) {
+      throw new Error(
+        `manifestFromResources: ${res.app}.${res.model}.${name} is an s.ref(...) whose target thunk did not return a resource() value`,
+      );
+    }
+    return {
+      name,
+      type: "fk",
+      relation: { app: target.app, model: target.model },
+    };
+  }
+
+  if (typeof field.__rastackScalar !== "string") return undefined;
+  const model: FieldModel = {
+    name,
+    type: field.__rastackScalar as ScalarType,
+  };
+  // Constraint mapping mirrors the compiler's `applyConstraints` exactly.
+  const opts = field.options;
+  if (opts && typeof opts === "object") {
+    if (typeof opts.maxLength === "number") model.maxLength = opts.maxLength;
+    if (opts.unique === true) model.unique = true;
+    if (opts.primaryKey === true) model.primaryKey = true;
+    if (opts.null === true) model.null = true;
+    if (opts.default !== undefined) model.default = opts.default;
+  }
+  return model;
+}
+
+/**
+ * Assemble the canonical manifest from `resource()` values at runtime —
+ * accepts the values themselves, arrays of them, or whole module namespaces
+ * (`import * as resources from "./resources"`), in any mix. Output order
+ * matches the compiler's (app, then model), so the result is byte-for-byte
+ * the manifest `rastack compile` would emit for the same definitions.
+ */
+export function manifestFromResources(
+  ...inputs: Array<
+    AnyResourceValue | readonly AnyResourceValue[] | Record<string, unknown>
+  >
+): Manifest {
+  const resources: ResourceModel[] = collectResources(inputs).map(resourceModel);
+  resources.sort((a, b) =>
+    a.app === b.app ? a.model.localeCompare(b.model) : a.app.localeCompare(b.app),
+  );
+  return { version: 1, resources };
+}
+
+/** Flatten values / arrays / module namespaces into the resource list. */
+function collectResources(inputs: unknown[]): AnyResourceValue[] {
+  const out: AnyResourceValue[] = [];
+  const seen = new Set<AnyResourceValue>();
+  const push = (res: AnyResourceValue) => {
+    if (!seen.has(res)) {
+      seen.add(res);
+      out.push(res);
+    }
+  };
+  for (const input of inputs) {
+    if (isResourceValue(input)) {
+      push(input);
+    } else if (Array.isArray(input)) {
+      for (const item of input) if (isResourceValue(item)) push(item);
+    } else if (input && typeof input === "object") {
+      for (const item of Object.values(input)) {
+        if (isResourceValue(item)) push(item);
+      }
+    }
+  }
+  return out;
+}
+
+/**
+ * Normalise anything a provider may be handed as "the manifest": a compiled
+ * manifest (object or JSON string), a `resource()` value, an array of them,
+ * or a module namespace containing them. This is what lets
+ * `<RAStackProvider manifest={[Airport, Terminal]}>` work with no compiled
+ * `schema.rastack.json` anywhere.
+ */
+export function toManifest(
+  input: ManifestInput | null | undefined,
+): Manifest | undefined {
+  if (input === null || input === undefined) return undefined;
+  if (typeof input === "string") return JSON.parse(input) as Manifest;
+  if (Array.isArray(input) || isResourceValue(input)) {
+    return manifestFromResources(
+      input as AnyResourceValue | readonly AnyResourceValue[],
+    );
+  }
+  const record = input as Record<string, unknown>;
+  // A compiled manifest passes through untouched.
+  if (Array.isArray(record.resources)) return input as Manifest;
+  // A module namespace of resource() exports builds one.
+  const values = Object.values(record).filter(isResourceValue);
+  if (values.length) return manifestFromResources(values);
+  return input as Manifest;
+}
+
+// ---------------------------------------------------------------------------
+// Option normalisers — shared with the compiler (`compile/analyze.ts`), so
+// the runtime and compiled manifests can never disagree about a resource.
+// ---------------------------------------------------------------------------
+
+/**
+ * Attach a normalised `transitions` block to a resource and derive what the
+ * machine implies about its state field: the `states` become the field's
+ * allowed-value set (`enum` in OpenAPI, the `member` gate in validation), and
+ * `initial` becomes its default when the field doesn't declare one.
+ */
+export function applyTransitions(resource: ResourceModel, raw: unknown): void {
+  const transitions = normalizeTransitions(raw);
+  if (!transitions) return;
+  resource.transitions = transitions;
+
+  const stateField = resource.fields.find((f) => f.name === transitions.field);
+  if (stateField && stateField.type !== "fk") {
+    stateField.options = [...transitions.states];
+    if (stateField.default === undefined && transitions.initial !== undefined) {
+      stateField.default = transitions.initial;
+    }
+  }
+}
+
+export 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;
+}
+
+export 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 (typeof access.groupField === "string") model.groupField = access.groupField;
+  if (
+    access.scope === "owner" ||
+    access.scope === "group" ||
+    access.scope === "shared"
+  ) {
+    model.scope = access.scope;
+  } else if (model.groupField) {
+    // Group-owned datasets are physically partitioned per group by default —
+    // that is their point. `scope: "shared"` opts out explicitly.
+    model.scope = "group";
+  }
+  if (Array.isArray(access.adminGroups)) {
+    model.adminGroups = access.adminGroups.filter(
+      (g: unknown) => typeof g === "string",
+    );
+  }
+  return Object.keys(model).length ? model : undefined;
+}
+
+export 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/define/markers.ts

@@ -0,0 +1,83 @@
+/**
+ * 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.
+ */
+
+/** The permission gate carried in the type system. */
+export interface PermissionOf<P extends string> {
+  readonly __rastackPermission?: P;
+}
+
+/** Every path requires a verified identity (this is also the default). */
+export interface IsAuthenticated extends PermissionOf<"authenticated"> {}
+
+/** Anonymous callers may read (list/retrieve); writes require identity. */
+export interface IsAuthenticatedOrReadOnly extends PermissionOf<"authenticatedOrReadOnly"> {}
+
+/** No gate — every caller may read and write. Opt-in, never the default. */
+export interface IsPublic extends PermissionOf<"public"> {}
+
+/**
+ * Token groups (`cognito:groups`) that bypass row-level security on this
+ * entity — the "is admin" role, driven from scopes: `implements
+ * AdminGroups<"staff" | "ops">`. Members see and act on every row.
+ */
+export interface AdminGroups<G extends string> {
+  readonly __rastackAdminGroups?: G;
+}
+
+/** Storage scope carried in the type system. */
+export interface ScopeOf<S extends string> {
+  readonly __rastackScope?: S;
+}
+
+/**
+ * Physically partition the entity's table per identity
+ * (`tenants/{sub}/…`) — the prefix object-storage IAM can fence per user.
+ * Combine with an `Owner` field brand.
+ */
+export interface OwnerScoped extends ScopeOf<"owner"> {}
+
+/**
+ * Physically partition the entity's table per group (`groups/{name}/…`).
+ * This is the default whenever a `Group` field brand is present — declare it
+ * only for emphasis or with a JSDoc-configured group field.
+ */
+export interface GroupScoped extends ScopeOf<"group"> {}
+
+/**
+ * Keep rows in one shared table (row-level filters still apply). Use to opt a
+ * `Group`-branded entity out of the default per-group physical partitioning.
+ */
+export interface SharedStorage extends ScopeOf<"shared"> {}

package/src/define/types.ts

@@ -0,0 +1,11 @@
+/**
+ * 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";