@harperfast/template-vue-ts-studio 1.9.0 → 1.9.1

package/.agents/skills/harper-best-practices/AGENTS.md

@@ -1031,19 +1031,20 @@ Use this skill when the automatic CRUD operations provided by `@table @export` a
 
 1. **Check if a Custom Resource is Necessary**: Verify if [Automatic APIs](./automatic-apis.md) or [Extending Tables](./extending-tables.md) can satisfy the requirement first.
 2. **Create the Resource File**: Create a `.ts` or `.js` file in the directory specified by `jsResource` in `config.yaml` (typically `resources/`).
-3. **Define the Resource Class**: Export a class extending `Resource` from `harper`:
+3. **Define the Resource Class**: Export a class extending `Resource` from `harper` and define **static** methods for the HTTP verbs you handle. In Harper 5 the static methods are the HTTP handlers (mapped 1:1 to verbs); they receive a pre-parsed `RequestTarget`, and write handlers also receive the request body as an awaitable `data` argument:
 
    ```typescript
-   import { type RequestTargetOrId, Resource } from 'harper';
+   import { Resource } from 'harper';
 
    export class MyResource extends Resource {
-   	async get(target?: RequestTargetOrId) {
+   	// v5 handlers are static and map 1:1 to HTTP verbs.
+   	static async get(target: any) {
    		return { message: 'Hello from custom GET!' };
    	}
    }
    ```
 
-4. **Implement HTTP Methods**: Add methods like `get`, `post`, `put`, `patch`, or `delete` to handle corresponding requests.
+4. **Implement HTTP Methods**: Add static methods (`get`, `post`, `put`, `patch`, or `delete`) to handle the corresponding requests. Read/delete handlers receive `(target)`; write handlers receive `(target, data)` where `data` is awaitable.
 5. **Route Nesting and Naming**: You can control the URL structure by how you export your resources:
    - **Direct Class Export**: `export class Foo extends Resource` creates endpoints at `/Foo/`. Class names are case-sensitive in the URL.
    - **Nested Objects**: `export const Bar = { Foo };` creates endpoints at `/Bar/Foo/`.
@@ -1074,23 +1075,26 @@ Use this skill when you need to add custom validation, side effects (like webhoo
    }
    ```
 2. **Create the Extension File**: Create a `.ts` file in your `resources/` directory.
-3. **Extend the Table Resource**: Export a class that extends `tables.YourTableName`:
+3. **Extend the Table Resource**: Export a class that extends `tables.YourTableName` and override the relevant **static** methods. In Harper 5 resource handlers are static and map 1:1 to HTTP verbs: `get(target)`, `post(target, data)`, `put(target, data)`, `patch(target, data)`, `delete(target)`. `target` is a pre-parsed `RequestTarget`; for writes, `data` is the request body and is **awaitable** (`await data`). Delegate to `super` to keep Harper's default behavior — a collection create passes just the record (`super.post(record)`), updates pass the target (`super.put(target, data)` / `super.patch(target, data)`), and reads/deletes pass the target (`super.get(target)`). To return a specific HTTP status from a thrown error, set **`.statusCode`** (e.g. `400`) on the error — a plain `.status` property is ignored.
 
    ```typescript
-   import { type RequestTargetOrId, tables } from 'harper';
+   import { tables } from 'harper';
 
    export class MyTable extends tables.MyTable {
-   	async post(target: RequestTargetOrId, record: any) {
-   		// Custom logic here
-   		if (!record.name) {
-   			throw new Error('Name required');
+   	// Static handler; receives (target, data) — data is awaitable.
+   	static async post(target: any, data: any) {
+   		const record = await data;
+   		if (!record?.name) {
+   			const error: any = new Error('Name is required');
+   			error.statusCode = 400; // HTTP status (use statusCode, NOT status)
+   			throw error;
    		}
-   		return super.post(target, record);
+   		return super.post(record); // create delegates with the record (no id)
    	}
    }
    ```
 
-4. **Override Methods**: Override `get`, `post`, `put`, `patch`, or `delete` as needed. Always call `super[method]` to maintain default Harper functionality unless you intend to replace it entirely.
+4. **Override Methods**: Override the static `get`, `post`, `put`, `patch`, or `delete` as needed, delegating to `super.<method>` (see the argument forms above) to preserve Harper's default behavior unless you intend to replace it entirely.
 5. **Implement Logic**: Use overrides for validation, side effects, or transforming data before/after database operations.
 
 ### 3.3 Programmatic Table Requests

package/.agents/skills/harper-best-practices/rules/custom-resources.md

@@ -17,19 +17,20 @@ Use this skill when the automatic CRUD operations provided by `@table @export` a
 
 1. **Check if a Custom Resource is Necessary**: Verify if [Automatic APIs](./automatic-apis.md) or [Extending Tables](./extending-tables.md) can satisfy the requirement first.
 2. **Create the Resource File**: Create a `.ts` or `.js` file in the directory specified by `jsResource` in `config.yaml` (typically `resources/`).
-3. **Define the Resource Class**: Export a class extending `Resource` from `harper`:
+3. **Define the Resource Class**: Export a class extending `Resource` from `harper` and define **static** methods for the HTTP verbs you handle. In Harper 5 the static methods are the HTTP handlers (mapped 1:1 to verbs); they receive a pre-parsed `RequestTarget`, and write handlers also receive the request body as an awaitable `data` argument:
 
    ```typescript
-   import { type RequestTargetOrId, Resource } from 'harper';
+   import { Resource } from 'harper';
 
    export class MyResource extends Resource {
-   	async get(target?: RequestTargetOrId) {
+   	// v5 handlers are static and map 1:1 to HTTP verbs.
+   	static async get(target: any) {
    		return { message: 'Hello from custom GET!' };
    	}
    }
    ```
 
-4. **Implement HTTP Methods**: Add methods like `get`, `post`, `put`, `patch`, or `delete` to handle corresponding requests.
+4. **Implement HTTP Methods**: Add static methods (`get`, `post`, `put`, `patch`, or `delete`) to handle the corresponding requests. Read/delete handlers receive `(target)`; write handlers receive `(target, data)` where `data` is awaitable.
 5. **Route Nesting and Naming**: You can control the URL structure by how you export your resources:
    - **Direct Class Export**: `export class Foo extends Resource` creates endpoints at `/Foo/`. Class names are case-sensitive in the URL.
    - **Nested Objects**: `export const Bar = { Foo };` creates endpoints at `/Bar/Foo/`.

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

@@ -23,21 +23,24 @@ Use this skill when you need to add custom validation, side effects (like webhoo
    }
    ```
 2. **Create the Extension File**: Create a `.ts` file in your `resources/` directory.
-3. **Extend the Table Resource**: Export a class that extends `tables.YourTableName`:
+3. **Extend the Table Resource**: Export a class that extends `tables.YourTableName` and override the relevant **static** methods. In Harper 5 resource handlers are static and map 1:1 to HTTP verbs: `get(target)`, `post(target, data)`, `put(target, data)`, `patch(target, data)`, `delete(target)`. `target` is a pre-parsed `RequestTarget`; for writes, `data` is the request body and is **awaitable** (`await data`). Delegate to `super` to keep Harper's default behavior — a collection create passes just the record (`super.post(record)`), updates pass the target (`super.put(target, data)` / `super.patch(target, data)`), and reads/deletes pass the target (`super.get(target)`). To return a specific HTTP status from a thrown error, set **`.statusCode`** (e.g. `400`) on the error — a plain `.status` property is ignored.
 
    ```typescript
-   import { type RequestTargetOrId, tables } from 'harper';
+   import { tables } from 'harper';
 
    export class MyTable extends tables.MyTable {
-   	async post(target: RequestTargetOrId, record: any) {
-   		// Custom logic here
-   		if (!record.name) {
-   			throw new Error('Name required');
+   	// Static handler; receives (target, data) — data is awaitable.
+   	static async post(target: any, data: any) {
+   		const record = await data;
+   		if (!record?.name) {
+   			const error: any = new Error('Name is required');
+   			error.statusCode = 400; // HTTP status (use statusCode, NOT status)
+   			throw error;
    		}
-   		return super.post(target, record);
+   		return super.post(record); // create delegates with the record (no id)
    	}
    }
    ```
 
-4. **Override Methods**: Override `get`, `post`, `put`, `patch`, or `delete` as needed. Always call `super[method]` to maintain default Harper functionality unless you intend to replace it entirely.
+4. **Override Methods**: Override the static `get`, `post`, `put`, `patch`, or `delete` as needed, delegating to `super.<method>` (see the argument forms above) to preserve Harper's default behavior unless you intend to replace it entirely.
 5. **Implement Logic**: Use overrides for validation, side effects, or transforming data before/after database operations.