@lunora/server 1.0.0-alpha.1 → 1.0.0-alpha.3

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

@@ -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
@@ -1562,7 +1609,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 +1682,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