@ai-matrx/data 0.23.0 → 0.25.0

package/dist/db.d.cts

@@ -842,6 +842,12 @@ interface TableDescriptor<Row = Record<string, unknown>, Insert = Record<string,
     readonly readOnlyColumns: readonly string[];
     readonly listScope: string | null;
     readonly realtime: boolean;
+    /**
+     * The table has a `created_by` column. A signed-in insert that omits it is stamped with the
+     * session's person (row security on tables like `workbench.notes` refuses an insert whose
+     * `created_by` is not `auth.uid()`). Optional: descriptors generated before 0.25.0 lack it.
+     */
+    readonly createdBy?: boolean;
     readonly [ROW]?: {
         row: Row;
         insert: Insert;
@@ -884,6 +890,7 @@ interface QueryLike extends PromiseLike<Resp<any>> {
     update(values: unknown): QueryLike;
     delete(): QueryLike;
     eq(column: string, value: unknown): QueryLike;
+    is(column: string, value: null | boolean): QueryLike;
     order(column: string, opts?: {
         ascending?: boolean;
     }): QueryLike;
@@ -902,6 +909,9 @@ interface SupabaseLike {
             data: {
                 session: {
                     access_token: string;
+                    user?: {
+                        id: string;
+                    } | null;
                 } | null;
             };
         }>;
@@ -958,74 +968,123 @@ declare class DatabaseError extends Error {
 type Op = "read" | "insert" | "update" | "remove" | "archive";
 /** Refuse before the wire when the descriptor's rules do not open this door. */
 declare function assertDoor(db: Db, table: TableDescriptor<any, any, any>, op: Op): void;
+type Col<R> = Extract<keyof R, string>;
+/** The typed filter a `Where` callback receives — column names and values checked against the row. */
+interface Filter<R> {
+    eq<K extends Col<R>>(column: K, value: NonNullable<R[K]>): Filter<R>;
+    neq<K extends Col<R>>(column: K, value: NonNullable<R[K]>): Filter<R>;
+    gt<K extends Col<R>>(column: K, value: NonNullable<R[K]>): Filter<R>;
+    gte<K extends Col<R>>(column: K, value: NonNullable<R[K]>): Filter<R>;
+    lt<K extends Col<R>>(column: K, value: NonNullable<R[K]>): Filter<R>;
+    lte<K extends Col<R>>(column: K, value: NonNullable<R[K]>): Filter<R>;
+    like(column: Col<R>, pattern: string): Filter<R>;
+    ilike(column: Col<R>, pattern: string): Filter<R>;
+    in<K extends Col<R>>(column: K, values: readonly NonNullable<R[K]>[]): Filter<R>;
+    is(column: Col<R>, value: null | boolean): Filter<R>;
+    contains(column: Col<R>, value: unknown): Filter<R>;
+    overlaps(column: Col<R>, value: unknown): Filter<R>;
+    textSearch(column: Col<R>, query: string, opts?: {
+        type?: "plain" | "phrase" | "websearch";
+        config?: string;
+    }): Filter<R>;
+    /** PostgREST's raw `or` grammar (`"pinned.eq.true,starred.eq.true"`). */
+    or(filters: string, opts?: {
+        referencedTable?: string;
+    }): Filter<R>;
+    not(column: Col<R>, operator: string, value: unknown): Filter<R>;
+}
+/** A filter callback — the same builder `readAllRows` callers write today, typed to the row. */
+type Where<R = any> = (q: Filter<R>) => Filter<R>;
+interface ReadOptions<C> {
+    /** Only these columns (the result is typed to them). Default every column. */
+    columns?: readonly C[];
+    /** Include soft-deleted rows (default: excluded on tables with `deleted_at`). */
+    includeDeleted?: boolean;
+}
 /** One row by primary key (a composite key takes `{ col: value }`), or null. */
-declare function read<T extends TableDescriptor<any, any, any>>(db: Db, table: T, id: unknown, columns?: string): Promise<RowOf<T> | null>;
-/** A filter callback — the same builder `readAllRows` callers write today (`q => q.or(…).gte(…)`). */
-type Where = (q: any) => any;
-/** EVERY matching row, paged past the 1,000-row cap; throws on a short read. */
-declare function listAll<T extends TableDescriptor<any, any, any>>(db: Db, table: T, where?: Where, opts?: {
-    columns?: string;
-    orderBy?: string;
+declare function read<R, I, U, C extends Col<R> = Col<R>>(db: Db, table: TableDescriptor<R, I, U>, id: unknown, opts?: ReadOptions<C>): Promise<Pick<R, C> | null>;
+/** EVERY matching row, paged past the 1,000-row cap (ordered by the full key); throws on a short read. */
+declare function listAll<R, I, U, C extends Col<R> = Col<R>>(db: Db, table: TableDescriptor<R, I, U>, where?: Where<R>, opts?: ReadOptions<C> & {
+    orderBy?: Col<R>;
     pageSize?: number;
     maxRows?: number;
-}): Promise<RowOf<T>[]>;
+}): Promise<Pick<R, C>[]>;
 /** One explicit window (`from`..`to`, inclusive) plus the exact total. */
-declare function page<T extends TableDescriptor<any, any, any>>(db: Db, table: T, window: {
+declare function page<R, I, U, C extends Col<R> = Col<R>>(db: Db, table: TableDescriptor<R, I, U>, window: ReadOptions<C> & {
     from: number;
     to: number;
-    where?: Where;
-    columns?: string;
-    orderBy?: string;
+    where?: Where<R>;
+    orderBy?: Col<R>;
     ascending?: boolean;
 }): Promise<{
-    rows: RowOf<T>[];
+    rows: Pick<R, C>[];
     total: number | null;
 }>;
 /** The exact count of matching rows (no rows transferred). */
-declare function count<T extends TableDescriptor<any, any, any>>(db: Db, table: T, where?: Where): Promise<number>;
+declare function count<R, I, U>(db: Db, table: TableDescriptor<R, I, U>, where?: Where<R>, opts?: {
+    includeDeleted?: boolean;
+}): Promise<number>;
 /** Insert one row (or many) and return what the database stored. */
-declare function insert<T extends TableDescriptor<any, any, any>>(db: Db, table: T, values: InsertOf<T>): Promise<RowOf<T>>;
-declare function insert<T extends TableDescriptor<any, any, any>>(db: Db, table: T, values: InsertOf<T>[]): Promise<RowOf<T>[]>;
+declare function insert<R, I, U>(db: Db, table: TableDescriptor<R, I, U>, values: I): Promise<R>;
+declare function insert<R, I, U>(db: Db, table: TableDescriptor<R, I, U>, values: readonly I[]): Promise<R[]>;
+/** Every write on a versioned table is explicit: `{ expectedVersion }` (guarded) or `{ overwrite: true }`. */
 type UpdateGuard = {
     expectedVersion: number;
 } | {
     overwrite: true;
 };
+type WriteResult<R> = {
+    status: "saved";
+    row: R;
+    rebasedFrom?: {
+        expectedVersion: number;
+        currentVersion: number;
+    };
+} | {
+    status: "conflict";
+    currentRow: R;
+    currentVersion: number;
+} | {
+    status: "not_found";
+};
 /**
  * Update one row by primary key. On a versioned table the guard is required:
  * `{ expectedVersion }` (a conflict comes back, never a silent overwrite) or
- * `{ overwrite: true }`.
+ * `{ overwrite: true }`; on an unversioned table `expectedVersion` is refused.
  */
-declare function update<T extends TableDescriptor<any, any, any>>(db: Db, table: T, id: unknown, patch: UpdateOf<T>, guard?: UpdateGuard): Promise<GuardedUpdateResult<RowOf<T> & {
-    version: number;
-}> | {
-    status: "saved";
-    row: RowOf<T>;
-} | {
-    status: "not_found";
-}>;
+declare function update<R, I, U>(db: Db, table: TableDescriptor<R, I, U>, id: unknown, patch: U, guard?: UpdateGuard): Promise<WriteResult<R>>;
 /**
  * Remove one row the way the table removes: soft delete (`deleted_at`) where it
  * has one; an archive-only table refuses (use `archive`); a hard delete only where
- * the table has neither.
+ * the table has neither. Guarded like `update` on a versioned table.
  */
-declare function remove<T extends TableDescriptor<any, any, any>>(db: Db, table: T, id: unknown): Promise<"soft_deleted" | "deleted" | "not_found">;
-/** Archive (or, with `restore`, bring back) one row by the table's archive column. */
-declare function archive<T extends TableDescriptor<any, any, any>>(db: Db, table: T, id: unknown, opts?: {
+declare function remove<R, I, U>(db: Db, table: TableDescriptor<R, I, U>, id: unknown, guard?: UpdateGuard): Promise<{
+    status: "soft_deleted" | "deleted" | "not_found";
+} | {
+    status: "conflict";
+    currentVersion: number;
+}>;
+/** Archive (or, with `restore`, bring back) one row by the table's archive column. Guarded like `update`. */
+declare function archive<R, I, U>(db: Db, table: TableDescriptor<R, I, U>, id: unknown, opts?: {
     restore?: boolean;
-}): Promise<RowOf<T> | null>;
+    guard?: UpdateGuard;
+}): Promise<WriteResult<R>>;
 /** Bring back an archived or soft-deleted row. */
-declare const restore: <T extends TableDescriptor<any, any, any>>(db: Db, table: T, id: unknown) => Promise<RowOf<T> | null>;
+declare const restore: <R, I, U>(db: Db, table: TableDescriptor<R, I, U>, id: unknown, guard?: UpdateGuard) => Promise<WriteResult<R>>;
 /** Call a database function through its generated door (PostgREST chooses an overload by argument names). */
 declare function call<F extends FunctionDescriptor<any, any>>(db: Db, fn: F, args: ArgsOf<F>): Promise<ResultOf<F>>;
-/** The compact flags index `matrx-data generate --flags-index` writes: "schema.table" → descriptor. */
+/** One schema's flags (`<schema>.flags.ts` from `matrx-data generate --flags-index`): "schema.table" → descriptor. */
 type FlagsIndex = Readonly<Record<string, TableDescriptor>>;
+/** Per-schema loaders (`flags-index.ts`): only the schema a runtime name names is loaded (pay-only). */
+type FlagLoaders = Readonly<Record<string, () => Promise<FlagsIndex>>>;
 /** The door for a table whose name arrives at runtime — loosely typed, the same rules. */
 declare function tableByName(index: FlagsIndex, name: string): TableDescriptor;
+/** `tableByName` over per-schema loaders: loads only the named schema's flags. */
+declare function loadTableByName(loaders: FlagLoaders, name: string): Promise<TableDescriptor>;
 /** The `postgres_changes` filter for a table — only published tables have one (an unpublished table delivers nothing). */
 declare function changesOf(table: TableDescriptor<any, any, any>): {
     schema: string;
     table: string;
 };
 
-export { type ActiveOrgCookie, type ActiveOrgCookieOptions, type ActiveOrgSelection, type ArgsOf, type AuthRetryableResult, BulkWriteError, type CreateActiveOrgCookieArgs, type CreateDbOptions, type CreateOAuthRefreshFetchArgs, type CreateSessionRetryOptions, DEFAULT_ACTIVE_ORG_COOKIE_MAX_AGE, DEFAULT_ACTIVE_ORG_COOKIE_NAME, DatabaseError, type Db, DoorRefusedError, type FlagsIndex, type FunctionDescriptor, type GuardedUpdateArgs, type GuardedUpdateResult, IncompleteReadError, type InsertOf, type JsonObject, type MergeJsonColumnArgs, type MergeJsonColumnResult, type OAuthRefreshStorage, type OrgRule, type PagedReadQuery, type PagedReadResult, type QueryLike, type ReadAllRowsOptions, type ReadAllRowsRestOptions, RecordUnavailableError, type RecordUnavailableReason, type RecordUnavailableResolution, type ResultOf, type RowOf, type SessionSource, SessionUnavailableError, type SupabaseLike, type TableDescriptor, type TableType, type TryWriteOneResult, type UpdateGuard, type UpdateOf, type UserCredentialsPort, type VersionedRow, type Where, WriteDidNotLandError, type WriteDidNotLandReason, type WriteFailureWords, type WriteOneAction, type WriteOneOptions, type WriteOneRowResult, WriteRefusedError, archive, asJsonObject, assertDoor, assertWriteLanded, call, changesOf, count, createActiveOrgCookie, createDb, createOAuthRefreshFetch, createServiceDb, createSessionRetry, decodeActiveOrgSelection, decodeOAuthRefreshClaims, describeWriteFailure, encodeActiveOrgSelection, guardedUpdate, insert, isMissingSessionError, isRecordUnavailableError, listAll, mergeJsonColumn, page, personSentence, read, readAllRows, readAllRowsRest, recordUnavailableMessage, remove, restore, serverMessageFromBody, tableByName, tryReadAllRows, tryReadAllRowsRest, tryWriteOne, update, writeFailureStatus, writeOne, writeOneRow };
+export { type ActiveOrgCookie, type ActiveOrgCookieOptions, type ActiveOrgSelection, type ArgsOf, type AuthRetryableResult, BulkWriteError, type CreateActiveOrgCookieArgs, type CreateDbOptions, type CreateOAuthRefreshFetchArgs, type CreateSessionRetryOptions, DEFAULT_ACTIVE_ORG_COOKIE_MAX_AGE, DEFAULT_ACTIVE_ORG_COOKIE_NAME, DatabaseError, type Db, DoorRefusedError, type Filter, type FlagLoaders, type FlagsIndex, type FunctionDescriptor, type GuardedUpdateArgs, type GuardedUpdateResult, IncompleteReadError, type InsertOf, type JsonObject, type MergeJsonColumnArgs, type MergeJsonColumnResult, type OAuthRefreshStorage, type OrgRule, type PagedReadQuery, type PagedReadResult, type QueryLike, type ReadAllRowsOptions, type ReadAllRowsRestOptions, type ReadOptions, RecordUnavailableError, type RecordUnavailableReason, type RecordUnavailableResolution, type ResultOf, type RowOf, type SessionSource, SessionUnavailableError, type SupabaseLike, type TableDescriptor, type TableType, type TryWriteOneResult, type UpdateGuard, type UpdateOf, type UserCredentialsPort, type VersionedRow, type Where, WriteDidNotLandError, type WriteDidNotLandReason, type WriteFailureWords, type WriteOneAction, type WriteOneOptions, type WriteOneRowResult, WriteRefusedError, type WriteResult, archive, asJsonObject, assertDoor, assertWriteLanded, call, changesOf, count, createActiveOrgCookie, createDb, createOAuthRefreshFetch, createServiceDb, createSessionRetry, decodeActiveOrgSelection, decodeOAuthRefreshClaims, describeWriteFailure, encodeActiveOrgSelection, guardedUpdate, insert, isMissingSessionError, isRecordUnavailableError, listAll, loadTableByName, mergeJsonColumn, page, personSentence, read, readAllRows, readAllRowsRest, recordUnavailableMessage, remove, restore, serverMessageFromBody, tableByName, tryReadAllRows, tryReadAllRowsRest, tryWriteOne, update, writeFailureStatus, writeOne, writeOneRow };

package/dist/db.d.ts

@@ -842,6 +842,12 @@ interface TableDescriptor<Row = Record<string, unknown>, Insert = Record<string,
     readonly readOnlyColumns: readonly string[];
     readonly listScope: string | null;
     readonly realtime: boolean;
+    /**
+     * The table has a `created_by` column. A signed-in insert that omits it is stamped with the
+     * session's person (row security on tables like `workbench.notes` refuses an insert whose
+     * `created_by` is not `auth.uid()`). Optional: descriptors generated before 0.25.0 lack it.
+     */
+    readonly createdBy?: boolean;
     readonly [ROW]?: {
         row: Row;
         insert: Insert;
@@ -884,6 +890,7 @@ interface QueryLike extends PromiseLike<Resp<any>> {
     update(values: unknown): QueryLike;
     delete(): QueryLike;
     eq(column: string, value: unknown): QueryLike;
+    is(column: string, value: null | boolean): QueryLike;
     order(column: string, opts?: {
         ascending?: boolean;
     }): QueryLike;
@@ -902,6 +909,9 @@ interface SupabaseLike {
             data: {
                 session: {
                     access_token: string;
+                    user?: {
+                        id: string;
+                    } | null;
                 } | null;
             };
         }>;
@@ -958,74 +968,123 @@ declare class DatabaseError extends Error {
 type Op = "read" | "insert" | "update" | "remove" | "archive";
 /** Refuse before the wire when the descriptor's rules do not open this door. */
 declare function assertDoor(db: Db, table: TableDescriptor<any, any, any>, op: Op): void;
+type Col<R> = Extract<keyof R, string>;
+/** The typed filter a `Where` callback receives — column names and values checked against the row. */
+interface Filter<R> {
+    eq<K extends Col<R>>(column: K, value: NonNullable<R[K]>): Filter<R>;
+    neq<K extends Col<R>>(column: K, value: NonNullable<R[K]>): Filter<R>;
+    gt<K extends Col<R>>(column: K, value: NonNullable<R[K]>): Filter<R>;
+    gte<K extends Col<R>>(column: K, value: NonNullable<R[K]>): Filter<R>;
+    lt<K extends Col<R>>(column: K, value: NonNullable<R[K]>): Filter<R>;
+    lte<K extends Col<R>>(column: K, value: NonNullable<R[K]>): Filter<R>;
+    like(column: Col<R>, pattern: string): Filter<R>;
+    ilike(column: Col<R>, pattern: string): Filter<R>;
+    in<K extends Col<R>>(column: K, values: readonly NonNullable<R[K]>[]): Filter<R>;
+    is(column: Col<R>, value: null | boolean): Filter<R>;
+    contains(column: Col<R>, value: unknown): Filter<R>;
+    overlaps(column: Col<R>, value: unknown): Filter<R>;
+    textSearch(column: Col<R>, query: string, opts?: {
+        type?: "plain" | "phrase" | "websearch";
+        config?: string;
+    }): Filter<R>;
+    /** PostgREST's raw `or` grammar (`"pinned.eq.true,starred.eq.true"`). */
+    or(filters: string, opts?: {
+        referencedTable?: string;
+    }): Filter<R>;
+    not(column: Col<R>, operator: string, value: unknown): Filter<R>;
+}
+/** A filter callback — the same builder `readAllRows` callers write today, typed to the row. */
+type Where<R = any> = (q: Filter<R>) => Filter<R>;
+interface ReadOptions<C> {
+    /** Only these columns (the result is typed to them). Default every column. */
+    columns?: readonly C[];
+    /** Include soft-deleted rows (default: excluded on tables with `deleted_at`). */
+    includeDeleted?: boolean;
+}
 /** One row by primary key (a composite key takes `{ col: value }`), or null. */
-declare function read<T extends TableDescriptor<any, any, any>>(db: Db, table: T, id: unknown, columns?: string): Promise<RowOf<T> | null>;
-/** A filter callback — the same builder `readAllRows` callers write today (`q => q.or(…).gte(…)`). */
-type Where = (q: any) => any;
-/** EVERY matching row, paged past the 1,000-row cap; throws on a short read. */
-declare function listAll<T extends TableDescriptor<any, any, any>>(db: Db, table: T, where?: Where, opts?: {
-    columns?: string;
-    orderBy?: string;
+declare function read<R, I, U, C extends Col<R> = Col<R>>(db: Db, table: TableDescriptor<R, I, U>, id: unknown, opts?: ReadOptions<C>): Promise<Pick<R, C> | null>;
+/** EVERY matching row, paged past the 1,000-row cap (ordered by the full key); throws on a short read. */
+declare function listAll<R, I, U, C extends Col<R> = Col<R>>(db: Db, table: TableDescriptor<R, I, U>, where?: Where<R>, opts?: ReadOptions<C> & {
+    orderBy?: Col<R>;
     pageSize?: number;
     maxRows?: number;
-}): Promise<RowOf<T>[]>;
+}): Promise<Pick<R, C>[]>;
 /** One explicit window (`from`..`to`, inclusive) plus the exact total. */
-declare function page<T extends TableDescriptor<any, any, any>>(db: Db, table: T, window: {
+declare function page<R, I, U, C extends Col<R> = Col<R>>(db: Db, table: TableDescriptor<R, I, U>, window: ReadOptions<C> & {
     from: number;
     to: number;
-    where?: Where;
-    columns?: string;
-    orderBy?: string;
+    where?: Where<R>;
+    orderBy?: Col<R>;
     ascending?: boolean;
 }): Promise<{
-    rows: RowOf<T>[];
+    rows: Pick<R, C>[];
     total: number | null;
 }>;
 /** The exact count of matching rows (no rows transferred). */
-declare function count<T extends TableDescriptor<any, any, any>>(db: Db, table: T, where?: Where): Promise<number>;
+declare function count<R, I, U>(db: Db, table: TableDescriptor<R, I, U>, where?: Where<R>, opts?: {
+    includeDeleted?: boolean;
+}): Promise<number>;
 /** Insert one row (or many) and return what the database stored. */
-declare function insert<T extends TableDescriptor<any, any, any>>(db: Db, table: T, values: InsertOf<T>): Promise<RowOf<T>>;
-declare function insert<T extends TableDescriptor<any, any, any>>(db: Db, table: T, values: InsertOf<T>[]): Promise<RowOf<T>[]>;
+declare function insert<R, I, U>(db: Db, table: TableDescriptor<R, I, U>, values: I): Promise<R>;
+declare function insert<R, I, U>(db: Db, table: TableDescriptor<R, I, U>, values: readonly I[]): Promise<R[]>;
+/** Every write on a versioned table is explicit: `{ expectedVersion }` (guarded) or `{ overwrite: true }`. */
 type UpdateGuard = {
     expectedVersion: number;
 } | {
     overwrite: true;
 };
+type WriteResult<R> = {
+    status: "saved";
+    row: R;
+    rebasedFrom?: {
+        expectedVersion: number;
+        currentVersion: number;
+    };
+} | {
+    status: "conflict";
+    currentRow: R;
+    currentVersion: number;
+} | {
+    status: "not_found";
+};
 /**
  * Update one row by primary key. On a versioned table the guard is required:
  * `{ expectedVersion }` (a conflict comes back, never a silent overwrite) or
- * `{ overwrite: true }`.
+ * `{ overwrite: true }`; on an unversioned table `expectedVersion` is refused.
  */
-declare function update<T extends TableDescriptor<any, any, any>>(db: Db, table: T, id: unknown, patch: UpdateOf<T>, guard?: UpdateGuard): Promise<GuardedUpdateResult<RowOf<T> & {
-    version: number;
-}> | {
-    status: "saved";
-    row: RowOf<T>;
-} | {
-    status: "not_found";
-}>;
+declare function update<R, I, U>(db: Db, table: TableDescriptor<R, I, U>, id: unknown, patch: U, guard?: UpdateGuard): Promise<WriteResult<R>>;
 /**
  * Remove one row the way the table removes: soft delete (`deleted_at`) where it
  * has one; an archive-only table refuses (use `archive`); a hard delete only where
- * the table has neither.
+ * the table has neither. Guarded like `update` on a versioned table.
  */
-declare function remove<T extends TableDescriptor<any, any, any>>(db: Db, table: T, id: unknown): Promise<"soft_deleted" | "deleted" | "not_found">;
-/** Archive (or, with `restore`, bring back) one row by the table's archive column. */
-declare function archive<T extends TableDescriptor<any, any, any>>(db: Db, table: T, id: unknown, opts?: {
+declare function remove<R, I, U>(db: Db, table: TableDescriptor<R, I, U>, id: unknown, guard?: UpdateGuard): Promise<{
+    status: "soft_deleted" | "deleted" | "not_found";
+} | {
+    status: "conflict";
+    currentVersion: number;
+}>;
+/** Archive (or, with `restore`, bring back) one row by the table's archive column. Guarded like `update`. */
+declare function archive<R, I, U>(db: Db, table: TableDescriptor<R, I, U>, id: unknown, opts?: {
     restore?: boolean;
-}): Promise<RowOf<T> | null>;
+    guard?: UpdateGuard;
+}): Promise<WriteResult<R>>;
 /** Bring back an archived or soft-deleted row. */
-declare const restore: <T extends TableDescriptor<any, any, any>>(db: Db, table: T, id: unknown) => Promise<RowOf<T> | null>;
+declare const restore: <R, I, U>(db: Db, table: TableDescriptor<R, I, U>, id: unknown, guard?: UpdateGuard) => Promise<WriteResult<R>>;
 /** Call a database function through its generated door (PostgREST chooses an overload by argument names). */
 declare function call<F extends FunctionDescriptor<any, any>>(db: Db, fn: F, args: ArgsOf<F>): Promise<ResultOf<F>>;
-/** The compact flags index `matrx-data generate --flags-index` writes: "schema.table" → descriptor. */
+/** One schema's flags (`<schema>.flags.ts` from `matrx-data generate --flags-index`): "schema.table" → descriptor. */
 type FlagsIndex = Readonly<Record<string, TableDescriptor>>;
+/** Per-schema loaders (`flags-index.ts`): only the schema a runtime name names is loaded (pay-only). */
+type FlagLoaders = Readonly<Record<string, () => Promise<FlagsIndex>>>;
 /** The door for a table whose name arrives at runtime — loosely typed, the same rules. */
 declare function tableByName(index: FlagsIndex, name: string): TableDescriptor;
+/** `tableByName` over per-schema loaders: loads only the named schema's flags. */
+declare function loadTableByName(loaders: FlagLoaders, name: string): Promise<TableDescriptor>;
 /** The `postgres_changes` filter for a table — only published tables have one (an unpublished table delivers nothing). */
 declare function changesOf(table: TableDescriptor<any, any, any>): {
     schema: string;
     table: string;
 };
 
-export { type ActiveOrgCookie, type ActiveOrgCookieOptions, type ActiveOrgSelection, type ArgsOf, type AuthRetryableResult, BulkWriteError, type CreateActiveOrgCookieArgs, type CreateDbOptions, type CreateOAuthRefreshFetchArgs, type CreateSessionRetryOptions, DEFAULT_ACTIVE_ORG_COOKIE_MAX_AGE, DEFAULT_ACTIVE_ORG_COOKIE_NAME, DatabaseError, type Db, DoorRefusedError, type FlagsIndex, type FunctionDescriptor, type GuardedUpdateArgs, type GuardedUpdateResult, IncompleteReadError, type InsertOf, type JsonObject, type MergeJsonColumnArgs, type MergeJsonColumnResult, type OAuthRefreshStorage, type OrgRule, type PagedReadQuery, type PagedReadResult, type QueryLike, type ReadAllRowsOptions, type ReadAllRowsRestOptions, RecordUnavailableError, type RecordUnavailableReason, type RecordUnavailableResolution, type ResultOf, type RowOf, type SessionSource, SessionUnavailableError, type SupabaseLike, type TableDescriptor, type TableType, type TryWriteOneResult, type UpdateGuard, type UpdateOf, type UserCredentialsPort, type VersionedRow, type Where, WriteDidNotLandError, type WriteDidNotLandReason, type WriteFailureWords, type WriteOneAction, type WriteOneOptions, type WriteOneRowResult, WriteRefusedError, archive, asJsonObject, assertDoor, assertWriteLanded, call, changesOf, count, createActiveOrgCookie, createDb, createOAuthRefreshFetch, createServiceDb, createSessionRetry, decodeActiveOrgSelection, decodeOAuthRefreshClaims, describeWriteFailure, encodeActiveOrgSelection, guardedUpdate, insert, isMissingSessionError, isRecordUnavailableError, listAll, mergeJsonColumn, page, personSentence, read, readAllRows, readAllRowsRest, recordUnavailableMessage, remove, restore, serverMessageFromBody, tableByName, tryReadAllRows, tryReadAllRowsRest, tryWriteOne, update, writeFailureStatus, writeOne, writeOneRow };
+export { type ActiveOrgCookie, type ActiveOrgCookieOptions, type ActiveOrgSelection, type ArgsOf, type AuthRetryableResult, BulkWriteError, type CreateActiveOrgCookieArgs, type CreateDbOptions, type CreateOAuthRefreshFetchArgs, type CreateSessionRetryOptions, DEFAULT_ACTIVE_ORG_COOKIE_MAX_AGE, DEFAULT_ACTIVE_ORG_COOKIE_NAME, DatabaseError, type Db, DoorRefusedError, type Filter, type FlagLoaders, type FlagsIndex, type FunctionDescriptor, type GuardedUpdateArgs, type GuardedUpdateResult, IncompleteReadError, type InsertOf, type JsonObject, type MergeJsonColumnArgs, type MergeJsonColumnResult, type OAuthRefreshStorage, type OrgRule, type PagedReadQuery, type PagedReadResult, type QueryLike, type ReadAllRowsOptions, type ReadAllRowsRestOptions, type ReadOptions, RecordUnavailableError, type RecordUnavailableReason, type RecordUnavailableResolution, type ResultOf, type RowOf, type SessionSource, SessionUnavailableError, type SupabaseLike, type TableDescriptor, type TableType, type TryWriteOneResult, type UpdateGuard, type UpdateOf, type UserCredentialsPort, type VersionedRow, type Where, WriteDidNotLandError, type WriteDidNotLandReason, type WriteFailureWords, type WriteOneAction, type WriteOneOptions, type WriteOneRowResult, WriteRefusedError, type WriteResult, archive, asJsonObject, assertDoor, assertWriteLanded, call, changesOf, count, createActiveOrgCookie, createDb, createOAuthRefreshFetch, createServiceDb, createSessionRetry, decodeActiveOrgSelection, decodeOAuthRefreshClaims, describeWriteFailure, encodeActiveOrgSelection, guardedUpdate, insert, isMissingSessionError, isRecordUnavailableError, listAll, loadTableByName, mergeJsonColumn, page, personSentence, read, readAllRows, readAllRowsRest, recordUnavailableMessage, remove, restore, serverMessageFromBody, tableByName, tryReadAllRows, tryReadAllRowsRest, tryWriteOne, update, writeFailureStatus, writeOne, writeOneRow };

package/dist/db.js

@@ -976,18 +976,29 @@ function byPk(q, t, id) {
   const key = id;
   return t.pk.reduce((acc, col) => acc.eq(col, key[col]), q);
 }
-async function read(db, table, id, columns = "*") {
+var selectOf = (columns) => columns && columns.length ? columns.join(",") : "*";
+function live(q, table, includeDeleted) {
+  return table.softDelete && !includeDeleted ? q.is("deleted_at", null) : q;
+}
+function ordered(q, table, orderBy, ascending = true) {
+  const cols = orderBy ? [orderBy, ...table.pk.filter((c) => c !== orderBy)] : table.pk.length ? table.pk : ["id"];
+  return cols.reduce((acc, c) => acc.order(c, { ascending }), q);
+}
+async function read(db, table, id, opts = {}) {
   assertDoor(db, table, "read");
-  return check(`read ${qualified(table)}`, await byPk(from(db, table).select(columns), table, id).maybeSingle());
+  const q = live(byPk(from(db, table).select(selectOf(opts.columns)), table, id), table, opts.includeDeleted);
+  return check(`read ${qualified(table)}`, await q.maybeSingle());
 }
 async function listAll(db, table, where, opts = {}) {
   assertDoor(db, table, "read");
-  const order = opts.orderBy ?? table.pk[0] ?? "id";
   return readAllRows(
     ({ from: lo, to: hi }) => {
-      let q = from(db, table).select(opts.columns ?? "*", { count: "exact" });
+      let q = live(from(db, table).select(selectOf(opts.columns), { count: "exact" }), table, opts.includeDeleted);
       if (where) q = where(q);
-      return q.order(order, { ascending: true }).range(lo, hi);
+      return Promise.resolve(ordered(q, table, opts.orderBy).range(lo, hi)).then((res) => {
+        if (res.error) throw new DatabaseError(`listAll ${qualified(table)}`, res.error);
+        return res;
+      });
     },
     {
       label: `listAll ${qualified(table)}`,
@@ -998,14 +1009,14 @@ async function listAll(db, table, where, opts = {}) {
 }
 async function page(db, table, window2) {
   assertDoor(db, table, "read");
-  let q = from(db, table).select(window2.columns ?? "*", { count: "exact" });
+  let q = live(from(db, table).select(selectOf(window2.columns), { count: "exact" }), table, window2.includeDeleted);
   if (window2.where) q = window2.where(q);
-  const res = await q.order(window2.orderBy ?? table.pk[0] ?? "id", { ascending: window2.ascending ?? true }).range(window2.from, window2.to);
+  const res = await ordered(q, table, window2.orderBy, window2.ascending ?? true).range(window2.from, window2.to);
   return { rows: check(`page ${qualified(table)}`, res) ?? [], total: res.count ?? null };
 }
-async function count(db, table, where) {
+async function count(db, table, where, opts = {}) {
   assertDoor(db, table, "read");
-  let q = from(db, table).select("*", { count: "exact", head: true });
+  let q = live(from(db, table).select("*", { count: "exact", head: true }), table, opts.includeDeleted);
   if (where) q = where(q);
   const res = await q;
   check(`count ${qualified(table)}`, res);
@@ -1033,11 +1044,34 @@ function withOrganization(db, table, values) {
 async function insert(db, table, values) {
   assertDoor(db, table, "insert");
   const many = Array.isArray(values);
-  const rows = (many ? values : [values]).map((v) => withOrganization(db, table, v));
+  let rows = (many ? values : [values]).map((v) => withOrganization(db, table, v));
+  if (table.createdBy && db.role === "user" && rows.some((r) => r.created_by == null) && db.client.auth) {
+    const { data } = await db.client.auth.getSession();
+    const person = data.session?.user?.id;
+    if (person) rows = rows.map((r) => r.created_by == null ? { ...r, created_by: person } : r);
+  }
   const res = await from(db, table).insert(rows).select("*");
   const stored = check(`insert ${qualified(table)}`, res);
   return many ? stored : stored[0];
 }
+async function writeRow(db, table, id, values, door, guard) {
+  const expected = guard && "expectedVersion" in guard ? guard.expectedVersion : void 0;
+  if (expected !== void 0 && !table.versioned) {
+    throw new DoorRefusedError(door, "expectedVersion on a table that is not versioned \u2014 nothing would guard it; pass no guard");
+  }
+  if (table.versioned && expected === void 0 && !(guard && "overwrite" in guard && guard.overwrite)) {
+    throw new DoorRefusedError(door, "a versioned table takes { expectedVersion } or { overwrite: true }");
+  }
+  if (expected !== void 0) {
+    return await guardedUpdate({
+      expectedVersion: expected,
+      applyUpdate: ({ expectedVersion, nextVersion }) => byPk(from(db, table).update({ ...values, version: nextVersion }), table, id).eq("version", expectedVersion).select("*").maybeSingle(),
+      fetchCurrent: () => byPk(from(db, table).select("*"), table, id).maybeSingle()
+    });
+  }
+  const row = check(door, await byPk(from(db, table).update(values), table, id).select("*").maybeSingle());
+  return row ? { status: "saved", row } : { status: "not_found" };
+}
 async function update(db, table, id, patch, guard) {
   assertDoor(db, table, "update");
   const door = `update ${qualified(table)}`;
@@ -1046,29 +1080,30 @@ async function update(db, table, id, patch, guard) {
     const blocked = table.readOnlyColumns.filter((c) => c in values);
     if (blocked.length) throw new DoorRefusedError(door, `read-only to clients: ${blocked.join(", ")}`);
   }
-  if (table.versioned && guard && "expectedVersion" in guard) {
-    return guardedUpdate({
-      expectedVersion: guard.expectedVersion,
-      applyUpdate: ({ expectedVersion, nextVersion }) => byPk(from(db, table).update({ ...values, version: nextVersion }), table, id).eq("version", expectedVersion).select("*").maybeSingle(),
-      fetchCurrent: () => byPk(from(db, table).select("*"), table, id).maybeSingle()
-    });
-  }
-  if (table.versioned && !(guard && "overwrite" in guard && guard.overwrite)) {
-    throw new DoorRefusedError(door, "a versioned table takes { expectedVersion } or { overwrite: true }");
-  }
-  const row = check(door, await byPk(from(db, table).update(values), table, id).select("*").maybeSingle());
-  return row ? { status: "saved", row } : { status: "not_found" };
+  return writeRow(db, table, id, values, door, guard);
 }
-async function remove(db, table, id) {
+async function remove(db, table, id, guard) {
   assertDoor(db, table, "remove");
   const door = `remove ${qualified(table)}`;
   if (table.softDelete) {
-    const row = check(door, await byPk(from(db, table).update({ deleted_at: (/* @__PURE__ */ new Date()).toISOString() }), table, id).select("*").maybeSingle());
-    return row ? "soft_deleted" : "not_found";
+    const res = await writeRow(db, table, id, { deleted_at: (/* @__PURE__ */ new Date()).toISOString() }, door, guard);
+    return res.status === "saved" ? { status: "soft_deleted" } : res.status === "conflict" ? { status: "conflict", currentVersion: res.currentVersion } : res;
   }
   if (table.archive) throw new DoorRefusedError(door, "this table archives instead of deleting \u2014 use archive()");
-  const rows = check(door, await byPk(from(db, table).delete(), table, id).select("*"));
-  return rows && rows.length ? "deleted" : "not_found";
+  const expected = guard && "expectedVersion" in guard ? guard.expectedVersion : void 0;
+  if (expected !== void 0 && !table.versioned) throw new DoorRefusedError(door, "expectedVersion on a table that is not versioned");
+  if (table.versioned && expected === void 0 && !(guard && "overwrite" in guard)) {
+    throw new DoorRefusedError(door, "a versioned table takes { expectedVersion } or { overwrite: true }");
+  }
+  let q = byPk(from(db, table).delete(), table, id);
+  if (expected !== void 0) q = q.eq("version", expected);
+  const rows = check(door, await q.select("*"));
+  if (rows && rows.length) return { status: "deleted" };
+  if (expected !== void 0) {
+    const current = check(door, await byPk(from(db, table).select("version"), table, id).maybeSingle());
+    if (current) return { status: "conflict", currentVersion: current.version };
+  }
+  return { status: "not_found" };
 }
 async function archive(db, table, id, opts = {}) {
   assertDoor(db, table, "archive");
@@ -1078,9 +1113,9 @@ async function archive(db, table, id, opts = {}) {
   else if (table.archive === "is_archived") values = { is_archived: !opts.restore };
   else if (table.softDelete && opts.restore) values = { deleted_at: null };
   else throw new DoorRefusedError(door, "the table has no archive column");
-  return check(door, await byPk(from(db, table).update(values), table, id).select("*").maybeSingle());
+  return writeRow(db, table, id, values, door, opts.guard);
 }
-var restore = (db, table, id) => archive(db, table, id, { restore: true });
+var restore = (db, table, id, guard) => archive(db, table, id, guard ? { restore: true, guard } : { restore: true });
 async function call(db, fn, args) {
   const door = `call ${fn.schema}.${fn.name}`;
   const role = db.role === "service" ? "service_role" : "authenticated";
@@ -1094,6 +1129,12 @@ function tableByName(index, name) {
   if (!t) throw new DoorRefusedError(`tableByName ${name}`, "no such table in the database description (schema-qualify it: schema.table)");
   return t;
 }
+async function loadTableByName(loaders, name) {
+  const schema = name.slice(0, name.indexOf("."));
+  const load = schema ? loaders[schema] : void 0;
+  if (!load) throw new DoorRefusedError(`tableByName ${name}`, "no such schema in the database description (schema-qualify it: schema.table)");
+  return tableByName(await load(), name);
+}
 function changesOf(table) {
   if (!table.realtime) throw new DoorRefusedError(`changesOf ${qualified(table)}`, "the table is not in the supabase_realtime publication");
   return { schema: table.schema, table: table.name };
@@ -1132,6 +1173,7 @@ export {
   isMissingSessionError,
   isRecordUnavailableError,
   listAll,
+  loadTableByName,
   mergeJsonColumn,
   page,
   parseCookieHeader,