@spooky-sync/query-builder 0.0.1-canary.16 → 0.0.1-canary.18

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spooky-sync/query-builder",
-  "version": "0.0.1-canary.16",
+  "version": "0.0.1-canary.18",
   "description": "Type-safe query builder for SurrealDB with relationship support",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -24,7 +24,8 @@
     "surrealdb",
     "query-builder",
     "typescript",
-    "type-safe"
+    "type-safe",
+    "tanstack-intent"
   ],
   "author": "",
   "license": "MIT",

package/skills/spooky-query-builder/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: spooky-query-builder
+description: >-
+  Type-safe query builder for SurrealDB used by the Spooky framework. Use when
+  defining schemas (SchemaStructure), building queries with QueryBuilder, handling
+  relationships (one/many cardinality), or working with Spooky type helpers like
+  TableNames, GetTable, TableModel, and QueryResult.
+metadata:
+  author: spooky-sync
+  version: "0.0.1"
+---
+
+# Spooky Query Builder
+
+`@spooky-sync/query-builder` provides the type-safe schema definition format and query builder used throughout the Spooky framework.
+
+## Schema Definition
+
+Spooky schemas are defined as `const` objects satisfying `SchemaStructure`. They are typically generated by the Spooky CLI (`spooky generate`), but can be written by hand.
+
+```typescript
+import type { SchemaStructure } from '@spooky-sync/query-builder';
+
+export const schema = {
+  tables: [
+    {
+      name: 'user',
+      columns: {
+        id: { type: 'string', optional: false },
+        email: { type: 'string', optional: false },
+        name: { type: 'string', optional: true },
+      },
+      primaryKey: ['id'],
+    },
+    {
+      name: 'post',
+      columns: {
+        id: { type: 'string', optional: false },
+        title: { type: 'string', optional: false },
+        body: { type: 'string', optional: false },
+        author: { type: 'string', optional: false, recordId: true },
+      },
+      primaryKey: ['id'],
+    },
+  ],
+  relationships: [
+    { from: 'post', field: 'author', to: 'user', cardinality: 'one' },
+    { from: 'user', field: 'posts', to: 'post', cardinality: 'many' },
+  ],
+  backends: {},
+} as const satisfies SchemaStructure;
+```
+
+### Column Types
+
+The `type` field maps to TypeScript types:
+
+| ValueType   | TypeScript Type |
+|-------------|-----------------|
+| `'string'`  | `string`        |
+| `'number'`  | `number`        |
+| `'boolean'` | `boolean`       |
+| `'null'`    | `null`          |
+| `'json'`    | `unknown`       |
+
+Set `optional: true` to make a field nullable (`T | null`).
+Set `recordId: true` to indicate a field stores a SurrealDB RecordId.
+
+## QueryBuilder API
+
+The `QueryBuilder` class provides a fluent, chainable API for constructing type-safe queries.
+
+```typescript
+import { QueryBuilder } from '@spooky-sync/query-builder';
+
+// Create a query builder for the "post" table
+const query = new QueryBuilder(schema, 'post')
+  .where({ author: 'user:alice' })
+  .select('id', 'title', 'body')
+  .orderBy('title', 'desc')
+  .limit(10)
+  .offset(0)
+  .related('author')
+  .build();
+```
+
+### Chain Methods
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `where` | `.where(conditions)` | Filter by field values. String IDs are auto-parsed to RecordId. |
+| `select` | `.select(...fields)` | Pick specific fields. Can only be called once per query. |
+| `orderBy` | `.orderBy(field, 'asc' \| 'desc')` | Sort results. Default direction is `'asc'`. |
+| `limit` | `.limit(count)` | Limit the number of results. |
+| `offset` | `.offset(count)` | Skip the first N results. |
+| `one` | `.one()` | Return a single object instead of an array. Implicitly sets `limit(1)`. |
+| `related` | `.related(field, modifier?)` | Include related data via subquery. See [Relationships](#relationships). |
+| `build` | `.build()` | Finalize the query into a `FinalQuery` object. |
+
+### Relationships
+
+Use `.related()` to include related tables. Relationships must be declared in the schema.
+
+```typescript
+// One-to-one: post has one author
+new QueryBuilder(schema, 'post')
+  .related('author')
+  .build();
+
+// One-to-many: user has many posts
+new QueryBuilder(schema, 'user')
+  .related('posts')
+  .build();
+
+// Nested relationship with modifier
+new QueryBuilder(schema, 'user')
+  .related('posts', (q) => q.orderBy('title', 'asc').limit(5))
+  .build();
+```
+
+Cardinality is inferred from the schema. For `'one'` relationships, the result is an object. For `'many'`, it is an array.
+
+## Type Helpers
+
+See [references/type-helpers.md](references/type-helpers.md) for a full reference of all type utilities.
+
+Key types:
+
+- `TableNames<S>` — Union of all table name strings
+- `GetTable<S, Name>` — Extract a table definition by name
+- `TableModel<T>` — Convert a table's columns to a TypeScript object type
+- `QueryResult<S, TableName, RelatedFields, IsOne>` — The full result type including related fields
+- `BackendNames<S>`, `BackendRoutes<S, B>`, `RoutePayload<S, B, R>` — Backend/run type helpers
+
+## Common Pitfalls
+
+1. **String IDs are auto-converted**: When you pass `'user:alice'` in a `where()`, it is automatically parsed into a SurrealDB `RecordId`. If the string does not contain `:`, and the field is named `id`, the table name is prepended.
+
+2. **`select()` can only be called once**: Calling it twice throws an error. Combine all fields in one call.
+
+3. **Schema must use `as const satisfies SchemaStructure`**: Without `as const`, TypeScript cannot infer literal types for table names and relationships, and type safety is lost.

package/skills/spooky-query-builder/references/type-helpers.md

@@ -0,0 +1,80 @@
+# Type Helpers Reference
+
+## Schema Types
+
+### `SchemaStructure`
+
+The top-level schema interface:
+
+```typescript
+interface SchemaStructure {
+  readonly tables: readonly {
+    readonly name: string;
+    readonly columns: Record<string, ColumnSchema>;
+    readonly primaryKey: readonly string[];
+  }[];
+  readonly relationships: readonly {
+    readonly from: string;
+    readonly field: string;
+    readonly to: string;
+    readonly cardinality: 'one' | 'many';
+  }[];
+  readonly backends: Record<string, HTTPOutboxBackendDefinition>;
+  readonly access?: Record<string, AccessDefinition>;
+  readonly buckets?: readonly BucketDefinitionSchema[];
+}
+```
+
+### `ColumnSchema`
+
+```typescript
+interface ColumnSchema {
+  readonly type: 'string' | 'number' | 'boolean' | 'null' | 'json';
+  readonly optional: boolean;
+  readonly dateTime?: boolean;
+  readonly recordId?: boolean;
+}
+```
+
+## Table Type Helpers
+
+| Type | Description |
+|------|-------------|
+| `TableNames<S>` | Union of all table name strings from the schema |
+| `GetTable<S, Name>` | Extract a specific table definition by name |
+| `TableModel<T>` | Convert a table's `columns` record into a TypeScript object type |
+| `TableFieldNames<T>` | Union of all column names for a table |
+
+### Example
+
+```typescript
+type MySchema = typeof schema;
+type Tables = TableNames<MySchema>; // 'user' | 'post'
+type UserTable = GetTable<MySchema, 'user'>; // The user table definition
+type UserModel = TableModel<UserTable>; // { id: string; email: string; name: string | null }
+```
+
+## Relationship Type Helpers
+
+| Type | Description |
+|------|-------------|
+| `TableRelationships<S, TableName>` | All relationship definitions originating from a table |
+| `RelationshipFields<S, TableName>` | Union of relationship field names for a table |
+| `GetRelationship<S, TableName, Field>` | Get a specific relationship by table and field name |
+
+## Result Type Helpers
+
+| Type | Description |
+|------|-------------|
+| `QueryResult<S, TableName, RelatedFields, IsOne>` | The full query result type. If `IsOne` is `true`, returns a single object; otherwise an array. Includes related fields merged into the base model. |
+| `RelatedFieldsMap` | A record mapping field names to `{ to, cardinality, relatedFields }` |
+
+## Backend Type Helpers
+
+| Type | Description |
+|------|-------------|
+| `BackendNames<S>` | Union of all backend names |
+| `BackendRoutes<S, B>` | Union of all route paths for a backend |
+| `RoutePayload<S, B, R>` | The typed payload object for a specific route |
+| `BucketNames<S>` | Union of all bucket names |
+| `BucketConfig<S, B>` | Configuration for a specific bucket |