@harperfast/template-react-studio 1.6.2 → 1.6.3

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

@@ -48,9 +48,9 @@ Use this skill when you need to define new data structures or modify existing on
 #### How It Works
 
 1. **Create Dedicated Schema Files**: Prefer having a dedicated schema `.graphql` file for each table. Check the `config.yaml` file under `graphqlSchema.files` to see how it's configured. It typically accepts wildcards (e.g., `schemas/*.graphql`), but may be configured to point at a single file.
-2. **Use Directives**: All available directives for defining your schema are defined in `node_modules/harperdb/schema.graphql`. Common directives include `@table`, `@export`, `@primaryKey`, `@indexed`, and `@relationship`.
+2. **Use Directives**: All available directives for defining your schema are defined in `node_modules/harper/schema.graphql`. Common directives include `@table`, `@export`, `@primaryKey`, `@indexed`, and `@relationship`.
 3. **Define Relationships**: Link tables together using the `@relationship` directive.
-4. **Enable Automatic APIs**: If you add `@table @export` to a schema type, Harper automatically sets up REST and WebSocket APIs for basic CRUD operations against that table.
+4. **Enable Automatic APIs**: If you add `@table @export` to a schema type, Harper automatically sets up REST and WebSocket APIs for basic CRUD operations against that table. **Important**: REST endpoints also require `rest: true` in `config.yaml` — without it, `@export`ed tables will not respond to HTTP requests.
 5. **Consider Table Extensions**: If you are going to extend the table in your resources, then do not `@export` the table from the schema.
 
 #### Example
@@ -69,7 +69,7 @@ Harper uses GraphQL schemas to define database tables, relationships, and APIs.
 
 #### Core Harper Directives
 
-Harper extends GraphQL with custom directives that define database behavior. These are typically defined in `node_modules/harperdb/schema.graphql`. If you don't have access to that file, here is a reference of the most important ones:
+Harper extends GraphQL with custom directives that define database behavior. These are typically defined in `node_modules/harper/schema.graphql`. If you don't have access to that file, here is a reference of the most important ones:
 
 ##### Table Definition
 
@@ -103,7 +103,7 @@ Create a file named `graphql.config.yml` in your project root with the following
 
 ```yaml
 schema:
-  - 'node_modules/harperdb/schema.graphql'
+  - 'node_modules/harper/schema.graphql'
   - 'schema.graphql'
   - 'schemas/*.graphql'
 ```
@@ -299,7 +299,7 @@ How to define custom REST endpoints using JavaScript or TypeScript.
 #### How It Works
 
 1. **Create Resource File**: Define your logic in a JS or TS file.
-2. **Define Resource Class**: Export a class extending `Resource` from `harperdb`.
+2. **Define Resource Class**: Export a class extending `Resource` from `harper`.
 3. **Implement HTTP Methods**: Add methods like `get`, `post`, `put`, `patch`, or `delete` to handle corresponding requests.
 4. **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.
@@ -430,11 +430,11 @@ Add the following scripts and dependencies to your `package.json`:
 {
 	"scripts": {
 		"deploy": "dotenv -- npm run deploy:component",
-		"deploy:component": "harperdb deploy_component . restart=rolling replicated=true"
+		"deploy:component": "harper deploy_component . restart=rolling replicated=true"
 	},
 	"devDependencies": {
 		"dotenv-cli": "^11.0.0",
-		"harperdb": "^4.7.20"
+		"harper": "^5.0.0"
 	}
 }
 ```
@@ -446,7 +446,7 @@ The `deploy` script is separated from `deploy:component` to ensure environment v
 - `deploy`: Uses `dotenv-cli` to load environment variables (like `CLI_TARGET`, `CLI_TARGET_USERNAME`, and `CLI_TARGET_PASSWORD`) before executing the next command.
 - `deploy:component`: The actual command that performs the deployment.
 
-By using `dotenv -- npm run deploy:component`, the environment variables are correctly set in the shell session before `harperdb deploy_component` is called, allowing it to authenticate with your cluster.
+By using `dotenv -- npm run deploy:component`, the environment variables are correctly set in the shell session before `harper deploy_component` is called, allowing it to authenticate with your cluster.
 
 #### 2. Configure GitHub Actions
 
@@ -499,7 +499,7 @@ Two ways to serve web content from a Harper application.
 
 #### Methods
 
-1. **Static Serving**: Serve HTML, CSS, and JS files directly. If using the Vite plugin for development, ensure Harper is running (e.g., `harperdb run .`) to allow for Hot Module Replacement (HMR).
+1. **Static Serving**: Serve HTML, CSS, and JS files directly. If using the Vite plugin for development, ensure Harper is running (e.g., `harper run .`) to allow for Hot Module Replacement (HMR).
 2. **Dynamic Rendering**: Use custom resources to render content on the fly.
 
 ### 4.5 Logging Best Practices

package/.agents/skills/harper-best-practices/rules/adding-tables-with-schemas.md

@@ -14,9 +14,9 @@ Use this skill when you need to define new data structures or modify existing on
 ## How It Works
 
 1. **Create Dedicated Schema Files**: Prefer having a dedicated schema `.graphql` file for each table. Check the `config.yaml` file under `graphqlSchema.files` to see how it's configured. It typically accepts wildcards (e.g., `schemas/*.graphql`), but may be configured to point at a single file.
-2. **Use Directives**: All available directives for defining your schema are defined in `node_modules/harperdb/schema.graphql`. Common directives include `@table`, `@export`, `@primaryKey`, `@indexed`, and `@relationship`.
+2. **Use Directives**: All available directives for defining your schema are defined in `node_modules/harper/schema.graphql`. Common directives include `@table`, `@export`, `@primaryKey`, `@indexed`, and `@relationship`.
 3. **Define Relationships**: Link tables together using the `@relationship` directive. For more details, see the [Defining Relationships](defining-relationships.md) skill.
-4. **Enable Automatic APIs**: If you add `@table @export` to a schema type, Harper automatically sets up REST and WebSocket APIs for basic CRUD operations against that table. For a detailed list of available endpoints and how to use them, see the [Automatic REST APIs](automatic-apis.md) skill.
+4. **Enable Automatic APIs**: If you add `@table @export` to a schema type, Harper automatically sets up REST and WebSocket APIs for basic CRUD operations against that table. **Important**: REST endpoints also require `rest: true` in `config.yaml` — without it, `@export`ed tables will not respond to HTTP requests. For a detailed list of available endpoints and how to use them, see the [Automatic REST APIs](automatic-apis.md) skill.
    - `GET /{TableName}`: Describes the schema itself.
    - `GET /{TableName}/`: Lists all records (supports filtering, sorting, and pagination via query parameters). See the [Querying REST APIs](querying-rest-apis.md) skill for details.
    - `GET /{TableName}/{id}`: Retrieves a single record by its ID.

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

@@ -13,11 +13,16 @@ Use this skill when you want to interact with Harper tables via REST or WebSocke
 
 ## How It Works
 
-1. **Enable Automatic APIs**: Ensure your GraphQL schema includes the `@export` directive for the table.
-2. **Access REST Endpoints**: Use the standard endpoints for your table (Note: Paths are case-sensitive).
-3. **Use Automatic WebSockets**: Connect to `wss://your-harper-instance/{TableName}` to receive events whenever updates are made to that table. This is the easiest way to add real-time capabilities. (Use `ws://` for local development without SSL). For more complex needs, see [Real-time Apps](real-time-apps.md).
-4. **Apply Filtering and Querying**: Use query parameters with `GET /{TableName}/` and `DELETE /{TableName}/`. See the [Querying REST APIs](querying-rest-apis.md) skill for advanced details.
-5. **Customize if Needed**: If the automatic APIs don't meet your requirements, [customize the resources](./custom-resources.md).
+1. **Enable REST in `config.yaml`**: REST endpoints are **not active by default**. You must explicitly enable them:
+   ```yaml
+   rest: true
+   ```
+   Without this, `@export`ed tables will not respond to HTTP requests.
+2. **Enable Automatic APIs**: Ensure your GraphQL schema includes the `@export` directive for the table.
+3. **Access REST Endpoints**: Use the standard endpoints for your table (Note: Paths are case-sensitive).
+4. **Use Automatic WebSockets**: Connect to `wss://your-harper-instance/{TableName}` to receive events whenever updates are made to that table. This is the easiest way to add real-time capabilities. (Use `ws://` for local development without SSL). For more complex needs, see [Real-time Apps](real-time-apps.md).
+5. **Apply Filtering and Querying**: Use query parameters with `GET /{TableName}/` and `DELETE /{TableName}/`. See the [Querying REST APIs](querying-rest-apis.md) skill for advanced details.
+6. **Customize if Needed**: If the automatic APIs don't meet your requirements, [customize the resources](./custom-resources.md).
 
 ## Examples
 

package/.agents/skills/harper-best-practices/rules/caching.md

@@ -32,7 +32,7 @@ type MyCache @table(expiration: 3600) @export {
 ### Resource Implementation
 
 ```js
-import { Resource, tables } from 'harperdb';
+import { Resource, tables } from 'harper';
 
 export class ThirdPartyAPI extends Resource {
 	async get() {

package/.agents/skills/harper-best-practices/rules/checking-authentication.md

@@ -13,7 +13,7 @@ Use this skill when you need to implement sign-in/sign-out functionality, protec
 
 ## How It Works
 
-1. **Configure Harper for Sessions**: Ensure `harperdb-config.yaml` has sessions enabled and local auto-authorization disabled for testing:
+1. **Configure Harper for Sessions**: Ensure `harper-config.yaml` has sessions enabled and local auto-authorization disabled for testing:
    ```yaml
    authentication:
      authorizeLocal: false

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

@@ -15,10 +15,10 @@ 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 `harperdb`:
+3. **Define the Resource Class**: Export a class extending `Resource` from `harper`:
 
    ```typescript
-   import { type RequestTargetOrId, Resource } from 'harperdb';
+   import { type RequestTargetOrId, Resource } from 'harper';
 
    export class MyResource extends Resource {
    	async get(target?: RequestTargetOrId) {
@@ -34,7 +34,7 @@ Use this skill when the automatic CRUD operations provided by `@table @export` a
    - **Lowercase and Hyphens**: Use object keys to define custom paths: `export const bar = { 'foo-baz': Foo };` exposes endpoints at `/bar/foo-baz/`.
 6. **Access Tables (Optional)**: Import and use the `tables` object to interact with your data:
    ```typescript
-   import { tables } from 'harperdb';
+   import { tables } from 'harper';
    // ... inside a method
    const results = await tables.MyTable.list();
    ```

package/.agents/skills/harper-best-practices/rules/deploying-to-harper-fabric.md

@@ -35,11 +35,11 @@ Add the following scripts and dependencies to your `package.json`:
 {
 	"scripts": {
 		"deploy": "dotenv -- npm run deploy:component",
-		"deploy:component": "harperdb deploy_component . restart=rolling replicated=true"
+		"deploy:component": "harper deploy_component . restart=rolling replicated=true"
 	},
 	"devDependencies": {
 		"dotenv-cli": "^11.0.0",
-		"harperdb": "^4.7.20"
+		"harper": "^5.0.0"
 	}
 }
 ```
@@ -51,7 +51,7 @@ The `deploy` script is separated from `deploy:component` to ensure environment v
 - `deploy`: Uses `dotenv-cli` to load environment variables (like `CLI_TARGET`, `CLI_TARGET_USERNAME`, and `CLI_TARGET_PASSWORD`) before executing the next command.
 - `deploy:component`: The actual command that performs the deployment.
 
-By using `dotenv -- npm run deploy:component`, the environment variables are correctly set in the shell session before `harperdb deploy_component` is called, allowing it to authenticate with your cluster.
+By using `dotenv -- npm run deploy:component`, the environment variables are correctly set in the shell session before `harper deploy_component` is called, allowing it to authenticate with your cluster.
 
 ### 2. Configure GitHub Actions
 

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

@@ -24,7 +24,7 @@ Use this skill when you need to add custom validation, side effects (like webhoo
 3. **Extend the Table Resource**: Export a class that extends `tables.YourTableName`:
 
    ```typescript
-   import { type RequestTargetOrId, tables } from 'harperdb';
+   import { type RequestTargetOrId, tables } from 'harper';
 
    export class MyTable extends tables.MyTable {
    	async post(target: RequestTargetOrId, record: any) {

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

@@ -30,6 +30,7 @@ Use this skill when you need to perform database operations (CRUD, search, subsc
      // process record
    }
    ```
+   See the [Query Conditions](#query-conditions) section below for the full query object reference.
 5. **Real-time Subscriptions**: Use `subscribe(query)` to listen for changes:
    ```typescript
    for await (const event of tables.MyTable.subscribe(query)) {
@@ -38,6 +39,90 @@ Use this skill when you need to perform database operations (CRUD, search, subsc
    ```
 6. **Publish Events**: Use `publish(id, message)` to trigger subscriptions without necessarily persisting data.
 
+## Query Conditions
+
+When passing a query to `search()`, `get()`, or `subscribe()`, use a query object with a `conditions` array.
+
+### Condition Object Shape
+
+| Property | Description |
+|---|---|
+| `attribute` | Field name, or array of field names to traverse a relationship (e.g., `['brand', 'name']`) |
+| `value` | The value to compare against |
+| `comparator` | One of the comparator strings below (default: `equals`) |
+| `operator` | `and` (default) or `or` — applies to a nested `conditions` block |
+| `conditions` | Nested array of condition objects for complex AND/OR logic |
+
+### Comparator Values
+
+Use these exact strings — incorrect comparator names will silently fail or error:
+
+| Comparator | Meaning |
+|---|---|
+| `equals` | Exact match (default) |
+| `not_equal` | Not equal |
+| `greater_than` | `>` |
+| `greater_than_equal` | `>=` |
+| `less_than` | `<` |
+| `less_than_equal` | `<=` |
+| `starts_with` | String starts with value |
+| `contains` | String contains value |
+| `ends_with` | String ends with value |
+| `between` | Value is between two bounds (pass `value` as `[min, max]`) |
+
+### Query Object Parameters
+
+| Property | Description |
+|---|---|
+| `conditions` | Array of condition objects |
+| `limit` | Maximum number of records to return |
+| `offset` | Number of records to skip (for pagination) |
+| `select` | Array of attribute names to return; supports `$id` and `$updatedtime` |
+| `sort` | Object with `attribute`, `descending` (bool), and optional `next` for secondary sort |
+
+### Examples
+
+**Simple filter:**
+```javascript
+for await (const record of tables.Product.search({
+  conditions: [{ attribute: 'price', comparator: 'less_than', value: 100 }],
+  limit: 20,
+})) { ... }
+```
+
+**AND + nested OR:**
+```javascript
+for await (const record of tables.Product.search({
+  conditions: [
+    { attribute: 'price', comparator: 'less_than', value: 100 },
+    {
+      operator: 'or',
+      conditions: [
+        { attribute: 'rating', comparator: 'greater_than', value: 4 },
+        { attribute: 'featured', value: true },
+      ],
+    },
+  ],
+})) { ... }
+```
+
+**Relationship traversal:**
+```javascript
+for await (const record of tables.Book.search({
+  conditions: [{ attribute: ['brand', 'name'], comparator: 'equals', value: 'Harper' }],
+})) { ... }
+```
+
+**Sort and paginate:**
+```javascript
+for await (const record of tables.Product.search({
+  conditions: [{ attribute: 'inStock', value: true }],
+  sort: { attribute: 'price', descending: false },
+  limit: 10,
+  offset: 20,
+})) { ... }
+```
+
 ## Cautions
 
 Be very careful when performing updates and deletions! You may be dealing with live production data. The wrong request to delete, without approval from a human, could be devastating to a business. Always use the proper approval process.

package/.agents/skills/harper-best-practices/rules/real-time-apps.md

@@ -24,7 +24,7 @@ Use this skill when you need to stream live updates to clients, implement chat f
 ### Bi-directional WebSocket Resource
 
 ```typescript
-import { Resource, tables } from 'harperdb';
+import { Resource, tables } from 'harper';
 
 export class MySocket extends Resource {
 	async *connect(target, incomingMessages) {

package/.agents/skills/harper-best-practices/rules/schema-design-tooling.md

@@ -9,7 +9,7 @@ Harper uses GraphQL schemas to define database tables, relationships, and APIs.
 
 ## Core Harper Directives
 
-Harper extends GraphQL with custom directives that define database behavior. These are typically defined in `node_modules/harperdb/schema.graphql`. If you don't have access to that file, here is a reference of the most important ones:
+Harper extends GraphQL with custom directives that define database behavior. These are typically defined in `node_modules/harper/schema.graphql`. If you don't have access to that file, here is a reference of the most important ones:
 
 ### Table Definition
 
@@ -43,7 +43,7 @@ Create a file named `graphql.config.yml` in your project root with the following
 
 ```yaml
 schema:
-  - 'node_modules/harperdb/schema.graphql'
+  - 'node_modules/harper/schema.graphql'
   - 'schema.graphql'
   - 'schemas/*.graphql'
 ```

package/.agents/skills/harper-best-practices/rules/serving-web-content.md

@@ -59,7 +59,6 @@ Use this skill when you need to serve a frontend (HTML, CSS, JS, or a React app)
 4. **Deploy for Production**: For Vite apps, use a build script to generate static files into a `web/` folder and deploy them using the static handler pattern. For example, these scripts in a package.json can perform the necessary steps:
    ```json
    "build": "vite build",
-   "deploy": "rm -Rf deploy && npm run build && mkdir deploy && mv web deploy/ && cp -R deploy-template/* deploy/ && cp -R schemas resources deploy/ && dotenv -- npm run deploy:component && rm -Rf deploy",
-   "deploy:component": "(cd deploy && harper deploy_component . project=web restart=rolling replicated=true)"
+   "deploy": "rm -Rf deploy && npm run build && mkdir deploy && mv web deploy/ && cp -R deploy-template/* deploy/ && cp -R schemas resources deploy/ && (cd deploy && harper deploy_component . project=web restart=rolling replicated=true) && rm -Rf deploy",
    ```
    Then in production, the "Static Plugin" option will performantly and securely serve your assets. `npm create harper@latest` scaffolds all of this for you.

package/.agents/skills/harper-best-practices/rules/typescript-type-stripping.md

@@ -17,7 +17,7 @@ Use this skill when you want to write Harper Resources in TypeScript and have th
 2. **Name Files with `.ts`**: Create your resource files in the `resources/` directory with a `.ts` extension.
 3. **Use TypeScript Syntax**: Write your resource classes using standard TypeScript (interfaces, types, etc.).
    ```typescript
-   import { Resource } from 'harperdb';
+   import { Resource } from 'harper';
    export class MyResource extends Resource {
    	async get(): Promise<{ message: string }> {
    		return { message: 'Running TS directly!' };

package/.agents/skills/harper-best-practices/rules/using-blob-datatype.md

@@ -22,7 +22,7 @@ Use this skill when you need to store unstructured or large binary data (media,
    ```
 2. **Create and Store Blobs**: Use `createBlob()` from Harper's globals to wrap Buffers or Streams:
    ```javascript
-   import { tables } from 'harperdb';
+   import { tables } from 'harper';
    const blob = createBlob(largeBuffer);
    await tables.MyTable.put('my-id', { data: blob });
    ```

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@harperfast/template-react-studio",
-	"version": "1.6.2",
+	"version": "1.6.3",
 	"type": "module",
 	"repository": "github:HarperFast/create-harper",
 	"scripts": {},

package/skills-lock.json

@@ -5,7 +5,7 @@
       "source": "harperfast/skills",
       "sourceType": "github",
       "skillPath": "harper-best-practices/SKILL.md",
-      "computedHash": "5ba34805d61ba1a997deffcbba9dd92ca775f286c4e8de8df0966518ff7b9eaf"
+      "computedHash": "838b776573e9ebd05ac70c9ad38233a5bf40d1882be0cc54744168092e96e251"
     }
   }
 }