@ai-matrx/data 0.25.0 → 0.26.0

package/dist/db.d.cts

@@ -902,7 +902,9 @@ interface QueryLike extends PromiseLike<Resp<any>> {
 interface SupabaseLike {
     schema(name: string): {
         from(table: string): QueryLike;
-        rpc(fn: string, args?: Record<string, unknown>): PromiseLike<Resp<any>>;
+        rpc(fn: string, args?: Record<string, unknown>, opts?: {
+            count?: "exact" | "planned" | "estimated";
+        }): PromiseLike<Resp<any>>;
     };
     auth?: {
         getSession(): Promise<{
@@ -1073,6 +1075,22 @@ declare function archive<R, I, U>(db: Db, table: TableDescriptor<R, I, U>, id: u
 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>>;
+/** One ordering column of a set-returning function's rows (PostgREST `order`). */
+type CallOrder = string | {
+    column: string;
+    ascending?: boolean;
+    nullsFirst?: boolean;
+};
+/**
+ * EVERY row a set-returning function answers, paged past the 1,000-row cap by
+ * `range` over a stable `order` (name enough columns to make it total — end on a key);
+ * throws a `DatabaseError` with the database's own error, or `IncompleteReadError` on a short read.
+ */
+declare function callAll<F extends FunctionDescriptor<any, any>>(db: Db, fn: F, args: ArgsOf<F>, opts: {
+    order: readonly CallOrder[];
+    pageSize?: number;
+    maxRows?: number;
+}): Promise<ResultOf<F> extends readonly (infer Row)[] ? Row[] : ResultOf<F>[]>;
 /** 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). */
@@ -1087,4 +1105,4 @@ declare function changesOf(table: TableDescriptor<any, any, any>): {
     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 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 };
+export { type ActiveOrgCookie, type ActiveOrgCookieOptions, type ActiveOrgSelection, type ArgsOf, type AuthRetryableResult, BulkWriteError, type CallOrder, 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, callAll, 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

@@ -902,7 +902,9 @@ interface QueryLike extends PromiseLike<Resp<any>> {
 interface SupabaseLike {
     schema(name: string): {
         from(table: string): QueryLike;
-        rpc(fn: string, args?: Record<string, unknown>): PromiseLike<Resp<any>>;
+        rpc(fn: string, args?: Record<string, unknown>, opts?: {
+            count?: "exact" | "planned" | "estimated";
+        }): PromiseLike<Resp<any>>;
     };
     auth?: {
         getSession(): Promise<{
@@ -1073,6 +1075,22 @@ declare function archive<R, I, U>(db: Db, table: TableDescriptor<R, I, U>, id: u
 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>>;
+/** One ordering column of a set-returning function's rows (PostgREST `order`). */
+type CallOrder = string | {
+    column: string;
+    ascending?: boolean;
+    nullsFirst?: boolean;
+};
+/**
+ * EVERY row a set-returning function answers, paged past the 1,000-row cap by
+ * `range` over a stable `order` (name enough columns to make it total — end on a key);
+ * throws a `DatabaseError` with the database's own error, or `IncompleteReadError` on a short read.
+ */
+declare function callAll<F extends FunctionDescriptor<any, any>>(db: Db, fn: F, args: ArgsOf<F>, opts: {
+    order: readonly CallOrder[];
+    pageSize?: number;
+    maxRows?: number;
+}): Promise<ResultOf<F> extends readonly (infer Row)[] ? Row[] : ResultOf<F>[]>;
 /** 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). */
@@ -1087,4 +1105,4 @@ declare function changesOf(table: TableDescriptor<any, any, any>): {
     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 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 };
+export { type ActiveOrgCookie, type ActiveOrgCookieOptions, type ActiveOrgSelection, type ArgsOf, type AuthRetryableResult, BulkWriteError, type CallOrder, 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, callAll, 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

@@ -1124,6 +1124,27 @@ async function call(db, fn, args) {
   }
   return check(door, await db.client.schema(fn.schema).rpc(fn.name, args));
 }
+async function callAll(db, fn, args, opts) {
+  const door = `callAll ${fn.schema}.${fn.name}`;
+  const role = db.role === "service" ? "service_role" : "authenticated";
+  if (!fn.roles.includes(role) && !(role === "authenticated" && fn.roles.includes("anon"))) {
+    throw new DoorRefusedError(door, `not executable by ${role} (executable by: ${fn.roles.join(", ") || "nobody"})`);
+  }
+  if (!opts.order.length) throw new DoorRefusedError(door, "a paged read needs an order (end on a key) \u2014 pages over no order can skip or repeat rows");
+  return readAllRows(
+    ({ from: lo, to: hi }) => {
+      let q = db.client.schema(fn.schema).rpc(fn.name, args, { count: "exact" });
+      for (const o of opts.order) {
+        q = typeof o === "string" ? q.order(o) : q.order(o.column, { ascending: o.ascending ?? true, ...o.nullsFirst !== void 0 ? { nullsFirst: o.nullsFirst } : {} });
+      }
+      return Promise.resolve(q.range(lo, hi)).then((res) => {
+        if (res.error) throw new DatabaseError(door, res.error);
+        return res;
+      });
+    },
+    { label: door, ...opts.pageSize !== void 0 ? { pageSize: opts.pageSize } : {}, ...opts.maxRows !== void 0 ? { maxRows: opts.maxRows } : {} }
+  );
+}
 function tableByName(index, name) {
   const t = index[name];
   if (!t) throw new DoorRefusedError(`tableByName ${name}`, "no such table in the database description (schema-qualify it: schema.table)");
@@ -1156,6 +1177,7 @@ export {
   assertDoor,
   assertWriteLanded,
   call,
+  callAll,
   changesOf,
   count,
   createActiveOrgCookie,