@lunora/server 1.0.0-alpha.2 → 1.0.0-alpha.4

package/dist/data-model.d.mts

@@ -49,6 +49,13 @@ interface QueryArgs<TDocument> {
   cursor?: null | string;
   limit?: number;
   orderBy?: OrderBy<TDocument>[];
+  /**
+  * Project each returned row down to these columns (plus the system fields
+  * `_id`/`_creationTime`, always retained). Trims wire payload for wide rows;
+  * relations requested via `with` are still attached. Reactivity is unaffected —
+  * the engine still reads the whole row to track dependencies.
+  */
+  select?: ReadonlyArray<keyof TDocument & string>;
   where?: Where<TDocument>;
 }
 /**
@@ -97,6 +104,12 @@ type WhereOf<DM, REL extends Record<keyof DM, object>, T extends keyof DM> = Rel
 /** {@link QueryArgs} with the relation-aware {@link WhereOf} `where` typing. */
 interface QueryArgsOf<DM, REL extends Record<keyof DM, object>, T extends keyof DM> {
   cursor?: null | string;
+  /**
+  * Include soft-deleted rows (`.softDelete()` tables only). Default hides them;
+  * `true` returns deleted rows alongside live ones. No effect on a table
+  * without `.softDelete()`.
+  */
+  includeDeleted?: boolean;
   limit?: number;
   orderBy?: OrderBy<DM[T]>[];
   where?: WhereOf<DM, REL, T>;
@@ -110,11 +123,15 @@ interface QueryPage<TDocument> {
 type NestedWithArgument<WK> = WK extends {
   with: infer NW;
 } ? NW : {};
+/** The nested `select` tuple inside a relation's with-value, or `undefined` (no projection). */
+type NestedSelectArgument<WK> = WK extends {
+  select: infer S;
+} ? S : undefined;
 /**
 * The `with` argument for table `T`: each relation can be `true` (load with no
-* refinements) or an object. `many` relations accept `where`/`orderBy`/`limit`
-* plus a nested `with`; `one` relations accept only a nested `with`. The
-* reserved `_count` key requests per-relation aggregate counts.
+* refinements) or an object. `many` relations accept `where`/`orderBy`/`limit`/
+* `select` plus a nested `with`; `one` relations accept `select` + a nested
+* `with`. The reserved `_count` key requests per-relation aggregate counts.
 */
 type WithArg<DM, REL extends Record<keyof DM, object>, T extends keyof DM> = { [K in keyof REL[T]]?: REL[T][K] extends {
   __relationKind: "many";
@@ -125,18 +142,24 @@ type WithArg<DM, REL extends Record<keyof DM, object>, T extends keyof DM> = { [
   __relationKind: "one";
   __target: infer Target extends keyof DM;
 } ? boolean | {
+  select?: ReadonlyArray<keyof DM[Target] & string>;
   with?: WithArg<DM, REL, Target>;
 } : never } & {
   _count?: { [K in keyof REL[T]]?: true };
 };
-/** Resolve a single relation descriptor + its with-value to the loaded type. */
+/**
+* Resolve a single relation descriptor + its with-value to the loaded type,
+* threading the nested `select` tuple into the projected child shape (the 5th
+* `LoadWith` arg) so `with: { author: { select: ["name"] } }` narrows the loaded
+* `author` to the selected columns + system fields.
+*/
 type LoadRelation<DM, REL extends Record<keyof DM, object>, R, WK> = R extends {
   __relationKind: "one";
   __target: infer Target extends keyof DM;
-} ? LoadWith<DM, REL, Target, NestedWithArgument<WK>> | null : R extends {
+} ? LoadWith<DM, REL, Target, NestedWithArgument<WK>, NestedSelectArgument<WK>> | null : R extends {
   __relationKind: "many";
   __target: infer Target extends keyof DM;
-} ? LoadWith<DM, REL, Target, NestedWithArgument<WK>>[] : never;
+} ? LoadWith<DM, REL, Target, NestedWithArgument<WK>, NestedSelectArgument<WK>>[] : never;
 /** The relation keys of `W` that were actually requested (not `false`/`undefined`). */
 type LoadedRelations<DM, REL extends Record<keyof DM, object>, T extends keyof DM, W> = { [K in keyof W as K extends keyof REL[T] ? (W[K] extends false | undefined ? never : K) : never]: K extends keyof REL[T] ? LoadRelation<DM, REL, REL[T][K], W[K]> : never };
 /** The `_count` projection of `W`, if any. */
@@ -145,8 +168,20 @@ type LoadedCount<W> = W extends {
 } ? {
   _count: { [K in keyof C]: number };
 } : {};
-/** `Doc&lt;T>` narrowed to exactly the relations requested in the with-arg `W`. */
-type LoadWith<DM, REL extends Record<keyof DM, object>, T extends keyof DM, W> = DM[T] & LoadedCount<W> & LoadedRelations<DM, REL, T, W>;
+/** System columns a `select` projection always retains, so cursors and by-id reuse keep working. */
+type SelectAlwaysKeep<DM, T extends keyof DM> = ("_creationTime" | "_id") & keyof DM[T];
+/**
+* `DM[T]` narrowed to the columns named by a `select` tuple `S` (plus the system
+* fields). `undefined` (the default — no `select`) keeps the full document.
+*/
+type ProjectDoc<DM, T extends keyof DM, S> = S extends ReadonlyArray<infer K> ? (K extends keyof DM[T] ? Pick<DM[T], (K & keyof DM[T]) | SelectAlwaysKeep<DM, T>> : DM[T]) : DM[T];
+/**
+* `Doc&lt;T>` narrowed to exactly the relations requested in the with-arg `W` and,
+* when a `select` tuple `S` is supplied, to its projected columns. `S` defaults
+* to `undefined` so the 4-argument form (the codegen-emitted callers) keeps the
+* full document.
+*/
+type LoadWith<DM, REL extends Record<keyof DM, object>, T extends keyof DM, W, S = undefined> = LoadedCount<W> & LoadedRelations<DM, REL, T, W> & ProjectDoc<DM, T, S>;
 /** Reducer applied by an aggregate (`avg`/`count`/`max`/`min`/`sum`). */
 type AggregateOp = "avg" | "count" | "max" | "min" | "sum";
 /**
@@ -260,15 +295,20 @@ interface TableReaderFacade<DM, REL extends Record<keyof DM, object>, RANK exten
   * uses to inject `baseWhere` and `restrictsCounts`.
   */
   count: (where?: RestrictableQueryOptionsOf<DM, REL, T> | WhereOf<DM, REL, T>) => Promise<number>;
-  findFirst: <W extends WithArg<DM, REL, T> = {}>(args?: QueryArgsOf<DM, REL, T> & {
+  /** `true` when at least one row matches `where` (any row when omitted). RLS-filtered exactly like `findFirst`. */
+  exists: (where?: WhereOf<DM, REL, T>) => Promise<boolean>;
+  findFirst: <W extends WithArg<DM, REL, T> = {}, S extends ReadonlyArray<keyof DM[T] & string> | undefined = undefined>(args?: QueryArgsOf<DM, REL, T> & {
+    select?: S;
     with?: W;
-  }) => Promise<LoadWith<DM, REL, T, W> | null>;
-  findFirstOrThrow: <W extends WithArg<DM, REL, T> = {}>(args?: QueryArgsOf<DM, REL, T> & {
+  }) => Promise<LoadWith<DM, REL, T, W, S> | null>;
+  findFirstOrThrow: <W extends WithArg<DM, REL, T> = {}, S extends ReadonlyArray<keyof DM[T] & string> | undefined = undefined>(args?: QueryArgsOf<DM, REL, T> & {
+    select?: S;
     with?: W;
-  }) => Promise<LoadWith<DM, REL, T, W>>;
-  findMany: <W extends WithArg<DM, REL, T> = {}>(args?: QueryArgsOf<DM, REL, T> & {
+  }) => Promise<LoadWith<DM, REL, T, W, S>>;
+  findMany: <W extends WithArg<DM, REL, T> = {}, S extends ReadonlyArray<keyof DM[T] & string> | undefined = undefined>(args?: QueryArgsOf<DM, REL, T> & {
+    select?: S;
     with?: W;
-  }) => Promise<QueryPage<LoadWith<DM, REL, T, W>>>;
+  }) => Promise<QueryPage<LoadWith<DM, REL, T, W, S>>>;
   get: (id: Id<string & T>) => Promise<DM[T] | null>;
   /**
   * Group rows by the named keys and apply `agg` per group (defaults to
@@ -299,6 +339,11 @@ interface TableReaderFacade<DM, REL extends Record<keyof DM, object>, RANK exten
 }
 /** Read-write typed table accessor exposed on `MutationCtx.db.&lt;table>` / `ActionCtx.db.&lt;table>`. */
 interface TableWriterFacade<DM, IM extends Record<keyof DM, object>, REL extends Record<keyof DM, object>, RANK extends Record<keyof DM, string>, SEARCH extends Record<keyof DM, string>, T extends keyof DM> extends TableReaderFacade<DM, REL, RANK, SEARCH, T> {
+  /**
+  * Delete a row by id. On a `.softDelete()` table this flips the marker column
+  * (and cascades as a soft delete) instead of removing the row; use
+  * {@link TableWriterFacade.hardDelete} to force physical removal.
+  */
   delete: (id: Id<string & T>) => Promise<void>;
   /** Delete many rows in this table by id in one call; returns the *requested* id count (unknown ids are no-ops). Atomic within a mutation (a throw rolls the mutation back); an action has no transaction span. */
   deleteMany: (ids: ReadonlyArray<Id<string & T>>, options?: {
@@ -306,7 +351,21 @@ interface TableWriterFacade<DM, IM extends Record<keyof DM, object>, REL extends
   }) => Promise<{
     deleted: number;
   }>;
-  insert: (values: IM[T]) => Promise<Id<string & T>>;
+  /** Physically remove a row (and physically cascade `onDelete`), bypassing `.softDelete()`. Same as `delete()` on a non-soft table. */
+  hardDelete: (id: Id<string & T>) => Promise<void>;
+  /**
+  * Insert a document, returning its minted id. With `{ skipDuplicates: true }`
+  * a UNIQUE-constraint breach resolves to `null` (the row already exists)
+  * instead of throwing — the return type widens to `Id | null` on that overload.
+  */
+  insert: {
+    (values: IM[T], options: {
+      skipDuplicates: true;
+    }): Promise<Id<string & T> | null>;
+    (values: IM[T], options?: {
+      skipDuplicates?: boolean;
+    }): Promise<Id<string & T>>;
+  };
   /** Insert many documents into this table in one call, returning the minted ids in input order. Atomic within a mutation (a throw rolls the mutation back); an action has no transaction span. */
   insertMany: (values: ReadonlyArray<IM[T]>, options?: {
     limit?: number;
@@ -320,9 +379,38 @@ interface TableWriterFacade<DM, IM extends Record<keyof DM, object>, REL extends
     limit?: number;
   }) => Promise<void>;
   replace: (id: Id<string & T>, values: IM[T]) => Promise<void>;
+  /** Un-soft-delete a row by id: clears the `.softDelete()` marker so list reads see it again. Throws on a non-soft table. */
+  restore: (id: Id<string & T>) => Promise<void>;
+  /**
+  * Insert when no existing row matches `target`, otherwise patch the match with
+  * `update` (defaulting to `create`). `target` names a `.unique()` column (or a
+  * tuple) used to look it up. Returns the row id and whether it was `created`.
+  * Composes `findFirst` + `insert`/`patch`, so RLS gates each step.
+  */
+  upsert: (args: {
+    create: IM[T];
+    target: UpsertTargetOf<DM, T>;
+    update?: Partial<IM[T]>;
+  }) => Promise<{
+    created: boolean;
+    id: Id<string & T>;
+  }>;
+  /** Sequential {@link TableWriterFacade.upsert} over many rows sharing one `target`; one result per input row, in order. */
+  upsertMany: (args: {
+    rows: ReadonlyArray<{
+      create: IM[T];
+      update?: Partial<IM[T]>;
+    }>;
+    target: UpsertTargetOf<DM, T>;
+  }) => Promise<{
+    created: boolean;
+    id: Id<string & T>;
+  }[]>;
 }
+/** Conflict target for `upsert`/`upsertMany`: one column of table `T`, or a tuple of them. */
+type UpsertTargetOf<DM, T extends keyof DM> = ReadonlyArray<keyof DM[T] & string> | (keyof DM[T] & string);
 /** Per-table read facade — `ctx.db.&lt;table>` on a `QueryCtx`. */
 type DatabaseReaderFacade<DM, REL extends Record<keyof DM, object>, RANK extends Record<keyof DM, string>, SEARCH extends Record<keyof DM, string>> = { readonly [T in keyof DM]: TableReaderFacade<DM, REL, RANK, SEARCH, T> };
 /** Per-table read-write facade — `ctx.db.&lt;table>` on a `MutationCtx` / `ActionCtx`. */
 type DatabaseWriterFacade<DM, IM extends Record<keyof DM, object>, REL extends Record<keyof DM, object>, RANK extends Record<keyof DM, string>, SEARCH extends Record<keyof DM, string>> = { readonly [T in keyof DM]: TableWriterFacade<DM, IM, REL, RANK, SEARCH, T> };
-export { AggregateOp, DatabaseReaderFacade, DatabaseWriterFacade, GroupByEntry, Id, LoadWith, ManyRelationWhere, OneRelationWhere, OrderBy, QueryArgs, QueryArgsOf, QueryPage, RankPage, RankResult, RestrictableQueryOptions, RestrictableQueryOptionsOf, SearchFilterBuilder, SearchReader, TableAggregateOptions, TableAggregateOptionsOf, TableGroupByOptions, TableGroupByOptionsOf, TableRankOptions, TableRankPageOptions, TableReaderFacade, TableWriterFacade, Where, WhereOf, WhereOperators, WithArg };
+export { AggregateOp, DatabaseReaderFacade, DatabaseWriterFacade, GroupByEntry, Id, LoadWith, ManyRelationWhere, OneRelationWhere, OrderBy, QueryArgs, QueryArgsOf, QueryPage, RankPage, RankResult, RestrictableQueryOptions, RestrictableQueryOptionsOf, SearchFilterBuilder, SearchReader, TableAggregateOptions, TableAggregateOptionsOf, TableGroupByOptions, TableGroupByOptionsOf, TableRankOptions, TableRankPageOptions, TableReaderFacade, TableWriterFacade, UpsertTargetOf, Where, WhereOf, WhereOperators, WithArg };

package/dist/data-model.d.ts

@@ -49,6 +49,13 @@ interface QueryArgs<TDocument> {
   cursor?: null | string;
   limit?: number;
   orderBy?: OrderBy<TDocument>[];
+  /**
+  * Project each returned row down to these columns (plus the system fields
+  * `_id`/`_creationTime`, always retained). Trims wire payload for wide rows;
+  * relations requested via `with` are still attached. Reactivity is unaffected —
+  * the engine still reads the whole row to track dependencies.
+  */
+  select?: ReadonlyArray<keyof TDocument & string>;
   where?: Where<TDocument>;
 }
 /**
@@ -97,6 +104,12 @@ type WhereOf<DM, REL extends Record<keyof DM, object>, T extends keyof DM> = Rel
 /** {@link QueryArgs} with the relation-aware {@link WhereOf} `where` typing. */
 interface QueryArgsOf<DM, REL extends Record<keyof DM, object>, T extends keyof DM> {
   cursor?: null | string;
+  /**
+  * Include soft-deleted rows (`.softDelete()` tables only). Default hides them;
+  * `true` returns deleted rows alongside live ones. No effect on a table
+  * without `.softDelete()`.
+  */
+  includeDeleted?: boolean;
   limit?: number;
   orderBy?: OrderBy<DM[T]>[];
   where?: WhereOf<DM, REL, T>;
@@ -110,11 +123,15 @@ interface QueryPage<TDocument> {
 type NestedWithArgument<WK> = WK extends {
   with: infer NW;
 } ? NW : {};
+/** The nested `select` tuple inside a relation's with-value, or `undefined` (no projection). */
+type NestedSelectArgument<WK> = WK extends {
+  select: infer S;
+} ? S : undefined;
 /**
 * The `with` argument for table `T`: each relation can be `true` (load with no
-* refinements) or an object. `many` relations accept `where`/`orderBy`/`limit`
-* plus a nested `with`; `one` relations accept only a nested `with`. The
-* reserved `_count` key requests per-relation aggregate counts.
+* refinements) or an object. `many` relations accept `where`/`orderBy`/`limit`/
+* `select` plus a nested `with`; `one` relations accept `select` + a nested
+* `with`. The reserved `_count` key requests per-relation aggregate counts.
 */
 type WithArg<DM, REL extends Record<keyof DM, object>, T extends keyof DM> = { [K in keyof REL[T]]?: REL[T][K] extends {
   __relationKind: "many";
@@ -125,18 +142,24 @@ type WithArg<DM, REL extends Record<keyof DM, object>, T extends keyof DM> = { [
   __relationKind: "one";
   __target: infer Target extends keyof DM;
 } ? boolean | {
+  select?: ReadonlyArray<keyof DM[Target] & string>;
   with?: WithArg<DM, REL, Target>;
 } : never } & {
   _count?: { [K in keyof REL[T]]?: true };
 };
-/** Resolve a single relation descriptor + its with-value to the loaded type. */
+/**
+* Resolve a single relation descriptor + its with-value to the loaded type,
+* threading the nested `select` tuple into the projected child shape (the 5th
+* `LoadWith` arg) so `with: { author: { select: ["name"] } }` narrows the loaded
+* `author` to the selected columns + system fields.
+*/
 type LoadRelation<DM, REL extends Record<keyof DM, object>, R, WK> = R extends {
   __relationKind: "one";
   __target: infer Target extends keyof DM;
-} ? LoadWith<DM, REL, Target, NestedWithArgument<WK>> | null : R extends {
+} ? LoadWith<DM, REL, Target, NestedWithArgument<WK>, NestedSelectArgument<WK>> | null : R extends {
   __relationKind: "many";
   __target: infer Target extends keyof DM;
-} ? LoadWith<DM, REL, Target, NestedWithArgument<WK>>[] : never;
+} ? LoadWith<DM, REL, Target, NestedWithArgument<WK>, NestedSelectArgument<WK>>[] : never;
 /** The relation keys of `W` that were actually requested (not `false`/`undefined`). */
 type LoadedRelations<DM, REL extends Record<keyof DM, object>, T extends keyof DM, W> = { [K in keyof W as K extends keyof REL[T] ? (W[K] extends false | undefined ? never : K) : never]: K extends keyof REL[T] ? LoadRelation<DM, REL, REL[T][K], W[K]> : never };
 /** The `_count` projection of `W`, if any. */
@@ -145,8 +168,20 @@ type LoadedCount<W> = W extends {
 } ? {
   _count: { [K in keyof C]: number };
 } : {};
-/** `Doc&lt;T>` narrowed to exactly the relations requested in the with-arg `W`. */
-type LoadWith<DM, REL extends Record<keyof DM, object>, T extends keyof DM, W> = DM[T] & LoadedCount<W> & LoadedRelations<DM, REL, T, W>;
+/** System columns a `select` projection always retains, so cursors and by-id reuse keep working. */
+type SelectAlwaysKeep<DM, T extends keyof DM> = ("_creationTime" | "_id") & keyof DM[T];
+/**
+* `DM[T]` narrowed to the columns named by a `select` tuple `S` (plus the system
+* fields). `undefined` (the default — no `select`) keeps the full document.
+*/
+type ProjectDoc<DM, T extends keyof DM, S> = S extends ReadonlyArray<infer K> ? (K extends keyof DM[T] ? Pick<DM[T], (K & keyof DM[T]) | SelectAlwaysKeep<DM, T>> : DM[T]) : DM[T];
+/**
+* `Doc&lt;T>` narrowed to exactly the relations requested in the with-arg `W` and,
+* when a `select` tuple `S` is supplied, to its projected columns. `S` defaults
+* to `undefined` so the 4-argument form (the codegen-emitted callers) keeps the
+* full document.
+*/
+type LoadWith<DM, REL extends Record<keyof DM, object>, T extends keyof DM, W, S = undefined> = LoadedCount<W> & LoadedRelations<DM, REL, T, W> & ProjectDoc<DM, T, S>;
 /** Reducer applied by an aggregate (`avg`/`count`/`max`/`min`/`sum`). */
 type AggregateOp = "avg" | "count" | "max" | "min" | "sum";
 /**
@@ -260,15 +295,20 @@ interface TableReaderFacade<DM, REL extends Record<keyof DM, object>, RANK exten
   * uses to inject `baseWhere` and `restrictsCounts`.
   */
   count: (where?: RestrictableQueryOptionsOf<DM, REL, T> | WhereOf<DM, REL, T>) => Promise<number>;
-  findFirst: <W extends WithArg<DM, REL, T> = {}>(args?: QueryArgsOf<DM, REL, T> & {
+  /** `true` when at least one row matches `where` (any row when omitted). RLS-filtered exactly like `findFirst`. */
+  exists: (where?: WhereOf<DM, REL, T>) => Promise<boolean>;
+  findFirst: <W extends WithArg<DM, REL, T> = {}, S extends ReadonlyArray<keyof DM[T] & string> | undefined = undefined>(args?: QueryArgsOf<DM, REL, T> & {
+    select?: S;
     with?: W;
-  }) => Promise<LoadWith<DM, REL, T, W> | null>;
-  findFirstOrThrow: <W extends WithArg<DM, REL, T> = {}>(args?: QueryArgsOf<DM, REL, T> & {
+  }) => Promise<LoadWith<DM, REL, T, W, S> | null>;
+  findFirstOrThrow: <W extends WithArg<DM, REL, T> = {}, S extends ReadonlyArray<keyof DM[T] & string> | undefined = undefined>(args?: QueryArgsOf<DM, REL, T> & {
+    select?: S;
     with?: W;
-  }) => Promise<LoadWith<DM, REL, T, W>>;
-  findMany: <W extends WithArg<DM, REL, T> = {}>(args?: QueryArgsOf<DM, REL, T> & {
+  }) => Promise<LoadWith<DM, REL, T, W, S>>;
+  findMany: <W extends WithArg<DM, REL, T> = {}, S extends ReadonlyArray<keyof DM[T] & string> | undefined = undefined>(args?: QueryArgsOf<DM, REL, T> & {
+    select?: S;
     with?: W;
-  }) => Promise<QueryPage<LoadWith<DM, REL, T, W>>>;
+  }) => Promise<QueryPage<LoadWith<DM, REL, T, W, S>>>;
   get: (id: Id<string & T>) => Promise<DM[T] | null>;
   /**
   * Group rows by the named keys and apply `agg` per group (defaults to
@@ -299,6 +339,11 @@ interface TableReaderFacade<DM, REL extends Record<keyof DM, object>, RANK exten
 }
 /** Read-write typed table accessor exposed on `MutationCtx.db.&lt;table>` / `ActionCtx.db.&lt;table>`. */
 interface TableWriterFacade<DM, IM extends Record<keyof DM, object>, REL extends Record<keyof DM, object>, RANK extends Record<keyof DM, string>, SEARCH extends Record<keyof DM, string>, T extends keyof DM> extends TableReaderFacade<DM, REL, RANK, SEARCH, T> {
+  /**
+  * Delete a row by id. On a `.softDelete()` table this flips the marker column
+  * (and cascades as a soft delete) instead of removing the row; use
+  * {@link TableWriterFacade.hardDelete} to force physical removal.
+  */
   delete: (id: Id<string & T>) => Promise<void>;
   /** Delete many rows in this table by id in one call; returns the *requested* id count (unknown ids are no-ops). Atomic within a mutation (a throw rolls the mutation back); an action has no transaction span. */
   deleteMany: (ids: ReadonlyArray<Id<string & T>>, options?: {
@@ -306,7 +351,21 @@ interface TableWriterFacade<DM, IM extends Record<keyof DM, object>, REL extends
   }) => Promise<{
     deleted: number;
   }>;
-  insert: (values: IM[T]) => Promise<Id<string & T>>;
+  /** Physically remove a row (and physically cascade `onDelete`), bypassing `.softDelete()`. Same as `delete()` on a non-soft table. */
+  hardDelete: (id: Id<string & T>) => Promise<void>;
+  /**
+  * Insert a document, returning its minted id. With `{ skipDuplicates: true }`
+  * a UNIQUE-constraint breach resolves to `null` (the row already exists)
+  * instead of throwing — the return type widens to `Id | null` on that overload.
+  */
+  insert: {
+    (values: IM[T], options: {
+      skipDuplicates: true;
+    }): Promise<Id<string & T> | null>;
+    (values: IM[T], options?: {
+      skipDuplicates?: boolean;
+    }): Promise<Id<string & T>>;
+  };
   /** Insert many documents into this table in one call, returning the minted ids in input order. Atomic within a mutation (a throw rolls the mutation back); an action has no transaction span. */
   insertMany: (values: ReadonlyArray<IM[T]>, options?: {
     limit?: number;
@@ -320,9 +379,38 @@ interface TableWriterFacade<DM, IM extends Record<keyof DM, object>, REL extends
     limit?: number;
   }) => Promise<void>;
   replace: (id: Id<string & T>, values: IM[T]) => Promise<void>;
+  /** Un-soft-delete a row by id: clears the `.softDelete()` marker so list reads see it again. Throws on a non-soft table. */
+  restore: (id: Id<string & T>) => Promise<void>;
+  /**
+  * Insert when no existing row matches `target`, otherwise patch the match with
+  * `update` (defaulting to `create`). `target` names a `.unique()` column (or a
+  * tuple) used to look it up. Returns the row id and whether it was `created`.
+  * Composes `findFirst` + `insert`/`patch`, so RLS gates each step.
+  */
+  upsert: (args: {
+    create: IM[T];
+    target: UpsertTargetOf<DM, T>;
+    update?: Partial<IM[T]>;
+  }) => Promise<{
+    created: boolean;
+    id: Id<string & T>;
+  }>;
+  /** Sequential {@link TableWriterFacade.upsert} over many rows sharing one `target`; one result per input row, in order. */
+  upsertMany: (args: {
+    rows: ReadonlyArray<{
+      create: IM[T];
+      update?: Partial<IM[T]>;
+    }>;
+    target: UpsertTargetOf<DM, T>;
+  }) => Promise<{
+    created: boolean;
+    id: Id<string & T>;
+  }[]>;
 }
+/** Conflict target for `upsert`/`upsertMany`: one column of table `T`, or a tuple of them. */
+type UpsertTargetOf<DM, T extends keyof DM> = ReadonlyArray<keyof DM[T] & string> | (keyof DM[T] & string);
 /** Per-table read facade — `ctx.db.&lt;table>` on a `QueryCtx`. */
 type DatabaseReaderFacade<DM, REL extends Record<keyof DM, object>, RANK extends Record<keyof DM, string>, SEARCH extends Record<keyof DM, string>> = { readonly [T in keyof DM]: TableReaderFacade<DM, REL, RANK, SEARCH, T> };
 /** Per-table read-write facade — `ctx.db.&lt;table>` on a `MutationCtx` / `ActionCtx`. */
 type DatabaseWriterFacade<DM, IM extends Record<keyof DM, object>, REL extends Record<keyof DM, object>, RANK extends Record<keyof DM, string>, SEARCH extends Record<keyof DM, string>> = { readonly [T in keyof DM]: TableWriterFacade<DM, IM, REL, RANK, SEARCH, T> };
-export { AggregateOp, DatabaseReaderFacade, DatabaseWriterFacade, GroupByEntry, Id, LoadWith, ManyRelationWhere, OneRelationWhere, OrderBy, QueryArgs, QueryArgsOf, QueryPage, RankPage, RankResult, RestrictableQueryOptions, RestrictableQueryOptionsOf, SearchFilterBuilder, SearchReader, TableAggregateOptions, TableAggregateOptionsOf, TableGroupByOptions, TableGroupByOptionsOf, TableRankOptions, TableRankPageOptions, TableReaderFacade, TableWriterFacade, Where, WhereOf, WhereOperators, WithArg };
+export { AggregateOp, DatabaseReaderFacade, DatabaseWriterFacade, GroupByEntry, Id, LoadWith, ManyRelationWhere, OneRelationWhere, OrderBy, QueryArgs, QueryArgsOf, QueryPage, RankPage, RankResult, RestrictableQueryOptions, RestrictableQueryOptionsOf, SearchFilterBuilder, SearchReader, TableAggregateOptions, TableAggregateOptionsOf, TableGroupByOptions, TableGroupByOptionsOf, TableRankOptions, TableRankPageOptions, TableReaderFacade, TableWriterFacade, UpsertTargetOf, Where, WhereOf, WhereOperators, WithArg };

package/dist/index.d.mts

@@ -1,6 +1,6 @@
 import { Validator, Infer, v } from '@lunora/values';
 export { type ColumnValidator, type Id, type Infer, ValidationError, type Validator, type ValidatorKind, v } from '@lunora/values';
-import { ArgsValidator, InferArgs, RegisteredAction, ActionCtx, MutationCtx, RegisteredMutation, QueryCtx, RegisteredQuery, RegisteredStream, FunctionKind, LifecycleEvent, RegisteredLifecycleHook, TableDefinition, RegisteredFunction, VectorIndexDefinition, Schema, AggregateOp, RelationDefinition, GlobalBackend, OnDeleteAction, TriggerBuilder, TriggerDefinition, VectorEmbedder, VectorMetric, AggregateIndexDefinition, RankIndexDefinition } from "./types.mjs";
+import { ArgsValidator, InferArgs, RegisteredAction, ActionCtx, MutationCtx, RegisteredMutation, QueryCtx, RegisteredQuery, RegisteredStream, FunctionKind, LifecycleEvent, RegisteredLifecycleHook, TableDefinition, RegisteredFunction, VectorIndexDefinition, Schema, AggregateOp, DurableObjectJurisdiction, RelationDefinition, GlobalBackend, OnDeleteAction, TriggerBuilder, TriggerDefinition, VectorEmbedder, VectorMetric, AggregateIndexDefinition, RankIndexDefinition } from "./types.mjs";
 export { type AnyApi, type AuthState, type DatabaseReader, type DatabaseWriter, type FunctionVisibility, type IndexDefinition, type IndexRangeBuilder, type LifecycleEventKind, type LunoraLogger, type PaginationOptions, type PaginationResult, type RankSortKey, type ReadOnlyStorage, type ScheduledFunctionDoc, type ScheduledJob, type Scheduler, type SearchFilterBuilder, type SearchIndexDefinition, type ShardMode, type Storage, type StorageMetadata, type SystemDatabaseReader, type SystemDoc, type SystemQuery, type SystemTableName, type TableReader, type TableVectorIndex, type TriggerAggregateOptions, type TriggerCtx, type TriggerDatabase, type TriggerDeleteEvent, type TriggerEvent, type TriggerGroupByEntry, type TriggerGroupByOptions, type TriggerHandler, type TriggerInsertEvent, type TriggerOp, type TriggerQueryArgs, type TriggerQueryPage, type TriggerRankOptions, type TriggerRankPageOptions, type TriggerRankResult, type TriggerRow, type TriggerTiming, type TriggerUpdateEvent, type VectorMatch, type VectorMatches, type VectorQueryInput, type VectorRecord, type VectorSearch, type VectorSearchReader, type VectorUpsertInput, type WorkflowCreateOptions, type WorkflowHandle, type WorkflowInstance, type WorkflowInstanceStatus, type WorkflowStatusResult, type Workflows, anyApi } from "./types.mjs";
 import { Context, Hono } from 'hono';
 import { b as Permission, R as Role, T as TypedDefinePolicyInput, a as Policy, D as DefinePolicyInput, W as WhereInput, c as RlsOptions } from "./packem_shared/types.d-DmvyEMD6.mjs";
@@ -325,21 +325,6 @@ declare class LunoraError extends Error {
   constructor(code: LunoraErrorCode, message?: string);
 }
 /**
-* The per-table `ctx.db` accessor (the `ctx.db.messages.findMany(...)` form) and
-* the kitcn-style `ctx.orm` namespace, as plain runtime helpers. This is the ONE
-* source of truth for the facade shape, shared by two callers so they can never
-* drift (a drift here is security-relevant — a facade accessor the RLS
-* middleware forgot to re-bind would read around policy). `@lunora/codegen`
-* emits `ctx.db`/`ctx.orm` by calling these over the raw shard writer (and the
-* D1 `globalDb` writer for `.global()` tables); the RLS middleware re-binds the
-* policy tables by calling them over the policy-enforcing wrapped writer.
-*
-* `bindTableFacade(writer, table)` pins `tableName` on the structural writer so
-* callers address rows by id (`get`/`delete`/`patch`/`replace`) or by the bound
-* table (everything else). The binding is identical regardless of which writer
-* is passed — that's the whole point.
-*/
-/**
 * Minimal structural writer the facade binds over. Declared with **method**
 * syntax (not arrow properties) so a more-specifically-typed writer — both
 * `@lunora/do`'s `DatabaseWriterLike` and the RLS middleware's wrapped writer —
@@ -349,7 +334,9 @@ declare class LunoraError extends Error {
 interface FacadeWriterLike {
   aggregate(tableName: string, options: unknown): Promise<unknown>;
   count(tableName: string, where?: unknown): Promise<number>;
-  delete(id: string, expectedTable?: string): Promise<void>;
+  delete(id: string, expectedTable?: string, options?: {
+    hard?: boolean;
+  }): Promise<void>;
   deleteMany?(ids: ReadonlyArray<string>, options?: {
     limit?: number;
   }, expectedTable?: string): Promise<{
@@ -377,6 +364,7 @@ interface FacadeWriterLike {
   rank(tableName: string, indexName: string, options: unknown): Promise<unknown>;
   rankPage(tableName: string, indexName: string, options?: unknown): Promise<unknown>;
   replace(id: string, document: Record<string, unknown>, expectedTable?: string): Promise<void>;
+  restore?(id: string, expectedTable?: string): Promise<void>;
 }
 /** The per-table accessor object returned for the `ctx.db` table form. */
 interface FacadeEntry {
@@ -388,12 +376,16 @@ interface FacadeEntry {
   }) => Promise<{
     deleted: number;
   }>;
+  /** `true` when at least one row matches `where` (or any row exists when omitted). Honors RLS like `findFirst`. */
+  exists: (where?: unknown) => Promise<boolean>;
   findFirst: (args?: unknown) => Promise<unknown>;
   findFirstOrThrow: (args?: unknown) => Promise<unknown>;
   findMany: (args?: unknown) => Promise<unknown>;
   get: (id: string) => Promise<unknown>;
   groupBy: (options: unknown) => Promise<unknown>;
-  insert: (document: Record<string, unknown>) => Promise<string>;
+  /** Physically remove a row (and physically cascade), bypassing `.softDelete()`. */
+  hardDelete: (id: string) => Promise<void>;
+  insert: (document: Record<string, unknown>, options?: FacadeInsertOptions) => Promise<null | string>;
   insertMany: (documents: ReadonlyArray<Record<string, unknown>>, options?: {
     limit?: number;
   }) => Promise<string[]>;
@@ -407,8 +399,47 @@ interface FacadeEntry {
   rank: (indexName: string, options: unknown) => Promise<unknown>;
   rankPage: (indexName: string, options?: unknown) => Promise<unknown>;
   replace: (id: string, document: Record<string, unknown>) => Promise<void>;
+  /** Un-soft-delete a row: clears the `.softDelete()` marker (by-id, so it reaches a row list reads hide). */
+  restore: (id: string) => Promise<void>;
+  /** Insert when no row matches `target`, else patch the match. Composes `findFirst` + `insert`/`patch`, so RLS applies to each step. */
+  upsert: (args: UpsertArgs) => Promise<UpsertResult>;
+  /** Sequential `upsert` over many rows sharing one `target`; returns one result per input row in order. */
+  upsertMany: (args: UpsertManyArgs) => Promise<UpsertResult[]>;
   withSearchIndex: (indexName: string, search: (q: unknown) => unknown) => unknown;
 }
+/** Options accepted by the per-table `insert` accessor. */
+interface FacadeInsertOptions {
+  /**
+  * When `true`, a UNIQUE-constraint breach is swallowed: the insert becomes a
+  * silent no-op and resolves to `null` instead of throwing a `CONFLICT`. Any
+  * other error still propagates. Mirrors better-drizzle's `create({ skipDuplicates })`.
+  */
+  skipDuplicates?: boolean;
+}
+/** The conflict target for `upsert`/`upsertMany`: one field name or a tuple of them. */
+type UpsertTarget = ReadonlyArray<string> | string;
+/** Argument to the per-table `upsert` accessor. */
+interface UpsertArgs {
+  /** Document inserted when no existing row matches the `target`. */
+  create: Record<string, unknown>;
+  /** Field(s) — typically a `.unique()` column or unique index — used to look up an existing row. */
+  target: UpsertTarget;
+  /** Patch applied when an existing row matches the `target`. Defaults to `create`. */
+  update?: Record<string, unknown>;
+}
+/** Result of an `upsert`: the row's id and whether it was freshly inserted (`true`) or updated (`false`). */
+interface UpsertResult {
+  created: boolean;
+  id: string;
+}
+/** Argument to the per-table `upsertMany` accessor — a shared `target` plus per-row create/update payloads. */
+interface UpsertManyArgs {
+  rows: ReadonlyArray<{
+    create: Record<string, unknown>;
+    update?: Record<string, unknown>;
+  }>;
+  target: UpsertTarget;
+}
 /**
 * Bind a structural writer to one table, producing its `ctx.db` table accessor.
 *
@@ -426,7 +457,7 @@ declare const bindTableFacade: (writer: FacadeWriterLike, tableName: string) =>
 interface OrmLike {
   delete: (table: string, id: string) => Promise<void>;
   insert: (table: string) => {
-    values: (document: Record<string, unknown>) => Promise<string>;
+    values: (document: Record<string, unknown>) => Promise<null | string>;
   };
   query: Record<string, FacadeEntry>;
   replace: (table: string, id: string) => {
@@ -1168,6 +1199,22 @@ interface TableBuilder<Shape extends Record<string, Validator> = Record<string,
   }) => TableBuilder<Shape>;
   /** Route storage by the named field — one DO per distinct value. */
   shardBy: (field: keyof Shape & string) => TableBuilder<Shape>;
+  /**
+  * Turn on soft delete. Adds a nullable timestamp column (`options.field`,
+  * default `deletedAt`) and changes `ctx.db.&lt;table>.delete()` to **set** it
+  * instead of removing the row; `onDelete: "cascade"` children are recursively
+  * soft-deleted too. **List reads** (`findMany`/`findFirst`/`query()`/`count`/
+  * `aggregate`/relation loads) then hide soft-deleted rows unless they pass
+  * `includeDeleted: true`; by-id `get`/`patch`/`replace` and the new
+  * `restore()` still address the row directly. `hardDelete()` physically
+  * removes it (cascading as a real delete). Note: `includeDeleted` is a read
+  * scope, not access control — anyone who can run the read can set it; a unique
+  * index still rejects a new row that collides with a soft-deleted one (the row
+  * physically persists).
+  */
+  softDelete: (options?: {
+    field?: string;
+  }) => TableBuilder<Shape>;
   /** Declare named lifecycle triggers fired inline within the write path. */
   triggers: (build: (t: TriggerBuilder<Shape>) => Record<string, TriggerDefinition>) => TableBuilder<Shape>;
   /** Declare a vector index over a single text field on this table. */
@@ -1190,7 +1237,7 @@ interface VectorIndexOptions {
 * Build a table definition. Returned object is both the table definition (for
 * `defineSchema`) and a fluent builder for indexes + sharding metadata.
 */
-declare const defineTable: <Shape extends Record<string, Validator>>(shape: Shape) => TableBuilder<Shape>;
+declare const defineTable: <Shape extends Record<string, Validator>>(inputShape: Shape) => TableBuilder<Shape>;
 /**
 * Declare a standalone vector index (DSL Shape B). Pass the returned value in
 * the `vectorIndexes` map of {@link defineSchema} when the source is derived
@@ -1262,6 +1309,28 @@ type ExtendableSchema<T extends Record<string, TableDefinition>> = {
     readonly key: Key;
   }) => ExtendableSchema<PrefixedTables<X, Key> & T>;
   /**
+  * Pin every Durable Object the app reaches — shards, fan-out, subscriptions,
+  * the scheduler, and `ctx.containers` — to a Cloudflare data-residency
+  * jurisdiction (`"eu"`, `"us"`, `"fedramp"`). Codegen reads this off the
+  * schema and emits it into the generated worker's `createWorker({ jurisdiction })`
+  * (and `ctx.scheduler` / `ctx.containers`). Non-mutating: returns a fresh
+  * `ExtendableSchema`, so it composes with `.rls(...)` / `.extend(...)` in any order.
+  *
+  * ⚠️ **Set this once, before your first deploy — changing or removing it
+  * strands data.** A Durable Object name maps to a *different* ID in each
+  * jurisdiction, so toggling this on an existing app makes every shard, scheduler
+  * job, and session DO resolve to a NEW, empty DO; the previous data stays in the
+  * old jurisdiction's DOs and is no longer reachable. There is no in-place
+  * migration — you would have to export from the old jurisdiction and import
+  * into the new one.
+  *
+  * Note: this pins **DO-backed** state only. D1-backed state — `.global()`
+  * tables and `@lunora/auth` sessions alike — is governed by D1's own location
+  * settings, not this option.
+  * @see https://developers.cloudflare.com/durable-objects/reference/data-location/
+  */
+  jurisdiction: (jurisdiction: DurableObjectJurisdiction) => ExtendableSchema<T>;
+  /**
   * Turn on secure-by-default RLS for the whole schema. Every table is then
   * protected — the DO/D1 write path denies raw, non-RLS `ctx.db` access, so a
   * procedure that forgets `.use(rls(...))` fails closed. Opt a table out with
@@ -1562,7 +1631,9 @@ interface DatabaseWriterLike {
   */
   aggregate: (tableName: string, options: AggregateArgs) => Promise<null | number>;
   count: (tableName: string, whereOrArgs?: CountArgs | WhereInput) => Promise<number>;
-  delete: (id: string, expectedTable?: string) => Promise<void>;
+  delete: (id: string, expectedTable?: string, options?: {
+    hard?: boolean;
+  }) => Promise<void>;
   deleteMany: (ids: ReadonlyArray<string>, options?: {
     limit?: number;
   }, expectedTable?: string) => Promise<{
@@ -1633,6 +1704,7 @@ interface DatabaseWriterLike {
   */
   rankPage: (tableName: string, indexName: string, options?: RankPageArgs) => Promise<QueryPage>;
   replace: (id: string, document: Record<string, unknown>, expectedTable?: string) => Promise<void>;
+  restore?: (id: string, expectedTable?: string) => Promise<void>;
 }
 /**
 * What a procedure's `ctx.db` must structurally satisfy for the middleware
@@ -1738,4 +1810,4 @@ interface StorageContextIn {
 }
 declare const storageRules: <Context extends StorageContextIn = StorageContextIn>(rules: ReadonlyArray<StorageRule<Context>>, options?: StorageRulesOptions) => Middleware<Context, Context>;
 declare const VERSION = "0.0.0";
-export { type ActionBuilder, type ActionCtx, type AggregateIndexDefinition, type AggregateIndexOptions, type AggregateOp, type ArgsValidator, type Component, type ComponentFunctions, type CreateOptions, type DataModelInit, type DefineComponentOptions, type DefinePluginOptions, type DefinePolicyInput, type DefinePresenceOptions, type DefineStorageRuleInput, type EmptyArgs, type EnvAccessor, type EnvKeyFailure, type EnvShape, type ExtendableSchema, type FacadeEntry, type FacadeWriterLike, type FunctionKind, type HttpActionCtx, type HttpActionHandler, type HttpMethod, type HttpRoute, type HttpRouteBuilder, type HttpRouteFactory, type HttpRouteHandlerOptions, type HttpStreamHandlerOptions, type InferArgs, type InferEnv, type InlineAggregateIndexOptions, type InlineRankIndexOptions, type InternalActionBuilder, type InternalMutationBuilder, type InternalQueryBuilder, type LifecycleEvent, type LifecycleHandler, type LunoraBuilders, LunoraEnvError, LunoraError, type LunoraErrorCode, type LunoraHttpApp, type LunoraHttpEnv, type LunoraRouteHandler, type ManyRelation, type MaskColumns, type MaskContext, type MaskFn, type MaskOptions, type MaskPolicies, type MaskStrategy, type Middleware, type MiddlewareNext, type MigrationDefinition, type MigrationDocument, type MigrationTransform, type MutationBuilder, type MutationCtx, type OnDeleteAction, type OneRelation, type OrmLike, DEFAULT_TTL_MS as PRESENCE_DEFAULT_TTL_MS, PRESENCE_TABLE, type Permission, type Plugin, type Policy, type PrefixedTables, type PresenceComponent, type PresenceFunctions, type PresenceMember, type ProtectPublicOptions, type QueryBuilder, type QueryCtx, type RankIndexDefinition, type RankIndexOptions, type RegisteredAction, type RegisteredFunction, type RegisteredLifecycleHook, type RegisteredMigration, type RegisteredMutation, type RegisteredQuery, type RegisteredStream, type RelationBuilder, type RelationDefinition, type RlsOptions, type Role, type Schema, type SchemaExtension, type StorageOperation, type StorageRule, type StorageRuleContext, type StorageRuleDecision, type StorageRulesOptions, type TableBuilder, type TableDefinition, type TerminalKind, type TriggerBuilder, type TriggerDefinition, type TypedDefinePolicyInput, VERSION, type VectorEmbedder, type VectorIndexDefinition, type VectorIndexOptions, type VectorMetric, type VectorizeOptions, type WhereInput, asBucketStorage, bindOrm, bindTableFacade, composePluginMiddleware, createPolicyDsl, defineAggregateIndex, defineComponent, defineEnv, defineMigration, definePermission, definePlugin, definePolicies, definePolicy, definePresence, defineRankIndex, defineRole, defineSchema, defineSchemaExtension, defineStorageRule, defineStorageRules, defineTable, defineVectorIndex, httpAction, httpRoute, httpRouter, initLunora, installPlugins, mask, mergeSchemaExtension, onConnect, onDisconnect, presenceExtension, protectPublic, redactSecrets, rls, serveStorageObject, storageRules };
+export { type ActionBuilder, type ActionCtx, type AggregateIndexDefinition, type AggregateIndexOptions, type AggregateOp, type ArgsValidator, type Component, type ComponentFunctions, type CreateOptions, type DataModelInit, type DefineComponentOptions, type DefinePluginOptions, type DefinePolicyInput, type DefinePresenceOptions, type DefineStorageRuleInput, type DurableObjectJurisdiction, type EmptyArgs, type EnvAccessor, type EnvKeyFailure, type EnvShape, type ExtendableSchema, type FacadeEntry, type FacadeWriterLike, type FunctionKind, type HttpActionCtx, type HttpActionHandler, type HttpMethod, type HttpRoute, type HttpRouteBuilder, type HttpRouteFactory, type HttpRouteHandlerOptions, type HttpStreamHandlerOptions, type InferArgs, type InferEnv, type InlineAggregateIndexOptions, type InlineRankIndexOptions, type InternalActionBuilder, type InternalMutationBuilder, type InternalQueryBuilder, type LifecycleEvent, type LifecycleHandler, type LunoraBuilders, LunoraEnvError, LunoraError, type LunoraErrorCode, type LunoraHttpApp, type LunoraHttpEnv, type LunoraRouteHandler, type ManyRelation, type MaskColumns, type MaskContext, type MaskFn, type MaskOptions, type MaskPolicies, type MaskStrategy, type Middleware, type MiddlewareNext, type MigrationDefinition, type MigrationDocument, type MigrationTransform, type MutationBuilder, type MutationCtx, type OnDeleteAction, type OneRelation, type OrmLike, DEFAULT_TTL_MS as PRESENCE_DEFAULT_TTL_MS, PRESENCE_TABLE, type Permission, type Plugin, type Policy, type PrefixedTables, type PresenceComponent, type PresenceFunctions, type PresenceMember, type ProtectPublicOptions, type QueryBuilder, type QueryCtx, type RankIndexDefinition, type RankIndexOptions, type RegisteredAction, type RegisteredFunction, type RegisteredLifecycleHook, type RegisteredMigration, type RegisteredMutation, type RegisteredQuery, type RegisteredStream, type RelationBuilder, type RelationDefinition, type RlsOptions, type Role, type Schema, type SchemaExtension, type StorageOperation, type StorageRule, type StorageRuleContext, type StorageRuleDecision, type StorageRulesOptions, type TableBuilder, type TableDefinition, type TerminalKind, type TriggerBuilder, type TriggerDefinition, type TypedDefinePolicyInput, VERSION, type VectorEmbedder, type VectorIndexDefinition, type VectorIndexOptions, type VectorMetric, type VectorizeOptions, type WhereInput, asBucketStorage, bindOrm, bindTableFacade, composePluginMiddleware, createPolicyDsl, defineAggregateIndex, defineComponent, defineEnv, defineMigration, definePermission, definePlugin, definePolicies, definePolicy, definePresence, defineRankIndex, defineRole, defineSchema, defineSchemaExtension, defineStorageRule, defineStorageRules, defineTable, defineVectorIndex, httpAction, httpRoute, httpRouter, initLunora, installPlugins, mask, mergeSchemaExtension, onConnect, onDisconnect, presenceExtension, protectPublic, redactSecrets, rls, serveStorageObject, storageRules };