@mindstudio-ai/agent 0.1.162 → 0.1.164

package/dist/index.d.ts

@@ -1045,10 +1045,11 @@ type UpdateInput<T> = Partial<Omit<T, SystemFields>>;
  * returns a boolean.
  *
  * The SDK attempts to compile the predicate to a SQL WHERE clause for
- * performance. Simple expressions (field comparisons, &&/||, .includes())
- * compile to efficient SQL. If the predicate can't be compiled (function
- * calls, regex, computed expressions), the SDK falls back to fetching all
- * rows and evaluating in JS. Both paths produce identical results.
+ * performance. Simple expressions (field comparisons, &&/||, .includes(),
+ * constant right-hand sides like `db.ago(db.days(7))`) compile to efficient
+ * SQL. If the predicate can't be compiled (function calls, regex, computed
+ * fields), the SDK falls back to fetching all rows and evaluating in JS. Both
+ * paths select the same rows, NULL columns included.
  *
  * For predicates that compare to outer-scope values (e.g.
  * `o => o.companyId === input.companyId`), prefer the explicit-bindings
@@ -1180,10 +1181,10 @@ interface PredicateEntry<T> {
  *
  * ## Parameterized queries
  *
- * All builders return `{ sql, params }` tuples. Values are passed as
- * positional bind params (`?` placeholders) rather than inlined into the
- * SQL string. This is safer and works naturally with the batch endpoint
- * which accepts `{ sql, params }` per query.
+ * All builders return `{ sql, params }` tuples. Every value is a positional
+ * bind param (`?`), never inlined into the SQL string, the compiled filters'
+ * included (`predicate.ts`), so a statement's shape doesn't change with its
+ * values. Only identifiers (table and column names) are written into the SQL.
  *
  * ## RETURNING support
  *
@@ -1297,18 +1298,26 @@ interface NormalizedAggregateSpec {
  *
  * ## Execution strategy (SQL fast path vs JS fallback)
  *
- * When a Query is executed, it attempts to compile all predicates to SQL:
+ * When a Query is executed, it compiles as much of the chain to SQL as it
+ * can say exactly:
  *
- * - **Fast path**: All predicates compile → single SQL query with WHERE,
- *   ORDER BY, LIMIT, OFFSET. Efficient, minimal data transfer.
+ * - **All of it**: every predicate compiles, and the sort is a bare field
+ *   (`o => o.createdAt`) or there's none → one statement with WHERE, ORDER
+ *   BY, LIMIT, OFFSET and the selected columns.
  *
- * - **Fallback path**: Any predicate fails to compile → fetch ALL rows
- *   from the table (SELECT *), then apply the entire chain as native JS
- *   array operations (Array.filter, Array.sort, Array.slice, etc.).
- *   A warning is logged so developers can optimize if needed.
+ * - **The filter, not the sort**: the predicates compile but the sort is
+ *   computed (`o => o.a.b`, `o => o.name.toLowerCase()`) → SQL selects the
+ *   matching rows, and JS sorts, skips and takes them. A limit can't go into
+ *   SQL without its order, so all the matching rows are read.
  *
- * Both paths produce identical results. The SQL path is a transparent
- * performance optimization.
+ * - **None of it**: a predicate doesn't compile → every row is read (SELECT
+ *   *), and the chain runs as JS array operations.
+ *
+ * A warning is logged whenever JS does part of the work, so developers can
+ * optimize. All three select the same rows in the same order; JS orders as
+ * SQLite does (`compareAsSqlite`). Without a sortBy, the order is SQLite's
+ * own: unspecified, except that `reverse()` and `last()` mean the reverse of
+ * the order rows were written in (`rowid`).
  */
 
 type AggregateState<T> = {
@@ -1331,6 +1340,8 @@ declare class Query<T, TResult = T[]> implements PromiseLike<TResult> {
     private readonly _rawWhereParams;
     /** @internal See AggregateState — set by aggregate terminals. */
     private readonly _aggregate;
+    /** @internal The columns `select()` named; every column when unset. */
+    private readonly _columns;
     /** @internal Post-process transform applied after row deserialization. */
     readonly _postProcess: ((rows: T[]) => TResult) | undefined;
     constructor(config: TableConfig, options?: {
@@ -1343,6 +1354,7 @@ declare class Query<T, TResult = T[]> implements PromiseLike<TResult> {
         rawWhere?: string;
         rawWhereParams?: unknown[];
         aggregate?: AggregateState<T>;
+        columns?: string[];
     });
     private _clone;
     filter(predicate: Predicate<T>): Query<T>;
@@ -1351,6 +1363,19 @@ declare class Query<T, TResult = T[]> implements PromiseLike<TResult> {
     reverse(): Query<T>;
     take(n: number): Query<T>;
     skip(n: number): Query<T>;
+    /**
+     * Return only these columns: `SELECT id, name` rather than every column of
+     * a wide row. Chain it before a terminal (`first()`, `take()`); filters and
+     * sorts still see the whole row.
+     *
+     * ```ts
+     * const names = await Companies
+     *   .filter((c, $) => c.firmId === $.firmId, { firmId })
+     *   .select('id', 'name');
+     * // Array<{ id: string; name: string }>
+     * ```
+     */
+    select<K extends keyof T & string>(...columns: K[]): Query<Pick<T, K>>;
     first(): Query<T, T | null>;
     last(): Query<T, T | null>;
     count(): Query<T, number>;
@@ -1422,22 +1447,21 @@ declare class Query<T, TResult = T[]> implements PromiseLike<TResult> {
     max(accessor: Accessor<T, number>): Query<T, T | null>;
     groupBy<K extends string | number>(accessor: Accessor<T, K>): Query<T, Map<K, T[]>>;
     /**
-     * @internal Compile this query into a SqlQuery for batch execution.
-     *
-     * Returns the compiled SQL query (if all predicates compile to SQL),
-     * or null (if JS fallback is needed). In the fallback case, a bare
-     * `SELECT *` is returned as `fallbackQuery` so the batch can fetch
-     * all rows and this query can filter them in JS post-fetch.
+     * @internal Compile this query into the statement to run, plus whatever
+     * JS has to do with its rows (see the module header's three cases). Used by
+     * db.batch() and by a standalone await alike.
      */
     _compile(): CompiledQuery<T, TResult>;
     /**
      * @internal Process raw SQL results into typed rows. Used by db.batch()
-     * after executing the compiled query.
+     * after executing the compiled query, and by a standalone await.
      *
-     * For SQL-compiled queries: just deserialize the rows.
-     * For JS-fallback queries: filter, sort, and slice in JS.
+     * Deserializes the rows, then does in JS whatever the SQL couldn't
+     * (`inJs`): the filter, the sort, the page, the projection.
      */
     static _processResults<T, R = T[]>(result: SqlResult, compiled: CompiledQuery<T, R>): R;
+    /** @internal Say that part of a query ran in JS, and why. */
+    static _warnInJs<T, R>(compiled: CompiledQuery<T, R>, rowsRead?: number): void;
     then<TResult1 = TResult, TResult2 = never>(onfulfilled?: ((value: TResult) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null): Promise<TResult1 | TResult2>;
     private _run;
     /**
@@ -1451,33 +1475,32 @@ declare class Query<T, TResult = T[]> implements PromiseLike<TResult> {
      */
     private _compileAggregateSql;
     catch<TResult2 = never>(onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null): Promise<TResult | TResult2>;
-    private _execute;
     private _compilePredicates;
-    private _fetchAndFilterInJs;
     private _fetchAllRows;
 }
 /**
- * Result of Query._compile(). Contains either a compiled SQL query
- * (fast path) or a fallback SELECT * with JS processing metadata.
+ * Result of Query._compile(): the statement to run, and what's left to do in
+ * JS over its rows when SQL couldn't do all of it.
  */
 interface CompiledQuery<T, TResult = T[]> {
     type: 'query';
-    /** Compiled SQL query, or null if JS fallback needed. */
-    query: SqlQuery | null;
-    /** SELECT * fallback query, or null if SQL compiled. */
-    fallbackQuery: SqlQuery | null;
+    /** The statement to run. */
+    query: SqlQuery;
     /** Table config for deserialization. */
     config: TableConfig;
-    /** JS predicates (only for fallback). */
-    predicates?: PredicateEntry<T>[];
-    /** Sort accessor (only for fallback). */
-    sortAccessor?: Accessor<T>;
-    /** Sort direction (only for fallback). */
-    reversed?: boolean;
-    /** Limit (only for fallback). */
-    limit?: number;
-    /** Offset (only for fallback). */
-    offset?: number;
+    /** What JS does to the statement's rows, in order, when SQL couldn't. */
+    inJs?: {
+        /** Why, for the warning. */
+        why: string;
+        /** Filters SQL couldn't run (the statement then reads every row). */
+        predicates?: PredicateEntry<T>[];
+        sortAccessor?: Accessor<T>;
+        reversed: boolean;
+        limit?: number;
+        offset?: number;
+        /** The columns `select()` named, kept once the rest is done. */
+        columns?: string[];
+    };
     /** Post-process transform (e.g. first() extracts [0] ?? null). */
     postProcess?: (rows: T[]) => TResult;
     /** When set, the SQL result rows ARE the answer (aggregate values, not
@@ -1510,9 +1533,12 @@ interface CompiledQuery<T, TResult = T[]> {
  * ## Non-batchable mutations
  *
  * Some mutations (e.g. `removeAll` with a JS-fallback predicate) require
- * multi-step execution that can't be expressed as a fixed SQL batch.
- * These are created via `Mutation.fromExecutor()` and work fine when
- * awaited standalone, but throw if passed to `db.batch()`.
+ * multi-step execution that can't be expressed as a fixed SQL batch. A
+ * builder says so by returning null, and the mutation runs its `fallback`
+ * instead: fine when awaited standalone, but it throws if passed to
+ * `db.batch()`. Whether it can be expressed may depend on the table's
+ * columns, so it's decided when the SQL is built, not when the write method
+ * was called.
  */
 
 interface CompiledMutation<TResult> {
@@ -1524,30 +1550,20 @@ interface CompiledMutation<TResult> {
 declare class Mutation<TResult> implements PromiseLike<TResult> {
     /** @internal */
     private readonly _config;
-    /** @internal */
+    /** @internal The statements, or null when the write can't be one batch. */
     private readonly _build;
     /** @internal */
     private readonly _processResult;
-    /** @internal Non-batchable executor for complex mutations (e.g. removeAll JS fallback). */
-    private readonly _executor;
-    constructor(config: TableConfig, build: () => SqlQuery[], processResult: (results: SqlResult[]) => TResult);
-    /**
-     * Create a non-batchable mutation that wraps an async executor.
-     * Used for operations that require multi-step execution (e.g. removeAll
-     * with a JS-fallback predicate: fetch all rows → filter → delete).
-     *
-     * Works fine when awaited standalone. Throws if passed to db.batch().
-     *
-     * @internal
-     */
-    static fromExecutor<T>(config: TableConfig, executor: () => Promise<T>): Mutation<T>;
+    /** @internal What runs when `_build` returns null (e.g. removeAll's JS fallback). */
+    private readonly _fallback;
+    constructor(config: TableConfig, build: () => SqlQuery[] | null, processResult: (results: SqlResult[]) => TResult, fallback?: () => Promise<TResult>);
     then<T1 = TResult, T2 = never>(onfulfilled?: ((value: TResult) => T1 | PromiseLike<T1>) | null, onrejected?: ((reason: unknown) => T2 | PromiseLike<T2>) | null): Promise<T1 | T2>;
     catch<T2 = never>(onrejected?: ((reason: unknown) => T2 | PromiseLike<T2>) | null): Promise<TResult | T2>;
     /**
      * @internal Compile this mutation into SQL for batch execution.
      * Returns the queries and a result processor.
      *
-     * Throws if this is a non-batchable mutation (created via fromExecutor).
+     * Throws if it can't be expressed as SQL (its builder returned null).
      */
     _compile(): CompiledMutation<TResult>;
     /**
@@ -1639,6 +1655,8 @@ declare class Table<T> {
     filter<B extends PredicateBindings>(predicate: (row: T, bindings: B) => boolean, bindings: B): Query<T>;
     /** Sort rows by a field. Returns a chainable Query. */
     sortBy(accessor: Accessor<T>): Query<T>;
+    /** Every row, with only these columns. See Query.select(). */
+    select<K extends keyof T & string>(...columns: K[]): Query<Pick<T, K>>;
     /**
      * Insert one or more rows. Returns the created row(s) with system fields
      * populated (id, createdAt, updatedAt, lastUpdatedBy).
@@ -4945,15 +4963,21 @@ declare class MindStudioAgent$1 {
      * can't drift between them.
      */
     private _brokeredRequest;
+    /** @internal Reads started together share a round trip (`db/readBatching.ts`). */
+    private readonly _dbReads;
     /**
      * @internal Execute a batch of SQL queries against a managed database.
-     * Used as the `executeBatch` callback for Table/Query instances.
-     *
-     * Calls `POST /_internal/v2/db/query` directly with the hook token
-     * (raw, no Bearer prefix). All queries run on a single SQLite connection,
-     * enabling RETURNING clauses and multi-statement batches.
+     * Used as the `executeBatch` callback for Table/Query instances. Reads one
+     * request starts in the same tick go to the platform as one batch.
      */
     private _executeDbBatch;
+    /**
+     * @internal Send one batch: `POST /_internal/v2/db/query` directly with the
+     * hook token (raw, no Bearer prefix), or its DB WebSocket. All queries run
+     * on a single SQLite connection, enabling RETURNING clauses and
+     * multi-statement batches.
+     */
+    private _sendDbBatch;
     /**
      * @internal Sync a user's roles to the platform after a successful
      * auth table write. Calls POST /_internal/v2/auth/sync-user.