@harperfast/template-react-ts-studio 1.12.7 → 1.12.9

package/.agents/skills/harper-best-practices/rules/extending-tables.md

@@ -6,8 +6,8 @@ metadata:
   sources:
     - reference/v5/resources/overview.md#Extending a Table
     - reference/v5/resources/resource-api.md#Throwing Errors
-  sourceCommit: ce0ab713d918d789bc1c9f22e461e963ccc1dff1
-  inputHash: 19738fbc732e0a1a
+  sourceCommit: 2cfb81318f17e0aca2d600109e6ad813d2d0443e
+  inputHash: 925aa3c817b6c9f1
 ---
 
 # Extending Tables
@@ -16,11 +16,11 @@ Instructions for the agent to follow when adding custom logic to automatically g
 
 ## When to Use
 
-Apply this rule when you need to add computed properties, intercept writes, enforce validation, or otherwise customize the behavior of a Harper table resource beyond what the default generated endpoints provide. Use it any time a `@table` type needs server-side logic attached to its REST handlers.
+Apply this rule when you need to override or augment the default HTTP handler behavior (GET, POST, PUT, PATCH, DELETE) for a Harper table resource. Use it when a table needs computed properties, input transformation, authorization checks, or custom error responses.
 
 ## How It Works
 
-1. **Define the schema without `@export`**: Declare the table type in `schema.graphql` and omit the `@export` directive. Leaving `@export` on the schema while also exporting a subclass with the same name produces conflicting endpoints. Let the JavaScript class own the URL instead.
+1. **Define the table schema without `@export`**: In `schema.graphql`, declare the table type but omit the `@export` directive. Leaving `@export` on the schema while also exporting a subclass with the same name produces conflicting endpoints.
 
    ```graphql
    # Omit the `@export` directive
@@ -30,7 +30,7 @@ Apply this rule when you need to add computed properties, intercept writes, enfo
    }
    ```
 
-2. **Extend the generated table class**: In `resources.js`, extend from the `tables.<TypeName>` global. The class name you export becomes the URL path. The exported class extends tables.
+2. **Extend the generated table class in `resources.js`**: Use `extends tables.<TableName>` to subclass the auto-generated resource. The exported JavaScript class owns the URL instead of the schema type.
 
    ```javascript
    export class MyTable extends tables.MyTable {
@@ -40,19 +40,17 @@ Apply this rule when you need to add computed properties, intercept writes, enfo
    	}
 
    	static async post(target, data) {
-   		this.create({ ...(await data), status: 'pending' });
+   		return this.create({ ...(await data), status: 'pending' });
    	}
    }
    ```
 
-3. **Call `super` to preserve default behavior**: When delegating to `super`, match the argument form to the operation:
-   - Reads/deletes: `super.get(target)` / `super.delete(target)`
+3. **Call `super` with the correct argument form per operation**: When delegating to the default behavior, match arguments to the operation type:
+   - Reads and deletes: `super.get(target)` / `super.delete(target)`
    - Collection create: `super.post(target, record)` — target carries no id
    - Updates: `super.put(target, data)` / `super.patch(target, data)`
 
-   Omit the `super` call only if you intend to replace the default behavior entirely.
-
-4. **Set `statusCode` on thrown errors to control HTTP responses**: Uncaught errors are caught by the protocol handler and produce error responses for REST. Use `.statusCode` — a plain `.status` property is ignored.
+4. **Set `statusCode` on thrown errors to control HTTP status**: A plain `.status` property is ignored. Use `.statusCode` on the error object:
 
    ```javascript
    const error = new Error('Name is required');
@@ -60,7 +58,9 @@ Apply this rule when you need to add computed properties, intercept writes, enfo
    throw error;
    ```
 
-5. **Configure Harper to load both files**: Ensure your configuration references the schema and resource files.
+   Uncaught errors are caught by the protocol handler and produce error responses for REST.
+
+5. **Configure Harper to load both files**: Ensure your configuration references the schema and resource files:
 
    ```yaml
    rest: true
@@ -72,17 +72,9 @@ Apply this rule when you need to add computed properties, intercept writes, enfo
 
 ## Examples
 
-Full end-to-end example — schema, resource class, and error handling:
-
-```graphql
-# schema.graphql — omit @export so the JS class owns the endpoint
-type MyTable @table {
-	id: Long @primaryKey
-}
-```
+Full example extending a table with a computed GET response, a custom POST, and a guarded handler that throws a typed error:
 
 ```javascript
-// resources.js
 export class MyTable extends tables.MyTable {
 	static async get(target) {
 		// get the record from the database
@@ -92,24 +84,24 @@ export class MyTable extends tables.MyTable {
 	}
 
 	static async post(target, data) {
-		// custom action on POST
-		this.create({ ...(await data), status: 'pending' });
+		// custom action on POST; return the write so the response waits for the commit
+		return this.create({ ...(await data), status: 'pending' });
 	}
-}
-```
-
-Throwing a controlled HTTP error:
 
-```javascript
-if (!authorized) {
-	const error = new Error('Forbidden');
-	error.statusCode = 403;
-	throw error;
+	static async delete(target) {
+		if (!authorized) {
+			const error = new Error('Forbidden');
+			error.statusCode = 403;
+			throw error;
+		}
+		return super.delete(target);
+	}
 }
 ```
 
 ## Notes
 
-- Always omit `@export` from the schema type when a JavaScript subclass is exporting the same name. The two registrations conflict.
-- `super` must be called with the correct arguments for each operation type — mismatched arguments will not behave as expected.
-- `statusCode` is the only recognized property for controlling HTTP status on thrown errors; `.status` is ignored.
+- Always omit `@export` from the schema type when you export a subclass with the same name in JavaScript. The exported class owns the endpoint registration.
+- Call `super.get/post/put/patch/delete` to preserve Harper's default behavior unless you intend to replace it entirely.
+- `statusCode` on an error object controls the HTTP response status for REST. A `.status` property is ignored.
+- See [`Database / Schema`](/reference/v5/database/schema.md) for full schema API details.

package/.agents/skills/harper-best-practices/rules/handling-binary-data.md

@@ -7,8 +7,8 @@ metadata:
     - reference/v5/database/api.md#Accepting Binary in JSON Requests
     - reference/v5/database/api.md#Serving Binary from a Resource
     - reference/v5/rest/content-types.md#Storing Arbitrary Content Types
-  sourceCommit: ce0ab713d918d789bc1c9f22e461e963ccc1dff1
-  inputHash: fa06480e6fae7614
+  sourceCommit: 2cfb81318f17e0aca2d600109e6ad813d2d0443e
+  inputHash: 8be9e31f009e2d27
 ---
 
 # Handling Binary Data
@@ -17,28 +17,30 @@ Instructions for the agent to follow when storing and serving binary data (image
 
 ## When to Use
 
-Apply this rule when a Harper resource needs to accept, store, or serve binary payloads such as images, audio files, or calendar data. Use it when REST clients send `base64`-encoded data inside JSON, when raw binary is uploaded via `PUT`/`POST`, or when a resource must stream binary back to the client with the correct `Content-Type`.
+Apply this rule when a Harper resource needs to accept, store, or serve binary payloads such as images, audio files, or calendar data. Use it when clients send raw binary via `PUT`/`POST`, or when they send `base64`-encoded data inside a JSON body.
 
 ## How It Works
 
-1. **Accept base64-encoded binary from JSON clients**: Decode the incoming `base64` string with `Buffer.from` and wrap it using `createBlob`, recording the MIME type. Override `post` in your resource class:
+1. **Accept base64-encoded binary from JSON clients**: REST clients that cannot post raw binary send `base64` inside a JSON body. In the resource override, `await` the `record` promise before reading any fields — reading fields off the unresolved promise silently yields `undefined` and stores the raw base64 string. Decode the field with `Buffer.from` and wrap it with `createBlob`, recording the MIME type.
 
    ```typescript
    import { type RequestTargetOrId, tables, createBlob } from 'harper';
 
    export class Photo extends tables.Photo {
    	static async post(target: RequestTargetOrId, record: any) {
-   		if (record.data) {
-   			record.data = createBlob(Buffer.from(record.data, record.encoding || 'base64'), {
-   				type: record.contentType || 'application/octet-stream',
+   		const body = await record;
+   		if (!body) return new Response('A JSON body is required', { status: 400 });
+   		if (body.data) {
+   			body.data = createBlob(Buffer.from(body.data, body.encoding || 'base64'), {
+   				type: body.contentType || 'application/octet-stream',
    			});
    		}
-   		return super.post(target, record);
+   		return super.post(target, body);
    	}
    }
    ```
 
-2. **Serve binary from a resource**: Override `get` to return a response object with the blob's MIME type in the `Content-Type` header and the blob as the body. Harper streams it to the client:
+2. **Serve binary from a resource**: Override `get` to return a response object with the blob's MIME type in the `Content-Type` header and the blob as the body. Harper streams it to the client.
 
    ```typescript
    export class Photo extends tables.Photo {
@@ -56,28 +58,11 @@ Apply this rule when a Harper resource needs to accept, store, or serve binary p
    }
    ```
 
-3. **Upload raw binary with a non-standard content type**: Make a `PUT` or `POST` with any non-standard `Content-Type` header. Harper automatically stores the body as a record with `contentType` and `data` properties:
+3. **Store arbitrary content types via raw PUT/POST**: When a `PUT` or `POST` arrives with a non-standard `Content-Type` (e.g., `text/calendar`, `image/gif`), Harper automatically stores the content as a record with `contentType` and `data` properties. Retrieving that record returns the response with the original `Content-Type` and body. If the content type is not from the `text` family, the data is treated as binary (a Node.js `Buffer`).
 
-   ```http
-   PUT /my-resource/33
-   Content-Type: text/calendar
+   Use `application/octet-stream` for generic binary data, or target a specific property:
 
-   BEGIN:VCALENDAR
-   VERSION:2.0
-   ...
    ```
-
-   Harper stores this as:
-
-   ```json
-   { "contentType": "text/calendar", "data": "BEGIN:VCALENDAR\nVERSION:2.0\n..." }
-   ```
-
-   Retrieving that record returns the response with the stored `Content-Type` and body. If the content type is not from the `text` family, the data is treated as binary (a Node.js `Buffer`).
-
-4. **Upload binary to a specific property**: Use `application/octet-stream` (or any image/binary MIME type) and target a sub-path to store binary directly on a property:
-
-   ```http
    PUT /my-resource/33/image
    Content-Type: image/gif
 
@@ -86,23 +71,40 @@ Apply this rule when a Harper resource needs to accept, store, or serve binary p
 
 ## Examples
 
-**End-to-end: accept base64 JSON, store as blob, serve as binary**
+**Storing a calendar entry with a raw PUT:**
+
+```
+PUT /my-resource/33
+Content-Type: text/calendar
+
+BEGIN:VCALENDAR
+VERSION:2.0
+...
+```
+
+Harper stores this as:
+
+```json
+{ "contentType": "text/calendar", "data": "BEGIN:VCALENDAR\nVERSION:2.0\n..." }
+```
+
+**Full resource class handling base64 JSON upload and binary serving:**
 
 ```typescript
 import { type RequestTargetOrId, tables, createBlob } from 'harper';
 
 export class Photo extends tables.Photo {
-	// Accept base64-encoded uploads in JSON
 	static async post(target: RequestTargetOrId, record: any) {
-		if (record.data) {
-			record.data = createBlob(Buffer.from(record.data, record.encoding || 'base64'), {
-				type: record.contentType || 'application/octet-stream',
+		const body = await record;
+		if (!body) return new Response('A JSON body is required', { status: 400 });
+		if (body.data) {
+			body.data = createBlob(Buffer.from(body.data, body.encoding || 'base64'), {
+				type: body.contentType || 'application/octet-stream',
 			});
 		}
-		return super.post(target, record);
+		return super.post(target, body);
 	}
 
-	// Stream the blob back with the correct Content-Type
 	static async get(target: RequestTargetOrId) {
 		const record = await super.get(target);
 		if (record?.data) {
@@ -119,7 +121,6 @@ export class Photo extends tables.Photo {
 
 ## Notes
 
-- `createBlob` takes a `Buffer` as its first argument and an options object with a `type` property for the MIME type. See [using-blob-datatype.md](using-blob-datatype.md) for full details on the blob data type.
-- Always fall back to `application/octet-stream` when no MIME type is known, both when creating and when serving blobs.
-- When Harper retrieves a record that has both `contentType` and `data` properties, it automatically sets the response `Content-Type` and body — no custom `get` override is required for that case unless you need additional logic.
-- Non-`text` content types cause `data` to be stored and returned as a Node.js `Buffer`.
+- Always `await` the `record` parameter before accessing its properties; accessing fields on the unresolved promise yields `undefined`.
+- `createBlob` accepts a `Buffer` and an options object with a `type` property for the MIME type. Fall back to `application/octet-stream` when no MIME type is provided.
+- For schema-level blob field definitions, see [using-blob-datatype.md](using-blob-datatype.md).

package/.agents/skills/harper-best-practices/rules/querying-rest-apis.md

@@ -5,17 +5,17 @@ metadata:
   mode: generate
   sources:
     - reference/v5/rest/querying.md
-  sourceCommit: 677ad213d67822e109c83619e181ca23a59823db
-  inputHash: 0f8efee293628a52
+  sourceCommit: 2cfb81318f17e0aca2d600109e6ad813d2d0443e
+  inputHash: 25b9daabc0a28fd5
 ---
 
 # Querying REST APIs
 
-Instructions for the agent to filter, sort, select, and paginate Harper REST API collections using URL query parameters.
+Instructions for the agent to filter, sort, select, and paginate records through Harper's URL-based REST query language.
 
 ## When to Use
 
-Apply this rule whenever building or modifying code that queries Harper REST collection endpoints. Use it when you need to filter records by attribute values, apply comparison operators, sort or paginate results, or join across related tables. See [automatic-apis.md](automatic-apis.md) for how Harper exposes tables as REST endpoints.
+Apply this rule whenever you need to construct or handle GET requests against Harper collection endpoints that require filtering by attribute value, comparison operators, sorting, field selection, or paginated results. This rule also covers type coercion syntax and relationship joins via dot notation. See [automatic-apis.md](automatic-apis.md) for how REST endpoints are generated from schemas.
 
 ## How It Works
 
@@ -26,7 +26,13 @@ Apply this rule whenever building or modifying code that queries Harper REST col
    GET /Product/?category=software&inStock=true
    ```
 
-2. **Apply comparison operators (FIQL syntax)**: Use FIQL operators in the query string for numeric, string, and date comparisons.
+   To filter for null values:
+
+   ```
+   GET /Product/?discount=null
+   ```
+
+2. **Apply comparison operators (FIQL syntax)**: Use FIQL operators in the query string for range and pattern matching.
 
    | Operator             | Meaning                                |
    | -------------------- | -------------------------------------- |
@@ -61,7 +67,7 @@ Apply this rule whenever building or modifying code that queries Harper REST col
    GET /Product/?price=gt=100&lt=200
    ```
 
-4. **Apply type conversion**: For FIQL comparators, Harper converts values automatically. Use explicit prefixes to force a type.
+4. **Apply type conversion**: For FIQL comparators (`==`, `!=`, `=gt=`, etc.), Harper converts values automatically. Use explicit type prefixes to force a specific type.
 
    | Syntax                                    | Behavior                                    |
    | ----------------------------------------- | ------------------------------------------- |
@@ -81,20 +87,20 @@ Apply this rule whenever building or modifying code that queries Harper REST col
    GET /Product/?rating=5|featured=true
    ```
 
-6. **Group conditions**: Use parentheses or square brackets to control order of operations. Prefer square brackets when constructing queries from user input, since standard URI encoding safely encodes `[` and `]`.
+6. **Group conditions**: Use parentheses or square brackets to control evaluation order. Prefer square brackets when building queries from user input, since standard URI encoding safely encodes `[` and `]`.
 
    ```
    GET /Product/?rating=5|(price=gt=100&price=lt=200)
    GET /Product/?rating=5&[tag=fast|tag=scalable|tag=efficient]
    ```
 
-   Construct from JavaScript:
+   Build grouped queries in JavaScript:
 
    ```javascript
    let url = `/Product/?rating=5&[${tags.map(encodeURIComponent).join('|')}]`;
    ```
 
-7. **Select specific properties with `select(`**: Append `select(...)` as a query function separated by `&`.
+7. **Select specific properties with `select()`**: Append `select()` as a query function separated by `&`.
 
    | Syntax                                 | Returns                                     |
    | -------------------------------------- | ------------------------------------------- |
@@ -104,47 +110,99 @@ Apply this rule whenever building or modifying code that queries Harper REST col
    | `?select(property1,)`                  | Objects with a single specified property    |
    | `?select(property{subProp1,subProp2})` | Nested objects with specific sub-properties |
 
-8. **Paginate with `limit(`**: Use `limit(end)` or `limit(start,end)` to control result count and offset.
+   ```
+   GET /Product/?category=software&select(name)
+   GET /Product/?brand.name=Microsoft&select(name,brand{name})
+   ```
+
+8. **Limit results with `limit(end)` or `limit(start,end)`**: Append as a query function.
+
+   ```
+   GET /Product/?rating=gt=3&inStock=true&select(rating,name)&limit(20)
+   GET /Product/?rating=gt=3&limit(10,30)
+   ```
+
+9. **Sort results with `sort(property)` or `sort(+property,-property,...)`**: Prefix `+` or no prefix = ascending; `-` = descending. List multiple properties to break ties in order.
+
+   ```
+   GET /Product/?rating=gt=3&sort(+name)
+   GET /Product/?sort(+rating,-price)
+   ```
 
-9. **Sort with `sort(`**: Use `sort(property)` or `sort(+property,-property,...)`. Prefix `+` or no prefix = ascending; `-` = descending.
+10. **Paginate with a total count**: Use `limit(start,end)` for paging and send a `Prefer` request header to receive a total match count.
 
-10. **Query across relationships**: Use dot-syntax to filter by related table attributes. Relationships must be defined in the schema using `@relationship`. Relationship attributes are not included by default — use `select()` to include them.
+    | `Prefer` value    | Meaning                                  |
+    | ----------------- | ---------------------------------------- |
+    | `count=exact`     | Exact count of matching records (opt-in) |
+    | `count=estimated` | Fast approximate count                   |
 
     ```
+    GET /Product/?category=software&limit(0,25)
+    Prefer: count=exact
+    ```
+
+    The server responds with:
+
+    | Header               | Example           | Description                                            |
+    | -------------------- | ----------------- | ------------------------------------------------------ |
+    | `Content-Range`      | `items 0-24/1234` | 0-based inclusive range out of total matching records  |
+    | `Range-Unit`         | `items`           | Unit used by `Content-Range`                           |
+    | `Preference-Applied` | `count=exact`     | Count mode the server applied (`exact` or `estimated`) |
+
+    The response status is always `200`. When the total cannot be produced, it is reported as `*` (e.g., `Content-Range: items 0-24/*`).
+
+    Enable exact counts in the application's REST configuration:
+
+    ```yaml
+    rest:
+      exactCount: true
+    ```
+
+    Without this, a `count=exact` request is served as an estimate.
+
+11. **Query across relationships using dot syntax**: Define relationships in the schema with `@relationship`, then filter and select across them.
+
+    ```
+    GET /Product/?brand.name=Microsoft
+    GET /Brand/?products.name=Keyboard
     GET /Product/?brand.name=Microsoft&select(name,brand{name})
     ```
 
-11. **Query for null values**: Use `=null` as the value to match null or non-null records.
+    Filtering on a related attribute produces INNER JOIN behavior. Selecting a relationship without filtering produces LEFT JOIN behavior — the property is omitted if the foreign key is null or references a non-existent record.
+
+12. **Access a specific property by URL**: Append the property name with dot syntax to the record ID.
+
     ```
-    GET /Product/?discount=null
+    GET /MyTable/123.propertyName
     ```
 
+    This only works for declared schema properties. The suffixes `.json`, `.cbor`, `.msgpack`, and `.csv` are reserved as content-type selectors.
+
 ## Examples
 
-**Filter with comparison operators and select:**
+**Range filter with select and sort:**
 
 ```
-GET /Product/?category=software&price=gt=100&price=lt=200&select(name,price)
+GET /Product/?category=software&price=gt=100&price=lt=200&select(name,price)&sort(+price)
 ```
 
-**Paginate and sort:**
+**Paginated request with exact count:**
 
 ```
-GET /Product/?rating=gt=3&inStock=true&select(rating,name)&limit(20)
-GET /Product/?rating=gt=3&limit(10,30)
-GET /Product/?rating=gt=3&sort(+name)
-GET /Product/?sort(+rating,-price)
+GET /Product/?category=software&limit(0,25)
+Prefer: count=exact
 ```
 
-**OR logic with grouping:**
+Response headers:
 
 ```
-GET /Product/?price=lt=100|[rating=5&[tag=fast|tag=scalable|tag=efficient]&inStock=true]
+HTTP/1.1 200 OK
+Content-Range: items 0-24/1234
+Range-Unit: items
+Preference-Applied: count=exact
 ```
 
-**Relationship join with nested select:**
-
-Define the schema:
+**Relationship schema and join query:**
 
 ```graphql
 type Product @table @export {
@@ -160,11 +218,8 @@ type Brand @table @export {
 }
 ```
 
-Query with join:
-
 ```
 GET /Product/?brand.name=Microsoft&select(name,brand{name,id})
-GET /Brand/?products.name=Keyboard
 ```
 
 **Many-to-many relationship:**
@@ -182,16 +237,17 @@ type Product @table @export {
 GET /Product/?resellers.name=Cool Shop&select(id,name,resellers{name,id})
 ```
 
-**Access a specific property by record ID:**
+**OR grouping with user-supplied tags:**
 
-```
-GET /MyTable/123.propertyName
+```javascript
+let url = `/Product/?rating=5&[${tags.map(encodeURIComponent).join('|')}]`;
 ```
 
 ## Notes
 
-- Only indexed attributes can be used as the primary filter attribute; when combining multiple attributes, only one needs to be indexed.
-- Relationship attributes are excluded from responses by default. Always use `select(` to include them.
-- When selecting a related attribute without filtering on it, the behavior is a LEFT JOIN — the property is omitted if the foreign key is null or references a non-existent record.
-- The suffixes `.json`, `.cbor`, `.msgpack`, and `.csv` in URL paths are reserved as content-type selectors and take precedence over a property of the same name.
-- Square brackets are preferred over parentheses when building grouped queries programmatically, because `[` and `]` are safely URL-encoded by standard encoding functions while `(` is not.
+- The queried attribute must be indexed for basic attribute filtering to execute. For multi-attribute queries, only one attribute needs to be indexed.
+- Null indexing requires indexes created after the feature was introduced. Rebuild existing indexes (remove and re-add) to support `name==null` queries.
+- `limit()` must be a non-negative integer no larger than **10,000**, and the requested window (offset + limit) no larger than **1,000,000**, for count headers to be returned.
+- A `HEAD` request with a `Prefer: count=exact` header returns count headers with no body — it saves bandwidth but still scans the matched set.
+- When CORS is enabled, `Content-Range`, `Range-Unit`, and `Preference-Applied` are added to `Access-Control-Expose-Headers` automatically.
+- Operators `!=` and `=ct=` (contains) do not produce cardinality estimates; the total is reported as `*` when these are used with `count=exact`.