@lunora/server 1.0.0-alpha.192 → 1.0.0-alpha.194

package/dist/data-model.d.mts

@@ -37,14 +37,53 @@ interface WhereOperators<T> {
   ne?: T;
   notIn?: T[];
 }
+/**
+ * A value stored as a plain JS object: not a scalar (an `Id<T>` is a branded string, which is an `object` to
+ * TypeScript but has no keys worth offering), an array, a date, bytes, a bigint or a function.
+ */
+type IsPlainObject<V> = V extends string | number | boolean | bigint | symbol ? false : V extends ReadonlyArray<unknown> ? false : V extends Date | Uint8Array | ArrayBuffer | bigint | ((...arguments_: never[]) => unknown) ? false : V extends object ? true : false;
+/** The dotted paths below an object, to three steps. */
+type SubPaths<V, Depth extends unknown[]> = Depth["length"] extends 3 ? never : [IsPlainObject<V>] extends [true] ? { [K in keyof V & string]-?: K | `${K}.${SubPaths<NonNullable<V[K]>, [...Depth, 0]>}`; }[keyof V & string] : never;
+/** The type at the end of dotted path `P` below `V`. */
+type PathValue<V, P extends string> = P extends `${infer Head}.${infer Rest}` ? Head extends keyof V ? PathValue<NonNullable<V[Head]>, Rest> : never : P extends keyof V ? V[P] : never;
+/**
+ * Every dotted path into an object-valued column of `Doc` (`"profile.address.city"`), at most four segments
+ * counting the column. A column that is not a plain object contributes none.
+ */
+type ColumnPaths<Doc> = { [K in keyof Doc & string]-?: [IsPlainObject<NonNullable<Doc[K]>>] extends [true] ? `${K}.${SubPaths<NonNullable<Doc[K]>, []>}` : never; }[keyof Doc & string];
+/** The type at the end of a {@link ColumnPaths} path. */
+type DocPathValue<Doc, P extends string> = P extends `${infer Column}.${infer Rest}` ? Column extends keyof Doc ? PathValue<NonNullable<Doc[Column]>, Rest> : never : never;
+type ScalarLeaf = boolean | number | string | null | undefined;
+/** The dotted paths into an object column that end at a string, number or boolean. */
+type ScalarPaths<Doc> = { [P in ColumnPaths<Doc>]: [DocPathValue<Doc, P>] extends [ScalarLeaf] ? P : never; }[ColumnPaths<Doc>];
+/**
+ * `where` keys that reach into an object column: `{ "profile.plan": "pro" }`. Only paths that end at a string,
+ * number or boolean are offered — an object, array, date, bigint or bytes leaf has no single SQL comparison.
+ *
+ * `unknown` (the identity for `&`) when there are none, never `{}`: intersecting with an empty object type
+ * switches off the weak-type check that rejects a `where` key naming nothing.
+ */
+type PathWhere<Doc, Paths extends string = ScalarPaths<Doc>> = [Paths] extends [never] ? unknown : { [P in Paths]?: DocPathValue<Doc, P> | WhereOperators<DocPathValue<Doc, P>>; };
+/** `patch` keys that set one value inside an object column, keeping its siblings: `{ "profile.plan": "pro" }`. */
+type PathPatch<Doc, Paths extends string = ColumnPaths<Doc>> = [Paths] extends [never] ? unknown : { [P in Paths]?: DocPathValue<Doc, P>; };
 /** A typed `where` tree over a document's columns. */
-type Where<TDocument> = { [K in keyof TDocument]?: TDocument[K] | WhereOperators<TDocument[K]>; } & {
+type Where<TDocument> = PathWhere<TDocument> & { [K in keyof TDocument]?: TDocument[K] | WhereOperators<TDocument[K]>; } & {
   AND?: Where<TDocument>[];
   NOT?: Where<TDocument>;
   OR?: Where<TDocument>[];
 };
-/** One `{ field: "asc" | "desc" }` ordering entry; `orderBy` is an ordered list. */
-type OrderBy<TDocument> = Partial<Record<keyof TDocument, "asc" | "desc">>;
+/**
+ * One ordering entry; `orderBy` is an ordered list. `{ field: "asc" | "desc" }` sorts NULLs first
+ * ascending and last descending. `{ field: { sort: "desc", nulls: "first" } }` places them yourself.
+ *
+ * A placement other than the default can change the query plan (see Pagination in the docs), so
+ * measure a hot read. It has no effect on a column that cannot hold NULL. Keep the same `orderBy` for every page of a
+ * paginated read, as a cursor is only valid against the ordering that minted it.
+ */
+type OrderBy<TDocument> = Partial<Record<keyof TDocument | ScalarPaths<TDocument>, "asc" | "desc" | {
+  nulls: "first" | "last";
+  sort: "asc" | "desc";
+}>>;
 interface QueryArgs<TDocument> {
   cursor?: null | string;
   limit?: number;
@@ -96,7 +135,7 @@ type RelationWhere<DM, REL extends Record<keyof DM, object>, T extends keyof DM>
  * `Where<DM[T]>` stays the column-only structural mirror for back-compat; the
  * table facade threads `REL` through this richer form.
  */
-type WhereOf<DM, REL extends Record<keyof DM, object>, T extends keyof DM> = RelationWhere<DM, REL, T> & { [K in keyof DM[T]]?: DM[T][K] | WhereOperators<DM[T][K]>; } & {
+type WhereOf<DM, REL extends Record<keyof DM, object>, T extends keyof DM> = PathWhere<DM[T]> & RelationWhere<DM, REL, T> & { [K in keyof DM[T]]?: DM[T][K] | WhereOperators<DM[T][K]>; } & {
   AND?: WhereOf<DM, REL, T>[];
   NOT?: WhereOf<DM, REL, T>;
   OR?: WhereOf<DM, REL, T>[];
@@ -348,6 +387,20 @@ interface TableReaderFacade<DM, REL extends Record<keyof DM, object>, RANK exten
   count: (where?: RestrictableQueryOptionsOf<DM, REL, T> | WhereOf<DM, REL, T>) => Promise<number>;
   /** `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>;
+  /**
+   * Describe how this table would run `findMany(args)` without running it: the SQL, its bound
+   * parameters, and the database's own plan, one line per step. Use it to check that a filter is
+   * served by an index (`SEARCH … USING INDEX by_room`) rather than a scan (`SCAN …`).
+   *
+   * Honors RLS and soft delete exactly like the read, so the plan is the one your caller would get.
+   * Explaining does not subscribe a live query to this table. A relation filter in `where` is resolved
+   * first with an ordinary read of the related table, which does subscribe to that table, since the ids
+   * it matched are part of `params`. Takes no `with` or `select`: neither changes the statement.
+   *
+   * `params` carries values your RLS policies injected and, for a relation filter, the ids it matched.
+   * Keep the result on the server rather than returning it to a client.
+   */
+  explain: (args?: QueryArgsOf<DM, REL, T>) => Promise<QueryPlan>;
   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;
@@ -442,10 +495,10 @@ interface TableWriterFacade<DM, IM extends Record<keyof DM, object>, REL extends
    * instead of throwing — the return type widens to `Id | null` on that overload.
    */
   insert: {
-    (values: IM[T], options: {
+    (values: InsertValues<DM, IM, REL, T>, options: {
       skipDuplicates: true;
     }): Promise<Id<string & T> | null>;
-    (values: IM[T], options?: {
+    (values: InsertValues<DM, IM, REL, T>, options?: {
       skipDuplicates?: boolean;
     }): Promise<Id<string & T>>;
   };
@@ -464,7 +517,7 @@ interface TableWriterFacade<DM, IM extends Record<keyof DM, object>, REL extends
       skipDuplicates?: boolean;
     }): Promise<Id<string & T>[]>;
   };
-  patch: (id: Id<string & T>, values: Partial<IM[T]>) => Promise<void>;
+  patch: (id: Id<string & T>, values: PatchValues<IM[T]> & RelationWrites<DM, REL, T>) => Promise<void>;
   /**
    * Patch many rows in this table. Pass an array of `{ id, values }` or
    * `{ where, values }` to patch matching rows with the same values. Returns
@@ -473,7 +526,7 @@ interface TableWriterFacade<DM, IM extends Record<keyof DM, object>, REL extends
   patchMany: {
     (patches: ReadonlyArray<{
       id: Id<string & T>;
-      values: Partial<IM[T]>;
+      values: PatchValues<IM[T]>;
     }>, options?: {
       limit?: number;
     }): Promise<{
@@ -481,7 +534,7 @@ interface TableWriterFacade<DM, IM extends Record<keyof DM, object>, REL extends
     }>;
     (args: {
       limit?: number;
-      values: Partial<IM[T]>;
+      values: PatchValues<IM[T]>;
       where: Partial<DM[T]>;
     }): Promise<{
       patched: number;
@@ -497,9 +550,9 @@ interface TableWriterFacade<DM, IM extends Record<keyof DM, object>, REL extends
    * Composes `findFirst` + `insert`/`patch`, so RLS gates each step.
    */
   upsert: (args: {
-    create: IM[T];
+    create: InsertValues<DM, IM, REL, T>;
     target: UpsertTargetOf<DM, T>;
-    update?: Partial<IM[T]>;
+    update?: PatchValues<IM[T]> & RelationWrites<DM, REL, T>;
   }) => Promise<{
     created: boolean;
     id: Id<string & T>;
@@ -507,8 +560,8 @@ interface TableWriterFacade<DM, IM extends Record<keyof DM, object>, REL extends
   /** 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]>;
+      create: InsertValues<DM, IM, REL, T>;
+      update?: PatchValues<IM[T]> & RelationWrites<DM, REL, T>;
     }>;
     target: UpsertTargetOf<DM, T>;
   }) => Promise<{
@@ -518,8 +571,106 @@ interface TableWriterFacade<DM, IM extends Record<keyof DM, object>, REL extends
 }
 /** 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);
+/**
+ * An atomic update for a number column, applied to the value the row holds when the
+ * write runs: `{ increment: 1 }`, `{ decrement: 1 }`, `{ multiply: 2 }`, `{ divide: 2 }`.
+ * The column must already hold a finite number; a result that is not finite is rejected.
+ */
+type NumberFieldOperator = {
+  decrement: number;
+  divide?: never;
+  increment?: never;
+  multiply?: never;
+} | {
+  decrement?: never;
+  divide: number;
+  increment?: never;
+  multiply?: never;
+} | {
+  decrement?: never;
+  divide?: never;
+  increment: number;
+  multiply?: never;
+} | {
+  decrement?: never;
+  divide?: never;
+  increment?: never;
+  multiply: number;
+};
+/** An atomic update for a boolean column: `{ toggle: true }` flips the stored value. */
+interface BooleanFieldOperator {
+  toggle: true;
+}
+/**
+ * The values a `patch` accepts: any column's own type, and for a number or boolean
+ * column also an atomic operator ({@link NumberFieldOperator}, {@link BooleanFieldOperator}).
+ */
+type PatchValues<Row> = PathPatch<Row> & { [K in keyof Row]?: Row[K] | OperatorFor<NonNullable<Row[K]>>; };
+/**
+ * The operator a column of type `T` takes: arithmetic when `T` is exactly `number` (so a literal union
+ * such as `1 | 2` is out — the result could leave the set — and so is `number | string`, which the
+ * store does not treat as a number column), `{ toggle: true }` when it is exactly `boolean`.
+ */
+type OperatorFor<T> = [T] extends [number] ? [number] extends [T] ? NumberFieldOperator : never : [T] extends [boolean] ? [boolean] extends [T] ? BooleanFieldOperator : never : never;
+/** What `explain` returns: the SQL a read compiles to, its bound parameters, and the database's plan for it. */
+interface QueryPlan {
+  /** The bound parameters, in order. */
+  params: unknown[];
+  /** One line per plan step, as the database reports it. */
+  plan: string[];
+  /** The statement the read compiles to. */
+  sql: string;
+}
+/**
+ * Nested write for a to-one relation: point the row at `Target` (`connect`), or clear the link (`disconnect`, which
+ * needs a foreign key that can be empty). One or the other, not both.
+ */
+type ToOneRelationWrite<TargetId> = {
+  connect: TargetId;
+  disconnect?: never;
+} | {
+  connect?: never;
+  disconnect: true;
+};
+/**
+ * Nested write for a to-many relation: point `Target` rows at this one (`connect`), release them (`disconnect`, which
+ * needs a foreign key that can be empty), or replace the whole list (`set`: rows not named are released). `set`
+ * cannot be combined with the other two.
+ */
+type ToManyRelationWrite<TargetId> = {
+  connect?: never;
+  disconnect?: never;
+  set: ReadonlyArray<TargetId>;
+} | {
+  connect?: ReadonlyArray<TargetId>;
+  disconnect?: ReadonlyArray<TargetId>;
+  set?: never;
+};
+/**
+ * Nested relation writes accepted by `insert`, `patch` and `upsert`, keyed by relation name:
+ * `{ author: { connect: userId } }`, `{ posts: { set: [a, b] } }`. A table with no relations contributes none
+ * (`unknown`, the identity for `&`, never `{}`: an empty object type would switch off the weak-type check).
+ */
+type RelationWrites<DM, REL extends Record<keyof DM, object>, T extends keyof DM> = [keyof REL[T]] extends [never] ? unknown : { [K in keyof REL[T]]?: REL[T][K] extends {
+  __relationKind: "one";
+  __target: infer Target extends keyof DM;
+} ? ToOneRelationWrite<Id<string & Target>> : REL[T][K] extends {
+  __relationKind: "many";
+  __target: infer Target extends keyof DM;
+} ? ToManyRelationWrite<Id<string & Target>> : never; };
+/** The foreign-key columns of a table's to-one relations — the keys a nested `connect` supplies. */
+type OneRelationFields<RelT> = { [K in keyof RelT]: RelT[K] extends {
+  __field: infer Field extends string;
+  __relationKind: "one";
+} ? Field : never; }[keyof RelT];
+/**
+ * What `insert` accepts: the row as it is, or the row without its to-one foreign keys plus the nested writes that
+ * supply them. Leaving a key out with no `connect` to supply it is not caught by the type — the store's own
+ * validation rejects the missing field.
+ */
+type InsertValues<DM, IM extends Record<keyof DM, object>, REL extends Record<keyof DM, object>, T extends keyof DM> = IM[T] | (Omit<IM[T], OneRelationFields<REL[T]>> & RelationWrites<DM, REL, T>);
 /** Per-table read facade — `ctx.db.<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>, GEO extends Record<keyof DM, string> = Record<keyof DM, never>> = { readonly [T in keyof DM]: TableReaderFacade<DM, REL, RANK, SEARCH, T, GEO>; };
 /** Per-table read-write facade — `ctx.db.<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>, GEO extends Record<keyof DM, string> = Record<keyof DM, never>> = { readonly [T in keyof DM]: TableWriterFacade<DM, IM, REL, RANK, SEARCH, T, GEO>; };
-export { AggregateOp, DatabaseReaderFacade, DatabaseWriterFacade, GeoBoundingBox, GeoFilterBuilder, GeoPointInput, GeoReader, 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 };
+export { AggregateOp, DatabaseReaderFacade, DatabaseWriterFacade, GeoBoundingBox, GeoFilterBuilder, GeoPointInput, GeoReader, GroupByEntry, Id, InsertValues, LoadWith, ManyRelationWhere, OneRelationWhere, OrderBy, PatchValues, QueryArgs, QueryArgsOf, QueryPage, QueryPlan, RankPage, RankResult, RelationWrites, RestrictableQueryOptions, RestrictableQueryOptionsOf, SearchFilterBuilder, SearchReader, TableAggregateOptions, TableAggregateOptionsOf, TableGroupByOptions, TableGroupByOptionsOf, TableRankOptions, TableRankPageOptions, TableReaderFacade, TableWriterFacade, ToManyRelationWrite, ToOneRelationWrite, UpsertTargetOf, Where, WhereOf, WhereOperators, WithArg };

package/dist/data-model.d.ts

@@ -37,14 +37,53 @@ interface WhereOperators<T> {
   ne?: T;
   notIn?: T[];
 }
+/**
+ * A value stored as a plain JS object: not a scalar (an `Id<T>` is a branded string, which is an `object` to
+ * TypeScript but has no keys worth offering), an array, a date, bytes, a bigint or a function.
+ */
+type IsPlainObject<V> = V extends string | number | boolean | bigint | symbol ? false : V extends ReadonlyArray<unknown> ? false : V extends Date | Uint8Array | ArrayBuffer | bigint | ((...arguments_: never[]) => unknown) ? false : V extends object ? true : false;
+/** The dotted paths below an object, to three steps. */
+type SubPaths<V, Depth extends unknown[]> = Depth["length"] extends 3 ? never : [IsPlainObject<V>] extends [true] ? { [K in keyof V & string]-?: K | `${K}.${SubPaths<NonNullable<V[K]>, [...Depth, 0]>}`; }[keyof V & string] : never;
+/** The type at the end of dotted path `P` below `V`. */
+type PathValue<V, P extends string> = P extends `${infer Head}.${infer Rest}` ? Head extends keyof V ? PathValue<NonNullable<V[Head]>, Rest> : never : P extends keyof V ? V[P] : never;
+/**
+ * Every dotted path into an object-valued column of `Doc` (`"profile.address.city"`), at most four segments
+ * counting the column. A column that is not a plain object contributes none.
+ */
+type ColumnPaths<Doc> = { [K in keyof Doc & string]-?: [IsPlainObject<NonNullable<Doc[K]>>] extends [true] ? `${K}.${SubPaths<NonNullable<Doc[K]>, []>}` : never; }[keyof Doc & string];
+/** The type at the end of a {@link ColumnPaths} path. */
+type DocPathValue<Doc, P extends string> = P extends `${infer Column}.${infer Rest}` ? Column extends keyof Doc ? PathValue<NonNullable<Doc[Column]>, Rest> : never : never;
+type ScalarLeaf = boolean | number | string | null | undefined;
+/** The dotted paths into an object column that end at a string, number or boolean. */
+type ScalarPaths<Doc> = { [P in ColumnPaths<Doc>]: [DocPathValue<Doc, P>] extends [ScalarLeaf] ? P : never; }[ColumnPaths<Doc>];
+/**
+ * `where` keys that reach into an object column: `{ "profile.plan": "pro" }`. Only paths that end at a string,
+ * number or boolean are offered — an object, array, date, bigint or bytes leaf has no single SQL comparison.
+ *
+ * `unknown` (the identity for `&`) when there are none, never `{}`: intersecting with an empty object type
+ * switches off the weak-type check that rejects a `where` key naming nothing.
+ */
+type PathWhere<Doc, Paths extends string = ScalarPaths<Doc>> = [Paths] extends [never] ? unknown : { [P in Paths]?: DocPathValue<Doc, P> | WhereOperators<DocPathValue<Doc, P>>; };
+/** `patch` keys that set one value inside an object column, keeping its siblings: `{ "profile.plan": "pro" }`. */
+type PathPatch<Doc, Paths extends string = ColumnPaths<Doc>> = [Paths] extends [never] ? unknown : { [P in Paths]?: DocPathValue<Doc, P>; };
 /** A typed `where` tree over a document's columns. */
-type Where<TDocument> = { [K in keyof TDocument]?: TDocument[K] | WhereOperators<TDocument[K]>; } & {
+type Where<TDocument> = PathWhere<TDocument> & { [K in keyof TDocument]?: TDocument[K] | WhereOperators<TDocument[K]>; } & {
   AND?: Where<TDocument>[];
   NOT?: Where<TDocument>;
   OR?: Where<TDocument>[];
 };
-/** One `{ field: "asc" | "desc" }` ordering entry; `orderBy` is an ordered list. */
-type OrderBy<TDocument> = Partial<Record<keyof TDocument, "asc" | "desc">>;
+/**
+ * One ordering entry; `orderBy` is an ordered list. `{ field: "asc" | "desc" }` sorts NULLs first
+ * ascending and last descending. `{ field: { sort: "desc", nulls: "first" } }` places them yourself.
+ *
+ * A placement other than the default can change the query plan (see Pagination in the docs), so
+ * measure a hot read. It has no effect on a column that cannot hold NULL. Keep the same `orderBy` for every page of a
+ * paginated read, as a cursor is only valid against the ordering that minted it.
+ */
+type OrderBy<TDocument> = Partial<Record<keyof TDocument | ScalarPaths<TDocument>, "asc" | "desc" | {
+  nulls: "first" | "last";
+  sort: "asc" | "desc";
+}>>;
 interface QueryArgs<TDocument> {
   cursor?: null | string;
   limit?: number;
@@ -96,7 +135,7 @@ type RelationWhere<DM, REL extends Record<keyof DM, object>, T extends keyof DM>
  * `Where<DM[T]>` stays the column-only structural mirror for back-compat; the
  * table facade threads `REL` through this richer form.
  */
-type WhereOf<DM, REL extends Record<keyof DM, object>, T extends keyof DM> = RelationWhere<DM, REL, T> & { [K in keyof DM[T]]?: DM[T][K] | WhereOperators<DM[T][K]>; } & {
+type WhereOf<DM, REL extends Record<keyof DM, object>, T extends keyof DM> = PathWhere<DM[T]> & RelationWhere<DM, REL, T> & { [K in keyof DM[T]]?: DM[T][K] | WhereOperators<DM[T][K]>; } & {
   AND?: WhereOf<DM, REL, T>[];
   NOT?: WhereOf<DM, REL, T>;
   OR?: WhereOf<DM, REL, T>[];
@@ -348,6 +387,20 @@ interface TableReaderFacade<DM, REL extends Record<keyof DM, object>, RANK exten
   count: (where?: RestrictableQueryOptionsOf<DM, REL, T> | WhereOf<DM, REL, T>) => Promise<number>;
   /** `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>;
+  /**
+   * Describe how this table would run `findMany(args)` without running it: the SQL, its bound
+   * parameters, and the database's own plan, one line per step. Use it to check that a filter is
+   * served by an index (`SEARCH … USING INDEX by_room`) rather than a scan (`SCAN …`).
+   *
+   * Honors RLS and soft delete exactly like the read, so the plan is the one your caller would get.
+   * Explaining does not subscribe a live query to this table. A relation filter in `where` is resolved
+   * first with an ordinary read of the related table, which does subscribe to that table, since the ids
+   * it matched are part of `params`. Takes no `with` or `select`: neither changes the statement.
+   *
+   * `params` carries values your RLS policies injected and, for a relation filter, the ids it matched.
+   * Keep the result on the server rather than returning it to a client.
+   */
+  explain: (args?: QueryArgsOf<DM, REL, T>) => Promise<QueryPlan>;
   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;
@@ -442,10 +495,10 @@ interface TableWriterFacade<DM, IM extends Record<keyof DM, object>, REL extends
    * instead of throwing — the return type widens to `Id | null` on that overload.
    */
   insert: {
-    (values: IM[T], options: {
+    (values: InsertValues<DM, IM, REL, T>, options: {
       skipDuplicates: true;
     }): Promise<Id<string & T> | null>;
-    (values: IM[T], options?: {
+    (values: InsertValues<DM, IM, REL, T>, options?: {
       skipDuplicates?: boolean;
     }): Promise<Id<string & T>>;
   };
@@ -464,7 +517,7 @@ interface TableWriterFacade<DM, IM extends Record<keyof DM, object>, REL extends
       skipDuplicates?: boolean;
     }): Promise<Id<string & T>[]>;
   };
-  patch: (id: Id<string & T>, values: Partial<IM[T]>) => Promise<void>;
+  patch: (id: Id<string & T>, values: PatchValues<IM[T]> & RelationWrites<DM, REL, T>) => Promise<void>;
   /**
    * Patch many rows in this table. Pass an array of `{ id, values }` or
    * `{ where, values }` to patch matching rows with the same values. Returns
@@ -473,7 +526,7 @@ interface TableWriterFacade<DM, IM extends Record<keyof DM, object>, REL extends
   patchMany: {
     (patches: ReadonlyArray<{
       id: Id<string & T>;
-      values: Partial<IM[T]>;
+      values: PatchValues<IM[T]>;
     }>, options?: {
       limit?: number;
     }): Promise<{
@@ -481,7 +534,7 @@ interface TableWriterFacade<DM, IM extends Record<keyof DM, object>, REL extends
     }>;
     (args: {
       limit?: number;
-      values: Partial<IM[T]>;
+      values: PatchValues<IM[T]>;
       where: Partial<DM[T]>;
     }): Promise<{
       patched: number;
@@ -497,9 +550,9 @@ interface TableWriterFacade<DM, IM extends Record<keyof DM, object>, REL extends
    * Composes `findFirst` + `insert`/`patch`, so RLS gates each step.
    */
   upsert: (args: {
-    create: IM[T];
+    create: InsertValues<DM, IM, REL, T>;
     target: UpsertTargetOf<DM, T>;
-    update?: Partial<IM[T]>;
+    update?: PatchValues<IM[T]> & RelationWrites<DM, REL, T>;
   }) => Promise<{
     created: boolean;
     id: Id<string & T>;
@@ -507,8 +560,8 @@ interface TableWriterFacade<DM, IM extends Record<keyof DM, object>, REL extends
   /** 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]>;
+      create: InsertValues<DM, IM, REL, T>;
+      update?: PatchValues<IM[T]> & RelationWrites<DM, REL, T>;
     }>;
     target: UpsertTargetOf<DM, T>;
   }) => Promise<{
@@ -518,8 +571,106 @@ interface TableWriterFacade<DM, IM extends Record<keyof DM, object>, REL extends
 }
 /** 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);
+/**
+ * An atomic update for a number column, applied to the value the row holds when the
+ * write runs: `{ increment: 1 }`, `{ decrement: 1 }`, `{ multiply: 2 }`, `{ divide: 2 }`.
+ * The column must already hold a finite number; a result that is not finite is rejected.
+ */
+type NumberFieldOperator = {
+  decrement: number;
+  divide?: never;
+  increment?: never;
+  multiply?: never;
+} | {
+  decrement?: never;
+  divide: number;
+  increment?: never;
+  multiply?: never;
+} | {
+  decrement?: never;
+  divide?: never;
+  increment: number;
+  multiply?: never;
+} | {
+  decrement?: never;
+  divide?: never;
+  increment?: never;
+  multiply: number;
+};
+/** An atomic update for a boolean column: `{ toggle: true }` flips the stored value. */
+interface BooleanFieldOperator {
+  toggle: true;
+}
+/**
+ * The values a `patch` accepts: any column's own type, and for a number or boolean
+ * column also an atomic operator ({@link NumberFieldOperator}, {@link BooleanFieldOperator}).
+ */
+type PatchValues<Row> = PathPatch<Row> & { [K in keyof Row]?: Row[K] | OperatorFor<NonNullable<Row[K]>>; };
+/**
+ * The operator a column of type `T` takes: arithmetic when `T` is exactly `number` (so a literal union
+ * such as `1 | 2` is out — the result could leave the set — and so is `number | string`, which the
+ * store does not treat as a number column), `{ toggle: true }` when it is exactly `boolean`.
+ */
+type OperatorFor<T> = [T] extends [number] ? [number] extends [T] ? NumberFieldOperator : never : [T] extends [boolean] ? [boolean] extends [T] ? BooleanFieldOperator : never : never;
+/** What `explain` returns: the SQL a read compiles to, its bound parameters, and the database's plan for it. */
+interface QueryPlan {
+  /** The bound parameters, in order. */
+  params: unknown[];
+  /** One line per plan step, as the database reports it. */
+  plan: string[];
+  /** The statement the read compiles to. */
+  sql: string;
+}
+/**
+ * Nested write for a to-one relation: point the row at `Target` (`connect`), or clear the link (`disconnect`, which
+ * needs a foreign key that can be empty). One or the other, not both.
+ */
+type ToOneRelationWrite<TargetId> = {
+  connect: TargetId;
+  disconnect?: never;
+} | {
+  connect?: never;
+  disconnect: true;
+};
+/**
+ * Nested write for a to-many relation: point `Target` rows at this one (`connect`), release them (`disconnect`, which
+ * needs a foreign key that can be empty), or replace the whole list (`set`: rows not named are released). `set`
+ * cannot be combined with the other two.
+ */
+type ToManyRelationWrite<TargetId> = {
+  connect?: never;
+  disconnect?: never;
+  set: ReadonlyArray<TargetId>;
+} | {
+  connect?: ReadonlyArray<TargetId>;
+  disconnect?: ReadonlyArray<TargetId>;
+  set?: never;
+};
+/**
+ * Nested relation writes accepted by `insert`, `patch` and `upsert`, keyed by relation name:
+ * `{ author: { connect: userId } }`, `{ posts: { set: [a, b] } }`. A table with no relations contributes none
+ * (`unknown`, the identity for `&`, never `{}`: an empty object type would switch off the weak-type check).
+ */
+type RelationWrites<DM, REL extends Record<keyof DM, object>, T extends keyof DM> = [keyof REL[T]] extends [never] ? unknown : { [K in keyof REL[T]]?: REL[T][K] extends {
+  __relationKind: "one";
+  __target: infer Target extends keyof DM;
+} ? ToOneRelationWrite<Id<string & Target>> : REL[T][K] extends {
+  __relationKind: "many";
+  __target: infer Target extends keyof DM;
+} ? ToManyRelationWrite<Id<string & Target>> : never; };
+/** The foreign-key columns of a table's to-one relations — the keys a nested `connect` supplies. */
+type OneRelationFields<RelT> = { [K in keyof RelT]: RelT[K] extends {
+  __field: infer Field extends string;
+  __relationKind: "one";
+} ? Field : never; }[keyof RelT];
+/**
+ * What `insert` accepts: the row as it is, or the row without its to-one foreign keys plus the nested writes that
+ * supply them. Leaving a key out with no `connect` to supply it is not caught by the type — the store's own
+ * validation rejects the missing field.
+ */
+type InsertValues<DM, IM extends Record<keyof DM, object>, REL extends Record<keyof DM, object>, T extends keyof DM> = IM[T] | (Omit<IM[T], OneRelationFields<REL[T]>> & RelationWrites<DM, REL, T>);
 /** Per-table read facade — `ctx.db.<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>, GEO extends Record<keyof DM, string> = Record<keyof DM, never>> = { readonly [T in keyof DM]: TableReaderFacade<DM, REL, RANK, SEARCH, T, GEO>; };
 /** Per-table read-write facade — `ctx.db.<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>, GEO extends Record<keyof DM, string> = Record<keyof DM, never>> = { readonly [T in keyof DM]: TableWriterFacade<DM, IM, REL, RANK, SEARCH, T, GEO>; };
-export { AggregateOp, DatabaseReaderFacade, DatabaseWriterFacade, GeoBoundingBox, GeoFilterBuilder, GeoPointInput, GeoReader, 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 };
+export { AggregateOp, DatabaseReaderFacade, DatabaseWriterFacade, GeoBoundingBox, GeoFilterBuilder, GeoPointInput, GeoReader, GroupByEntry, Id, InsertValues, LoadWith, ManyRelationWhere, OneRelationWhere, OrderBy, PatchValues, QueryArgs, QueryArgsOf, QueryPage, QueryPlan, RankPage, RankResult, RelationWrites, RestrictableQueryOptions, RestrictableQueryOptionsOf, SearchFilterBuilder, SearchReader, TableAggregateOptions, TableAggregateOptionsOf, TableGroupByOptions, TableGroupByOptionsOf, TableRankOptions, TableRankPageOptions, TableReaderFacade, TableWriterFacade, ToManyRelationWrite, ToOneRelationWrite, UpsertTargetOf, Where, WhereOf, WhereOperators, WithArg };

package/dist/in-process.mjs

@@ -1 +1 @@
-import{LunoraError as b}from"@lunora/errors";import{runShardMigrations as w,TransactionHeadroomTracker as d,createShardCtxDb as R,RLS_UNWRAP_SYMBOL as T}from"@lunora/shard-engine";import{beginDeferredSchedules as g}from"./packem_shared/beginDeferredSchedules-CmmdpWRS.mjs";import{bindTableFacade as y}from"./packem_shared/bindOrm-D_hFUjmr.mjs";const k=r=>{if(r===null||typeof r.userId!="string"||r.userId.length===0)return{claims:null,userId:null};const{userId:e,...s}=r;return{claims:Object.keys(s).length>0?s:null,userId:e}};class S extends d{current=new d;reset(){this.current=new d}headroom(){return this.current.headroom()}recordRead(e){this.current.recordRead(e)}recordWrite(e){this.current.recordWrite(e)}}const x=(r,e)=>{const{scheduler:s,sql:a}=e,i=r;w(a,i);const c=new S,h=t=>{const n=t;for(const o of Object.keys(i.tables))n[o]=y(t,o);return t},I=t=>{const n=R({auth:{identity:t.claims,userId:t.userId},enforceRls:e.enforceRls??!0,headroom:c,schema:i,sql:a}),o=n[T]??n;return{database:h(n),rawDatabase:h(o)}},u=t=>{a.exec.call(a,t)};let m=Promise.resolve();return{createWriters:I,resetHeadroom:()=>{c.reset()},runInTransaction:t=>{const n=async()=>{const f=g({scheduler:s});c.reset(),u("BEGIN");try{const l=await t();return u("COMMIT"),await f(!0),l}catch(l){try{u("ROLLBACK")}catch{}throw await f(!1),l}},o=m.then(n);return m=o.then(()=>{},()=>{}),o}}},p=r=>{if(typeof r!="object"||r===null)return;const{kind:e}=r;if(e==="query"||e==="mutation"||e==="action")return e},A=(r,e,s,a,i)=>{const c=p(e);if(c!==r)throw new b("INTERNAL",`expected a registered ${r}, received a ${c??"non-function"} reference`);if(!i&&e.visibility==="internal")throw new b("INTERNAL",`This ${r} is an internal function — it is unreachable from the external RPC boundary in production. Call it through ctx.run${r.charAt(0).toUpperCase()}${r.slice(1)} from another function instead.`);return Promise.resolve(e.handler(s,a??{}))};export{x as createInProcessRuntime,p as registeredFunctionKind,k as resolveInProcessIdentity,A as runRegisteredFunction};
+import{LunoraError as b}from"@lunora/errors";import{runShardMigrations as w,TransactionHeadroomTracker as d,createShardCtxDb as R,RLS_UNWRAP_SYMBOL as T}from"@lunora/shard-engine";import{beginDeferredSchedules as g}from"./packem_shared/beginDeferredSchedules-CmmdpWRS.mjs";import{bindTableFacade as y}from"./packem_shared/bindOrm-BaAMwCFL.mjs";const k=r=>{if(r===null||typeof r.userId!="string"||r.userId.length===0)return{claims:null,userId:null};const{userId:e,...s}=r;return{claims:Object.keys(s).length>0?s:null,userId:e}};class S extends d{current=new d;reset(){this.current=new d}headroom(){return this.current.headroom()}recordRead(e){this.current.recordRead(e)}recordWrite(e){this.current.recordWrite(e)}}const x=(r,e)=>{const{scheduler:s,sql:a}=e,i=r;w(a,i);const c=new S,h=t=>{const n=t;for(const o of Object.keys(i.tables))n[o]=y(t,o);return t},I=t=>{const n=R({auth:{identity:t.claims,userId:t.userId},enforceRls:e.enforceRls??!0,headroom:c,schema:i,sql:a}),o=n[T]??n;return{database:h(n),rawDatabase:h(o)}},u=t=>{a.exec.call(a,t)};let m=Promise.resolve();return{createWriters:I,resetHeadroom:()=>{c.reset()},runInTransaction:t=>{const n=async()=>{const f=g({scheduler:s});c.reset(),u("BEGIN");try{const l=await t();return u("COMMIT"),await f(!0),l}catch(l){try{u("ROLLBACK")}catch{}throw await f(!1),l}},o=m.then(n);return m=o.then(()=>{},()=>{}),o}}},p=r=>{if(typeof r!="object"||r===null)return;const{kind:e}=r;if(e==="query"||e==="mutation"||e==="action")return e},A=(r,e,s,a,i)=>{const c=p(e);if(c!==r)throw new b("INTERNAL",`expected a registered ${r}, received a ${c??"non-function"} reference`);if(!i&&e.visibility==="internal")throw new b("INTERNAL",`This ${r} is an internal function — it is unreachable from the external RPC boundary in production. Call it through ctx.run${r.charAt(0).toUpperCase()}${r.slice(1)} from another function instead.`);return Promise.resolve(e.handler(s,a??{}))};export{x as createInProcessRuntime,p as registeredFunctionKind,k as resolveInProcessIdentity,A as runRegisteredFunction};