@taylordb/query-builder 0.16.3 → 0.17.0

package/docs/sorting.md

@@ -0,0 +1,63 @@
+# Sorting
+
+Use `.orderBy()` to control the order of results returned by a select or aggregation query.
+
+## `.orderBy(field, direction?)`
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `field` | `keyof Table` | — | The field to sort by. TypeScript will autocomplete valid field names for the table. |
+| `direction` | `'asc' \| 'desc'` | `'asc'` | Sort direction. |
+
+```ts
+const users = await qb
+  .selectFrom('users')
+  .select(['id', 'name', 'createdAt'])
+  .orderBy('name', 'asc')
+  .execute();
+```
+
+## Multiple sort fields
+
+Chain `.orderBy()` multiple times. The sorts are applied in the order they are added.
+
+```ts
+const users = await qb
+  .selectFrom('users')
+  .selectAll()
+  .orderBy('role', 'asc')
+  .orderBy('name', 'asc')
+  .execute();
+// sorted by role ascending, then by name ascending within each role
+```
+
+## With pagination
+
+Sorting composes cleanly with `.limit()`, `.offset()`, and `.paginate()`.
+
+```ts
+const page2 = await qb
+  .selectFrom('posts')
+  .select(['id', 'title', 'createdAt'])
+  .orderBy('createdAt', 'desc')
+  .paginate(2, 20)
+  .execute();
+```
+
+## On aggregation queries
+
+`.orderBy()` works the same way on `AggregationQueryBuilder`.
+
+```ts
+const stats = await qb
+  .aggregateFrom('orders')
+  .groupBy('status')
+  .metrics({ total: count('id') })
+  .orderBy('status', 'asc')
+  .execute();
+```
+
+## Limitations
+
+- Sorting is only available on root select queries and aggregation queries. It is not available when configuring a sub-query inside `.with({ ... })`.
+- You cannot sort by a link field directly. Sort by scalar fields on the table.

package/llm.txt

@@ -0,0 +1,29 @@
+# @taylordb/query-builder — LLM Documentation Index
+
+This package is the TypeScript query builder for TaylorDB. It provides a fluent, type-safe API for reading and writing data. Use `createQueryBuilder<TaylorDatabase>(config)` as the entry point — the `TaylorDatabase` type is generated by `@taylordb/cli`.
+
+## Documentation
+
+- [Field Types](./docs/field-types.md)
+  All column types (`TextColumnType`, `NumberColumnType`, `DateColumnType`, `CheckboxColumnType`, `SingleSelectColumnType`, `MultiSelectColumnType`, `LinkColumnType`, `AttachmentColumnType`, `SearchColumnType`, auto-generated variants). What value each type accepts on insert/update, what is returned on select, and which filter operators are available per type.
+
+- [Insert](./docs/insert.md)
+  How to create records using `insertInto().values().returning().execute()`. Single and batch inserts, the default return value, how attachment and link fields are handled on insert, and which tables cannot be inserted into.
+
+- [File Upload](./docs/file-upload.md)
+  How to upload files with `qb.uploadAttachments()`, how to attach the resulting `Attachment` instances to a record on insert or update, how to add/remove individual attachments on update, and how attachment URLs are resolved when reading.
+
+- [Current User](./docs/current-user.md)
+  How to retrieve the authenticated user's profile with `qb.auth.getUser()`, what it returns, and what is required for it to work.
+
+- [Sorting](./docs/sorting.md)
+  How to sort results with `.orderBy(field, direction)`, chaining multiple sort fields, using sorting with pagination, and sorting on aggregation queries.
+
+- [Conditions](./docs/conditions.md)
+  How to filter records with `.where()` and `.orWhere()`. Simple conditions, AND/OR chaining, grouped/nested conditions via callbacks, cross-table filtering on link fields, isEmpty/isNotEmpty, checkbox and date filter values.
+
+- [Relationships](./docs/relationships.md)
+  How to load linked records with `.with()`. Simple string/array form, object form with sub-query configuration, nesting relationships, and what cannot be loaded (attachments, aggregated counts, relationships inside insert returning).
+
+- [Pagination](./docs/pagination.md)
+  How to paginate with `.limit()`, `.offset()`, `.paginate(page, limit)`, how to get the total record count with `.count()`, pagination on sub-queries, and pagination on aggregation queries.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@taylordb/query-builder",
-  "version": "0.16.3",
+  "version": "0.17.0",
   "description": "A type-safe query builder for TaylorDB",
   "private": false,
   "main": "./dist/cjs/index.js",
@@ -14,7 +14,9 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "docs",
+    "llm.txt"
   ],
   "keywords": [
     "query-builder",
@@ -29,7 +31,7 @@
     "lodash": "^4.17.21",
     "socket.io-client": "^4.8.1",
     "zod": "^4.1.12",
-    "@taylordb/shared": "0.16.3"
+    "@taylordb/shared": "0.17.0"
   },
   "devDependencies": {
     "@types/eventemitter3": "^2.0.4",