@taylordb/query-builder 0.16.3 → 0.17.0

package/docs/conditions.md

@@ -0,0 +1,111 @@
+# Conditions (Filtering)
+
+Use `.where()` and `.orWhere()` to filter records. Both methods are available on `selectFrom`, `update`, `deleteFrom`, and aggregation queries.
+
+## Simple condition
+
+```ts
+.where(field, operator, value)
+```
+
+```ts
+const users = await qb
+  .selectFrom('users')
+  .select(['id', 'name'])
+  .where('age', '>', 30)
+  .execute();
+```
+
+The available operators and their accepted value types depend on the column type — see [field-types.md](./field-types.md) for the full operator table per type.
+
+## Multiple AND conditions
+
+Chaining `.where()` adds each condition with AND logic.
+
+```ts
+const users = await qb
+  .selectFrom('users')
+  .selectAll()
+  .where('age', '>', 18)
+  .where('role', '=', 'admin')
+  .execute();
+// age > 18 AND role = 'admin'
+```
+
+## OR conditions
+
+`.orWhere()` has the same signature as `.where()` but switches the conjunction to OR for all conditions in the current group.
+
+```ts
+const users = await qb
+  .selectFrom('users')
+  .selectAll()
+  .where('name', '=', 'Alice')
+  .orWhere('name', '=', 'Bob')
+  .execute();
+// name = 'Alice' OR name = 'Bob'
+```
+
+## Grouped conditions (nested logic)
+
+Pass a callback to `.where()` to create a nested group. The callback receives a fresh builder scoped to the same table and only the conditions added inside it form the group.
+
+```ts
+const users = await qb
+  .selectFrom('users')
+  .selectAll()
+  .where('status', '=', 'active')
+  .where(qb =>
+    qb
+      .where('role', '=', 'admin')
+      .orWhere('role', '=', 'editor')
+  )
+  .execute();
+// status = 'active' AND (role = 'admin' OR role = 'editor')
+```
+
+## Cross-table filtering (link fields)
+
+When filtering on a link field you can pass a callback instead of a plain value. The callback receives a builder scoped to the **linked** table, letting you filter based on properties of the related records.
+
+```ts
+const users = await qb
+  .selectFrom('users')
+  .selectAll()
+  .where('posts', 'hasAnyOf', qb =>
+    qb.where('isPublished', '=', true)
+  )
+  .execute();
+// users who have at least one published post
+```
+
+The operator you choose on the link field still applies (`hasAnyOf`, `hasAllOf`, `isExactly`, `hasNoneOf`), but the value is resolved by running the inner filter against the linked table.
+
+## isEmpty / isNotEmpty
+
+For operators that take no value (`isEmpty`, `isNotEmpty`), omit the third argument or pass `undefined`.
+
+```ts
+.where('bio', 'isEmpty')
+.where('avatar', 'isNotEmpty')
+```
+
+## Checkbox fields
+
+Checkbox filters use numeric values — `1` for true, `0` for false.
+
+```ts
+.where('isVerified', '=', 1)
+```
+
+## Date shorthand values
+
+Date fields accept named shorthands in addition to exact values.
+
+```ts
+.where('createdAt', '=', 'today')
+.where('dueDate', '<', ['daysFromNow', 7])
+.where('updatedAt', 'isWithIn', 'pastWeek')
+```
+
+See [field-types.md](./field-types.md) for the full list of date filter values.

package/docs/current-user.md

@@ -0,0 +1,50 @@
+# Current User
+
+The query builder exposes a built-in way to get the currently authenticated user's profile record.
+
+## Usage
+
+```ts
+const user = await qb.auth.getUser();
+```
+
+## Return value
+
+```ts
+{
+  id: number;
+  name: string;
+  email: string;
+  avatar: string;
+} | null
+```
+
+Returns `null` when no matching collaborator record is found.
+
+## How it works
+
+`getUser()` pulls the user ID from the active WebSocket/HTTP connection, then looks up that ID in the `bambooCollaborators` internal table using a filter on `externalId`. Only active collaborators (those with `status = 'ACTIVE'`) are considered.
+
+## Requirement
+
+Authentication must have been established at the connection level — i.e. the `apiKey` provided to `createQueryBuilder` must be a valid user token, not just a public API key. If the connection has no user ID attached, `getUser()` throws:
+
+```
+Error: User ID not available from the connection
+```
+
+## Example
+
+```ts
+const qb = createQueryBuilder<TaylorDatabase>({
+  baseUrl: 'https://your-instance.taylordb.ai',
+  baseId: 'your-base-id',
+  apiKey: 'user-bearer-token',
+});
+
+const me = await qb.auth.getUser();
+
+if (me) {
+  console.log(`Hello ${me.name} (${me.email})`);
+}
+```

package/docs/field-types.md

@@ -0,0 +1,215 @@
+# Field Types
+
+Every column in a TaylorDB table is represented by a strongly-typed column type. These types encode what value you can write on insert/update, what value you read back on select, and which filter operators are valid for that field.
+
+## Column type anatomy
+
+```ts
+ColumnType<Select, Update, Insert, IsRequired, Filters, Aggregations>
+```
+
+| Slot | Meaning |
+|------|---------|
+| `Select` (`raw`) | The TypeScript type you receive when you read the field |
+| `Update` | The type accepted by `.set({ field: value })` |
+| `Insert` | The type accepted by `.values({ field: value })` |
+| `IsRequired` | `true` — field must be provided on insert; `false` — optional |
+| `Filters` | The operators available in `.where(field, operator, value)` |
+| `Aggregations` | The aggregation functions available for this field |
+
+---
+
+## Text — `TextColumnType<IsRequired>`
+
+Maps to field types: `singleLineText`, `text`, `longText`, `url`, `email`, `phoneNumber`, `json`.
+
+- **Select / Insert / Update**: `string`
+
+**Available filter operators**
+
+| Operator | Value type |
+|----------|-----------|
+| `=` | `string` |
+| `!=` | `string` |
+| `caseEqual` | `string` |
+| `contains` | `string` |
+| `doesNotContain` | `string` |
+| `startsWith` | `string` |
+| `endsWith` | `string` |
+| `hasAnyOf` | `string[]` |
+| `isEmpty` | _(no value)_ |
+| `isNotEmpty` | _(no value)_ |
+
+---
+
+## Number — `NumberColumnType<IsRequired>`
+
+Maps to field types: `number`, `currency`, `percent`, `duration`, `serial`, `decimalSerial`, `position`.
+
+- **Select / Insert / Update**: `number`
+
+**Available filter operators**
+
+| Operator | Value type |
+|----------|-----------|
+| `=` | `number` |
+| `!=` | `number` |
+| `>` | `number` |
+| `>=` | `number` |
+| `<` | `number` |
+| `<=` | `number` |
+| `hasAnyOf` | `number[]` |
+| `hasNoneOf` | `number[]` |
+| `isEmpty` | _(no value)_ |
+| `isNotEmpty` | _(no value)_ |
+
+**Available aggregations**: `sum`, `average`, `median`, `min`, `max`, `range`, `standardDeviation`, `histogram`, `empty`, `filled`, `unique`, `percentEmpty`, `percentFilled`, `percentUnique`
+
+---
+
+## Auto-generated number — `AutoGeneratedNumberColumnType`
+
+Maps to field type: `autoNumber`, system field `id`.
+
+- **Select**: `number`
+- **Insert / Update**: `never` — cannot be written
+
+Same filter operators and aggregations as `NumberColumnType`.
+
+---
+
+## Checkbox — `CheckboxColumnType<IsRequired>`
+
+- **Select / Insert / Update**: `boolean`
+
+**Available filter operators**
+
+| Operator | Value type |
+|----------|-----------|
+| `=` | `number` (use `1` for true, `0` for false) |
+
+---
+
+## Date — `DateColumnType<IsRequired>`
+
+- **Select / Insert / Update**: `string` (ISO 8601 date string)
+
+**Available filter operators**
+
+| Operator | Value type |
+|----------|-----------|
+| `=` | `DefaultDateFilterValue` |
+| `!=` | `DefaultDateFilterValue` |
+| `<` | `DefaultDateFilterValue` |
+| `>` | `DefaultDateFilterValue` |
+| `<=` | `DefaultDateFilterValue` |
+| `>=` | `DefaultDateFilterValue` |
+| `isWithIn` | `IsWithinOperatorValue` or `{ value: 'daysAgo' \| 'daysFromNow'; date: number }` |
+| `isEmpty` | _(no value)_ |
+| `isNotEmpty` | _(no value)_ |
+
+`DefaultDateFilterValue` can be one of:
+- A named shorthand string: `'today'`, `'tomorrow'`, `'yesterday'`, `'oneWeekAgo'`, `'oneWeekFromNow'`, `'oneMonthAgo'`, `'oneMonthFromNow'`
+- A tuple `['exactDay' | 'exactTimestamp', string]` — pass an ISO date string as the second element
+- A tuple `['daysAgo' | 'daysFromNow', number]`
+
+`IsWithinOperatorValue`: `'pastWeek'`, `'pastMonth'`, `'pastYear'`, `'nextWeek'`, `'nextMonth'`, `'nextYear'`, `'daysFromNow'`, `'daysAgo'`, `'currentWeek'`, `'currentMonth'`, `'currentYear'`
+
+**Available aggregations**: `empty`, `filled`, `unique`, `percentEmpty`, `percentFilled`, `percentUnique`, `min`, `max`, `daysRange`, `monthRange`
+
+---
+
+## Auto-generated date — `AutoGeneratedDateColumnType`
+
+Maps to field types: `createdAt`, `updatedAt`, `modifiedAt`.
+
+- **Select**: `string`
+- **Insert / Update**: `never` — cannot be written
+
+Same filter operators and aggregations as `DateColumnType`.
+
+---
+
+## Single select — `SingleSelectColumnType<Options, IsRequired>`
+
+- **Select / Insert / Update**: `Options[number]` — one of the allowed string values
+- `Options` is the `typeof YourTableFieldOptions` const generated by the CLI
+
+**Available filter operators**
+
+| Operator | Value type |
+|----------|-----------|
+| `=` | `Options[number]` |
+| `hasAnyOf` | `Options[number][]` |
+| `hasAllOf` | `Options[number][]` |
+| `isExactly` | `Options[number][]` |
+| `hasNoneOf` | `Options[number][]` |
+| `contains` | `string` |
+| `doesNotContain` | `string` |
+| `isEmpty` | _(no value)_ |
+| `isNotEmpty` | _(no value)_ |
+
+---
+
+## Multi select — `MultiSelectColumnType<Options, IsRequired>`
+
+- **Select / Insert / Update**: `Options[number][]` — array of allowed string values
+
+Same filter operators as `SingleSelectColumnType`.
+
+---
+
+## Link — `LinkColumnType<LinkedTable, IsRequired>`
+
+Represents a relationship to another table.
+
+- **Select**: `object` (resolved through `.with()`)
+- **Insert**: `number[]` — array of IDs to link
+- **Update**: `number[] | { newIds: number[]; deletedIds: number[] }`
+
+**Available filter operators**
+
+| Operator | Value type |
+|----------|-----------|
+| `=` | `number` |
+| `hasAnyOf` | `number[]` |
+| `hasAllOf` | `number[]` |
+| `isExactly` | `number[]` |
+| `hasNoneOf` | `number[]` |
+| `contains` | `string` |
+| `doesNotContain` | `string` |
+| `isEmpty` | _(no value)_ |
+| `isNotEmpty` | _(no value)_ |
+
+Cross-table filtering is also supported — see [conditions.md](./conditions.md).
+
+---
+
+## Attachment — `AttachmentColumnType<IsRequired>`
+
+- **Select**: `string[]` — array of absolute URLs (automatically resolved by the query builder)
+- **Insert**: `Attachment[] | number[]`
+- **Update**: `Attachment[] | number[] | { newAttachments: Attachment[]; deletedUrls: string[] }`
+
+For how to produce `Attachment` instances, see [file-upload.md](./file-upload.md).
+
+Same filter operators as `LinkColumnType`.
+
+---
+
+## Search — `SearchColumnType`
+
+Read-only computed field.
+
+- **Select**: `string`
+- **Insert / Update**: `string`
+
+**Available filter operators**
+
+| Operator | Value type |
+|----------|-----------|
+| `search` | `string` |
+| `contains` | `string` |
+| `containsStrict` | `string` |
+| `isEmpty` | _(no value)_ |
+| `isNotEmpty` | _(no value)_ |

package/docs/file-upload.md

@@ -0,0 +1,89 @@
+# File Upload (Attachments)
+
+Attachment fields store files. The upload and the record write are two separate steps.
+
+## Step 1 — upload the files
+
+Call `qb.uploadAttachments()` with an array of `{ file, name }` objects. This sends the files to the TaylorDB media service and returns an array of `Attachment` instances.
+
+```ts
+const attachments = await qb.uploadAttachments([
+  { file: myBlob, name: 'invoice.pdf' },
+  { file: anotherBlob, name: 'receipt.png' },
+]);
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `file` | `Blob` | The file content (a browser `File` extends `Blob`) |
+| `name` | `string` | The filename including extension |
+
+Returns `Attachment[]`. Each `Attachment` object holds metadata: `collectionName`, `fileInformation`, `baseId`, `storageAdaptor`, `_id`.
+
+The upload uses your `apiKey` and `baseId` from the query builder config for authentication.
+
+## Step 2 — write the record
+
+Pass the `Attachment[]` array as the value for any `AttachmentColumnType` field. The builder automatically calls `.toColumnValue()` on each attachment to convert it to the format the API expects.
+
+```ts
+const attachments = await qb.uploadAttachments([
+  { file: invoiceBlob, name: 'invoice.pdf' },
+]);
+
+const record = await qb
+  .insertInto('expenses')
+  .values({
+    title: 'Office supplies',
+    receipt: attachments,          // AttachmentColumnType field
+  })
+  .returning(['id', 'title'])
+  .executeTakeFirst();
+```
+
+The same works for update:
+
+```ts
+const newAttachments = await qb.uploadAttachments([
+  { file: newFileBlob, name: 'updated-receipt.pdf' },
+]);
+
+await qb
+  .update('expenses')
+  .set({ receipt: newAttachments })
+  .where('id', '=', 42)
+  .execute();
+```
+
+To replace some attachments while keeping others, use the `{ newAttachments, deletedUrls }` form that `AttachmentColumnType` update accepts:
+
+```ts
+const uploadedAttachments = await qb.uploadAttachments([
+  { file: replacementBlob, name: 'replacement.jpg' },
+]);
+
+await qb
+  .update('expenses')
+  .set({
+    receipt: {
+      newAttachments: uploadedAttachments,
+      deletedUrls: ['https://media.taylordb.ai/files/something.jpg'],
+    },
+  })
+  .where('id', '=', 42)
+  .execute();
+```
+
+## Reading attachments
+
+When you select an attachment field the query builder automatically converts the raw storage path to a full absolute URL.
+
+```ts
+const record = await qb
+  .selectFrom('expenses')
+  .select(['id', 'receipt'])
+  .executeTakeFirst();
+
+// record.receipt is string[] — each entry is a full URL:
+// 'https://media.taylordb.ai/files/...'
+```

package/docs/insert.md

@@ -0,0 +1,78 @@
+# Insert
+
+Use `insertInto` to create one or more records in a table.
+
+## Basic usage
+
+```ts
+const record = await qb
+  .insertInto('users')
+  .values({ name: 'Alice', email: 'alice@example.com' })
+  .executeTakeFirst();
+// returns { id: number } by default
+```
+
+## Methods
+
+### `.values(record | record[])`
+
+Pass a single object or an array of objects. Each key must match a field name on the table. Required fields (typed as `IsRequired = true`) will cause a TypeScript error if omitted.
+
+```ts
+// single
+.values({ name: 'Alice' })
+
+// batch
+.values([{ name: 'Alice' }, { name: 'Bob' }])
+```
+
+Attachment fields expect an `Attachment[]` value. Upload first with `qb.uploadAttachments()`, then pass the returned instances directly — the builder converts them to the correct column format automatically. See [file-upload.md](./file-upload.md).
+
+Link fields expect `number[]` — the IDs of the records you want to associate.
+
+### `.returning(fields[])`
+
+Specify which fields to include in the response. Without `.returning()` only `id` is returned.
+
+```ts
+const user = await qb
+  .insertInto('users')
+  .values({ name: 'Alice' })
+  .returning(['id', 'name', 'email'])
+  .executeTakeFirst();
+// user: { id: number; name: string; email: string }
+```
+
+Only non-link fields can be passed to `.returning()`. To include related records, use an `UpdateQueryBuilder` after the insert.
+
+### `.execute()`
+
+Runs the insert and returns an array of records matching the `.returning()` selection.
+
+```ts
+const users = await qb
+  .insertInto('users')
+  .values([{ name: 'Alice' }, { name: 'Bob' }])
+  .returning(['id', 'name'])
+  .execute();
+// users: Array<{ id: number; name: string }>
+```
+
+### `.executeTakeFirst()`
+
+Same as `.execute()` but returns the first result or `null`.
+
+```ts
+const user = await qb
+  .insertInto('users')
+  .values({ name: 'Alice' })
+  .returning(['id', 'name'])
+  .executeTakeFirst();
+// user: { id: number; name: string } | null
+```
+
+## Restrictions
+
+- `attachmentTable` and `collaborators` are blacklisted and cannot be inserted into.
+- Auto-generated fields (`id`, `createdAt`, `updatedAt`, `autoNumber`) have insert type `never` — passing them causes a TypeScript error.
+- Link fields on insert accept only `number[]` (adding IDs). To selectively add/remove links on an existing record use `.update().set({ field: { newIds: [], deletedIds: [] } })`.

package/docs/pagination.md

@@ -0,0 +1,88 @@
+# Pagination
+
+Three methods control how many records are returned and from where in the result set.
+
+## `.limit(count)`
+
+Sets the maximum number of records to return.
+
+```ts
+const users = await qb
+  .selectFrom('users')
+  .selectAll()
+  .limit(20)
+  .execute();
+```
+
+## `.offset(count)`
+
+Skips the first `count` records before returning results.
+
+```ts
+const users = await qb
+  .selectFrom('users')
+  .selectAll()
+  .offset(40)
+  .execute();
+```
+
+## `.paginate(page, limit)`
+
+Convenience wrapper around `.offset()` and `.limit()`. Pages are 1-indexed.
+
+```ts
+.paginate(page, limit)
+// equivalent to .offset((page - 1) * limit).limit(limit)
+```
+
+```ts
+const page3 = await qb
+  .selectFrom('users')
+  .selectAll()
+  .orderBy('name', 'asc')
+  .paginate(3, 25)  // rows 51–75
+  .execute();
+```
+
+## `.count()`
+
+Returns the total number of records that match the current filters, ignoring `.limit()` and `.offset()`. Use this to calculate total pages.
+
+```ts
+const total = await qb
+  .selectFrom('users')
+  .where('role', '=', 'admin')
+  .count();
+
+const totalPages = Math.ceil(total / pageSize);
+```
+
+`count()` can only be called on a root `selectFrom` query, not on a sub-query inside `.with()`.
+
+## Pagination on sub-queries
+
+`.limit()` and `.offset()` are available inside the `.with()` object form to limit how many related records are returned per parent record.
+
+```ts
+const users = await qb
+  .selectFrom('users')
+  .select(['id', 'name'])
+  .with({
+    posts: qb => qb.select(['id', 'title']).limit(3),
+  })
+  .execute();
+// at most 3 posts per user
+```
+
+## Pagination on aggregation queries
+
+All three methods — `.limit()`, `.offset()`, `.paginate()` — are available on `AggregationQueryBuilder` as well.
+
+```ts
+const stats = await qb
+  .aggregateFrom('orders')
+  .groupBy('status')
+  .metrics({ total: count('id') })
+  .paginate(1, 10)
+  .execute();
+```

package/docs/relationships.md

@@ -0,0 +1,75 @@
+# Relationships (Loading Linked Records)
+
+Use `.with()` to load related records through link fields. It is available on `selectFrom` queries.
+
+## What can be loaded
+
+Only fields typed as `LinkColumnType` can be used with `.with()`. These are the fields the CLI generates when a TaylorDB field is of type `link`, `collaborators`, or `modifiedBy`.
+
+Fields that use `AttachmentColumnType` are **not** loaded via `.with()` — attachment URLs are resolved automatically when the attachment field is included in `.select()` or `.selectAll()`.
+
+## Simple form — load all fields
+
+Pass a relation name as a string or an array of relation names. All fields of the linked table are fetched.
+
+```ts
+const users = await qb
+  .selectFrom('users')
+  .select(['id', 'name'])
+  .with('posts')
+  .execute();
+// each user: { id, name, posts: Array<{ id, title, ... all post fields }> }
+```
+
+Multiple relations at once:
+
+```ts
+.with(['posts', 'team'])
+```
+
+## Object form — configure the sub-query
+
+Pass an object where each key is a relation name and the value is a callback that receives a `QueryBuilder` scoped to the linked table. You can call `.select()`, `.where()`, `.orderBy()`, `.limit()`, `.offset()`, and further `.with()` on the sub-builder.
+
+```ts
+const users = await qb
+  .selectFrom('users')
+  .select(['id', 'name'])
+  .with({
+    posts: qb =>
+      qb
+        .select(['id', 'title', 'createdAt'])
+        .where('isPublished', '=', true)
+        .orderBy('createdAt', 'desc')
+        .limit(5),
+  })
+  .execute();
+// each user: { id, name, posts: Array<{ id, title, createdAt }> }
+// only published posts, newest first, max 5 per user
+```
+
+## Nested relationships
+
+You can nest `.with()` inside a sub-query to load relationships of related records.
+
+```ts
+const users = await qb
+  .selectFrom('users')
+  .select(['id', 'name'])
+  .with({
+    posts: qb =>
+      qb
+        .select(['id', 'title'])
+        .with({
+          comments: cqb => cqb.select(['id', 'body']),
+        }),
+  })
+  .execute();
+```
+
+## What cannot be loaded
+
+- **Attachment fields** (`AttachmentColumnType`) are not relationship fields and cannot be used with `.with()`. Select them directly — their URLs are resolved automatically.
+- **Aggregated counts** of related records are not supported through `.with()`. Use `aggregateFrom` with a cross-table filter for that instead.
+- **`returning()` on insert** does not support loading relationships. Perform a follow-up `selectFrom` query if you need related data after an insert.
+- **`update` and `deleteFrom`** do not support `.with()`.