@harperfast/template-react-ts-ssr-studio 1.13.4 → 1.13.6

package/.agents/skills/harper-best-practices/rules/programmatic-table-requests.md

@@ -14,155 +14,161 @@ metadata:
       reference/v5/resources/resource-api.md#`addTo(property: string, value:
       number)`
     - reference/v5/components/javascript-environment.md#Module Formats
-  sourceCommit: e73e5efb2823cc52caf7a6458d67fbcff3bbff2c
-  inputHash: bb360b0d6c0a7bd4
+  sourceCommit: 6c3e29dd9149201364b0d74642725c30f0305e3e
+  inputHash: b42fe5775d69e9a2
 ---
 
 # Programmatic Table Requests
 
-Instructions for the agent to follow when interacting with Harper tables programmatically using the `tables` object.
+Instructions for the agent to interact with Harper tables programmatically using the `tables` object, the Query API, and transactions.
+
+**Instead of:** ORM and query-builder clients (Prisma, Drizzle, Knex). Use this rule rather than adding that service. See `harper-architecture`.
 
 ## When to Use
 
-Apply this rule when writing server-side Harper component code that reads from or writes to tables using the programmatic API — for example, in HTTP handlers, background jobs, timers, or SSR entry points. Use it whenever you need to construct queries with `conditions`, `sort`, `select`, pagination, or transactions outside of the REST layer.
+Apply this rule when writing server-side Harper code that reads, writes, searches, or transactionally modifies table data through the `tables` object. Use it when building background jobs, SSR renderers, or any code that calls `search(`, `addTo`, `select`, `sort`, or `transaction()` directly rather than through REST endpoints.
 
 ## How It Works
 
-1. **Import `tables` (and other APIs) from `harper`**: Access every table defined in `schema.graphql` as a property of `tables`. Each property is the table class implementing the Resource API.
+1. **Import `tables` (and other APIs) from `harper`**: Access every table defined in `schema.graphql` as a named property of `tables`. This is equivalent to `databases.data.<TableName>`.
 
    ```javascript
-   import { tables, transaction } from 'harper';
+   import { tables, Resource } from 'harper';
    const { Product } = tables;
    // same as: databases.data.Product
    ```
 
-   For components in their own directory, run:
+   CommonJS is also supported: `const { tables, Resource } = require('harper');`
+
+   For components in their own directory, link the package first:
 
    ```bash
    npm link harper
    ```
 
-   All installed components have `harper` automatically linked.
+   When bundling for SSR with Vite, keep `harper` external so it resolves to the runtime:
 
-2. **Define your schema with `@table`**: Every type you want to access via `tables` must carry the `@table` directive. Mark queryable fields with `@indexed`.
+   ```javascript
+   // vite.config
+   ssr: {
+   	external: ['harper'];
+   }
+   ```
+
+2. **Define your schema with `@table` (and `@indexed` where needed)**: Tables must be declared in `schema.graphql`. Mark attributes that will be used as sort keys or standalone condition attributes with `@indexed`.
 
    ```graphql
    type Product @table {
    	id: Long @primaryKey
    	name: String
-   	price: Float
+   	price: Float @indexed
    }
    ```
 
-3. **Query records using `search(`**: Pass a Query object to `search()`. The query is an async iterable.
+3. **Query records using `search(`**: Pass a Query object to `search()`. The query is an async iterable; iterate the result with `for await`. Use a `conditions` array to filter records. Each condition specifies `attribute`, `value`, and an optional `comparator`.
+
+   | Property     | Description                                                                                                                                                                         |
+   | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+   | `attribute`  | Property name, or array for chained/joined properties                                                                                                                               |
+   | `value`      | The value to match                                                                                                                                                                  |
+   | `comparator` | `equals` (default), `greater_than`, `greater_than_equal`, `less_than`, `less_than_equal`, `starts_with`, `contains`, `ends_with`, `between`, `not_equal`, or a full-text comparator |
+   | `conditions` | Nested conditions array                                                                                                                                                             |
+   | `operator`   | `and` (default) or `or` for the nested `conditions`                                                                                                                                 |
 
    ```javascript
-   const query = {
+   for await (const record of Product.search({
    	conditions: [{ attribute: 'price', comparator: 'less_than', value: 8.0 }],
-   };
-   for await (const record of Product.search(query)) {
+   })) {
    	// process record
    }
    ```
 
-4. **Build `conditions`**: Each condition object supports the following properties:
+4. **Use `select` to control which properties are returned**: Pass an array of property names, a string for a single property, or nested objects for relationships.
 
-   | Property     | Description                                                                                                                                              |
-   | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
-   | `attribute`  | Property name, or array for chained/joined properties (e.g. `['brand', 'name']`)                                                                         |
-   | `value`      | The value to match                                                                                                                                       |
-   | `comparator` | `equals` (default), `greater_than`, `greater_than_equal`, `less_than`, `less_than_equal`, `starts_with`, `contains`, `ends_with`, `between`, `not_equal` |
-   | `conditions` | Nested conditions array                                                                                                                                  |
-   | `operator`   | `and` (default) or `or` for the nested `conditions`                                                                                                      |
+   ```javascript
+   const book = await Book.get({
+   	id: 42,
+   	select: ['id', 'title', { name: 'author', select: ['name'] }],
+   });
+   ```
 
-5. **Apply `select` to shape results**: Pass an array of property names, a string for a single property, or nested objects for relationships.
+   Special `select` properties:
+   - `$id` — returns the primary key regardless of its name
+   - `$updatedtime` — returns the last-updated timestamp
+   - `$distance` — returns computed vector distance when using a vector index
+   - `$score` — returns BM25 relevance score for full-text queries
+   - `$highlights` — returns full-text fragments and matching spans
 
-   ```javascript
-   // Flat select
-   Product.search({ select: ['name', 'price'] });
+5. **Use `sort` with an `@indexed` attribute or combine with `conditions`**: Harper requires either an `@indexed` sort attribute or at least one `conditions` entry when sorting. Sorting by a non-indexed attribute with zero conditions raises:
 
-   // Nested relationship select
-   Book.get({ id: 42, select: ['id', 'title', { name: 'author', select: ['name'] }] });
-   ```
+   > `HdbError: <attribute> is not indexed and not combined with any other conditions`
 
-   Special `select` values: `$id`, `$updatedtime`, `$distance`.
+   Note: `@primaryKey` alone is treated as not indexed for sort purposes. To iterate a whole table in primary-key order, add an open-ended condition:
+
+   ```javascript
+   Product.search({
+   	conditions: [{ attribute: 'id', comparator: 'greater_than', value: '' }],
+   	sort: { attribute: 'id' },
+   });
+   ```
 
-6. **Apply `sort`**: Harper uses an index to provide sort order.
+   `sort` object properties:
 
    | Property     | Description                                                |
    | ------------ | ---------------------------------------------------------- |
    | `attribute`  | Property name (or array for chained relationship property) |
    | `descending` | Sort descending if `true` (default: `false`)               |
    | `next`       | Secondary sort to resolve ties (same structure)            |
-   - If the sort `attribute` is `@indexed`, no condition is required.
-   - If the sort `attribute` is not indexed, at least one entry in `conditions` (on **any** attribute) is required.
-   - Sorting by a non-indexed attribute with zero conditions raises:
-     > `HdbError: <attribute> is not indexed and not combined with any other conditions`
-   - The bare `@primaryKey` is treated as not indexed for sort purposes. To iterate in primary-key order, add an open-ended condition:
-
-     ```javascript
-     Product.search({
-     	conditions: [{ attribute: 'id', comparator: 'greater_than', value: '' }],
-     	sort: { attribute: 'id' },
-     });
-     ```
 
-   - Pass `allowFullScan: true` to permit an unconditional ordered scan, or omit `sort` entirely to iterate without an index requirement.
-
-7. **Paginate with `limit` and `offset`**:
+6. **Apply `limit` and `offset` for pagination**: Add these to the Query object to bound result sets.
 
    ```javascript
-   Product.search({ conditions: [...], limit: 20, offset: 40 });
+   Product.search({
+   	conditions: [{ attribute: 'price', comparator: 'less_than', value: 100 }],
+   	limit: 20,
+   	offset: 40,
+   });
    ```
 
-8. **Debug with `explain` and `enforceExecutionOrder`**:
+7. **Use `explain` and `enforceExecutionOrder` for debugging and optimization**:
    - `explain: true` — returns conditions reordered as Harper will execute them.
    - `enforceExecutionOrder: true` — forces conditions to execute in the order supplied, disabling Harper's automatic re-ordering.
 
-9. **Use `addTo` for concurrent-safe increments**: `addTo(property, value)` uses CRDT incrementation, safe across threads and nodes.
+8. **Use `addTo` for concurrent-safe numeric updates**: Increments or decrements a property using CRDT incrementation, safe across threads and nodes.
 
    ```javascript
    static async post(target, data) {
      const record = await this.update(target.id);
-     record.addTo('quantity', -1);
+     record.addTo('quantity', -1); // decrement safely across nodes
    }
    ```
 
-10. **Wrap background work in `transaction()`**: Harper auto-starts transactions for HTTP handlers. Use `transaction()` explicitly for timers, background jobs, or any code outside a natural transaction context.
-
-    ```javascript
-    await transaction(async (txn) => {
-    	for (let item of data) {
-    		await MyTable.put(item, txn);
-    	}
-    });
-    ```
+9. **Wrap background or timer work in `transaction()`**: HTTP handlers get a transaction automatically. Use `transaction()` explicitly for timers, background jobs, or any code outside a natural request context. Always `await` the call and `catch` errors.
 
-    The `txn` object exposes:
-
-    | Member                | Type            | Description                                            |
-    | --------------------- | --------------- | ------------------------------------------------------ |
-    | `commit()`            | `() => Promise` | Commits the current transaction                        |
-    | `abort()`             | `() => void`    | Aborts the transaction and resets it                   |
-    | `resetReadSnapshot()` | `() => void`    | Resets the read snapshot to the latest committed state |
-    | `timestamp`           | `number`        | Timestamp associated with the current transaction      |
+   ```javascript
+   await transaction(async (txn) => {
+   	for (let item of data) {
+   		await MyTable.put(item, txn);
+   	}
+   });
+   ```
 
-    On normal callback completion the transaction commits automatically. If the callback throws, the transaction is aborted.
+   The `txn` object exposes:
 
-11. **Understand atomicity**: Transactions span a single database. All tables within the same database share one transactional context — reads return a consistent snapshot and writes across multiple tables commit atomically. Cross-database operations get separate transactions with no cross-database atomicity guarantee.
+   | Member                | Type            | Description                                            |
+   | --------------------- | --------------- | ------------------------------------------------------ |
+   | `commit()`            | `() => Promise` | Commits the current transaction                        |
+   | `abort()`             | `() => void`    | Aborts the transaction and resets it                   |
+   | `resetReadSnapshot()` | `() => void`    | Resets the read snapshot to the latest committed state |
+   | `timestamp`           | `number`        | Timestamp associated with the current transaction      |
 
-12. **Keep `harper` external when bundling for SSR**: In `vite.config`, mark `harper` as external so it resolves to the runtime rather than being bundled.
+   On normal callback completion the transaction commits automatically. If the callback throws, the transaction is aborted.
 
-    ```javascript
-    // vite.config
-    ssr: {
-    	external: ['harper'];
-    }
-    ```
+10. **Understand atomicity boundaries**: All tables within the same database share a single transactional context — reads return a consistent snapshot and writes are committed atomically. Tables in different databases each get their own transaction with no cross-database atomicity guarantee.
 
 ## Examples
 
-**Full CRUD flow:**
+### Basic CRUD and search
 
 ```javascript
 import { tables } from 'harper';
@@ -178,14 +184,15 @@ await Product.patch(created.id, { price: Math.round(created.price * 0.8 * 100) /
 const record = await Product.get(created.id);
 
 // Search with conditions
-for await (const record of Product.search({
+const query = {
 	conditions: [{ attribute: 'price', comparator: 'less_than', value: 8.0 }],
-})) {
+};
+for await (const record of Product.search(query)) {
 	// process record
 }
 ```
 
-**Nested conditions with `or`:**
+### Nested conditions with `or`
 
 ```javascript
 Product.search({
@@ -202,13 +209,32 @@ Product.search({
 });
 ```
 
-**Chained attribute reference (join):**
+### Chained attribute reference (join/relationship)
 
 ```javascript
 Product.search({ conditions: [{ attribute: ['brand', 'name'], value: 'Harper' }] });
 ```
 
-**Background job with `transaction()`:**
+### Selecting and constraining related records
+
+```javascript
+const brand = await Brand.get({
+	id: 42,
+	select: [
+		'id',
+		{
+			name: 'products',
+			conditions: [{ attribute: 'price', comparator: 'greater_than_equal', value: 30 }],
+			sort: { attribute: 'price' },
+			offset: 0,
+			limit: 1,
+			select: ['id', 'price'],
+		},
+	],
+});
+```
+
+### Background job with `transaction()`
 
 ```javascript
 import { isMainThread } from 'node:worker_threads';
@@ -218,7 +244,7 @@ const { MyTable } = tables;
 if (isMainThread) {
 	let running = false;
 	setInterval(async () => {
-		if (running) return;
+		if (running) return; // the previous run has not committed yet
 		running = true;
 		try {
 			let data = await (await fetch('https://example.com/data')).json();
@@ -232,11 +258,11 @@ if (isMainThread) {
 		} finally {
 			running = false;
 		}
-	}, 3600000);
+	}, 3600000); // every hour
 }
 ```
 
-**SSR with Harper data:**
+### SSR with Vite
 
 ```typescript
 import { tables } from 'harper';
@@ -247,11 +273,18 @@ export async function render(url: string): Promise<string> {
 }
 ```
 
+Keep `harper` external in `vite.config` so it resolves to the runtime:
+
+```javascript
+ssr: {
+	external: ['harper'];
+}
+```
+
 ## Notes
 
-- `tables` and `databases` calls run in a trusted server-side context and do **not** automatically apply the target table's role permissions.
-- Programmatic `update`, `patch`, and `delete` calls operate directly on stored data. Scope destructive operations with specific `conditions`, validate the affected set before writing, and gate them behind authorization controls.
-- If `transaction()` is called with a context that already has an active transaction, it reuses that transaction — making it safe to call defensively.
-- Always `await` the `transaction()` call and `catch` errors when outside a request context; an unawaited call means a failed write is never observed.
-- Guard against timer overlap: if a job can outlast its interval, use a `running` flag to skip a tick rather than opening two transactions over the same rows.
-- CommonJS is also supported: `const { tables, Resource } = require('harper');`
+- Calls through `tables` run in a trusted server-side context and do **not** automatically apply the target table's role permissions. Set `checkPermission: true` on the query and pass the authenticated `context` as the second argument when authorization is required.
+- `update`, `patch`, and `delete` operate directly on stored data. Scope destructive operations with specific `conditions`, validate the affected set before writing, and gate them behind authorization controls.
+- Pass `allowFullScan: true` to permit an unconditional ordered scan without conditions. If order doesn't matter, omit `sort` entirely — `search({})` iterates without an index requirement.
+- If `transaction()` is called with a context that already has an active transaction, it reuses that transaction and executes the callback immediately — safe to call defensively.
+- Guard timer-based jobs against overlap: a timer fires on schedule regardless of whether the previous run has committed. Use a `running` flag to skip a tick when the previous run is still active.