@harperfast/template-react-ts-studio 0.12.3 → 0.12.4

package/AGENTS.md

@@ -1,11 +1,11 @@
-# HarperDB Agent Skills
+# Harper Agent Skills
 
 This repository contains "skills" that guide AI agents in developing Harper applications.
 
 ## Available Skills
 
 - [Adding Tables with Schemas](skills/adding-tables-with-schemas.md): Learn how to define schemas and enable automatic REST APIs for your database tables with schema .graphql files in Harper.
-- [Automatic REST APIs](skills/automatic-rest-apis.md): Details on the CRUD endpoints automatically generated for exported tables.
+- [Automatic APIs](skills/automatic-apis.md): Details on the CRUD endpoints automatically generated for exported tables with REST and WebSockets.
 - [Querying REST APIs](skills/querying-rest-apis.md): How to use filters, operators, sorting, and pagination in REST requests.
 - [Programmatic Table Requests](skills/programmatic-table-requests.md): How to use filters, operators, sorting, and pagination in programmatic table requests.
 - [Custom Resources](skills/custom-resources.md): How to define custom REST endpoints using JavaScript or TypeScript (Note: Paths are case-sensitive).
@@ -16,3 +16,4 @@ This repository contains "skills" that guide AI agents in developing Harper appl
 - [Handling Binary Data](skills/handling-binary-data.md): How to store and serve binary data like images or MP3s.
 - [Serving Web Content](skills/serving-web-content): Two ways to serve web content from a Harper application.
 - [Checking Authentication](skills/checking-authentication.md): How to use sessions to verify user identity and roles.
+  [adding-tables-with-schemas.md](skills/adding-tables-with-schemas.md)

package/package.json

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

package/resources/README.md

@@ -1,6 +1,6 @@
 # Resources
 
-The [schemas you define in .GraphQL files](../skills/adding-tables-with-schemas.md) will [automatically stand-up REST APIs](../skills/automatic-rest-apis.md).
+The [schemas you define in .GraphQL files](../skills/adding-tables-with-schemas.md) will [automatically stand-up REST APIs](../skills/automatic-apis.md).
 
 But you can [extend your tables with custom logic](../skills/extending-tables.md) and [create your own resources](../skills/custom-resources.md) in this directory.
 

package/skills/adding-tables-with-schemas.md

@@ -1,4 +1,4 @@
-# Adding Tables to HarperDB
+# Adding Tables to Harper
 
 To add tables to a Harper database, follow these guidelines:
 
@@ -8,7 +8,7 @@ To add tables to a Harper database, follow these guidelines:
 
 3. **Defining Relationships**: You can link tables together using the `@relationship` directive. For more details, see the [Defining Relationships](defining-relationships.md) skill.
 
-4. **Automatic REST APIs**: If you add `@table @export` to a schema type, HarperDB automatically sets up REST 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-rest-apis.md) skill.
+4. **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.
 
    - `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.

package/skills/automatic-apis.md

@@ -0,0 +1,49 @@
+# Automatic APIs in Harper
+
+When you define a GraphQL type with the `@table` and `@export` directives, Harper automatically generates a fully-functional REST API and WebSocket interface for that table. This allows for immediate CRUD (Create, Read, Update, Delete) operations and real-time updates without writing any additional code.
+
+## Enabling Automatic APIs
+
+To enable the automatic REST and WebSocket APIs for a table, ensure your GraphQL schema includes the `@export` directive:
+
+```graphql
+type MyTable @table @export {
+	id: ID @primaryKey
+	# ... other fields
+}
+```
+
+## Available REST Endpoints
+
+The following endpoints are automatically created for a table named `TableName` (Note: Paths are **case-sensitive**, so `GET /TableName/` is valid while `GET /tablename/` is not):
+
+- **Describe Schema**: `GET /{TableName}`
+  Returns the schema definition and metadata for the table.
+- **List Records**: `GET /{TableName}/`
+  Lists all records in the table. This endpoint supports advanced filtering, sorting, and pagination. For more details, see the [Querying REST APIs](querying-rest-apis.md) skill.
+- **Get Single Record**: `GET /{TableName}/{id}`
+  Retrieves a single record by its primary key (`id`).
+- **Create Record**: `POST /{TableName}/`
+  Creates a new record. The request body should be a JSON object containing the record data.
+- **Update Record (Full)**: `PUT /{TableName}/{id}`
+  Replaces the entire record at the specified `id` with the provided JSON data.
+- **Update Record (Partial)**: `PATCH /{TableName}/{id}`
+  Updates only the specified fields of the record at the given `id`.
+- **Delete All/Filtered Records**: `DELETE /{TableName}/`
+  Deletes all records in the table, or a subset of records if filtering parameters are provided.
+- **Delete Single Record**: `DELETE /{TableName}/{id}`
+  Deletes the record with the specified `id`.
+
+## Automatic WebSockets
+
+In addition to REST endpoints, Harper also stands up WebSocket interfaces for exported tables. When you connect to the table's endpoint via WebSocket, you will automatically receive events whenever updates are made to that table.
+
+- **WebSocket Endpoint**: `ws://your-harper-instance/{TableName}`
+
+This is the easiest way to add real-time capabilities to your application. For more complex real-time needs, see the [Real-time Applications](real-time-apps.md) skill.
+
+## Filtering and Querying
+
+The `GET /{TableName}/` and `DELETE /{TableName}/` endpoints can be filtered using query parameters. While basic equality filters are straightforward, Harper supports a rich set of operators, sorting, and pagination.
+
+For a comprehensive guide on advanced querying, see the [Querying REST APIs](querying-rest-apis.md) skill.

package/skills/checking-authentication.md

@@ -1,8 +1,8 @@
-# Checking Authentication and Sessions in this app (HarperDB Resources)
+# Checking Authentication and Sessions in this app (Harper Resources)
 
-This project uses HarperDB Resource classes with cookie-backed sessions to enforce authentication and authorization. Below are the concrete patterns used across resources like `resources/me.ts`, `resources/signIn.ts`, `resources/signOut.ts`, and protected endpoints such as `resources/downloadAlbumArtwork.ts`.
+This project uses Harper Resource classes with cookie-backed sessions to enforce authentication and authorization. Below are the concrete patterns used across resources like `resources/me.ts`, `resources/signIn.ts`, `resources/signOut.ts`, and protected endpoints such as `resources/downloadAlbumArtwork.ts`.
 
-Important: To actually enforce sessions (even on localhost), HarperDB must not auto-authorize the local loopback as the superuser. Ensure the following in your HarperDB config (see `~/hdb/harperdb-config.yaml`):
+Important: To actually enforce sessions (even on localhost), Harper must not auto-authorize the local loopback as the superuser. Ensure the following in your Harper config (see `~/hdb/harperdb-config.yaml`):
 
 ```yaml
 authentication:
@@ -174,7 +174,7 @@ export function ensureSuperUser(user: User | undefined) {
 
 ## Client considerations
 
-- Sessions are cookie-based; the server handles setting and reading the cookie via HarperDB. If you make cross-origin requests, ensure the appropriate `credentials` mode and CORS settings.
+- Sessions are cookie-based; the server handles setting and reading the cookie via Harper. If you make cross-origin requests, ensure the appropriate `credentials` mode and CORS settings.
 - If developing locally, double-check the server config still has `authentication.authorizeLocal: false` to avoid accidental superuser bypass.
 
 ## Quick checklist
@@ -183,4 +183,4 @@ export function ensureSuperUser(user: User | undefined) {
 - [ ] Sign-in uses `context.login` and handles 400/403 correctly.
 - [ ] Protected routes call `ensureSuperUser(this.getCurrentUser())` (or another role check) before doing work.
 - [ ] Sign-out verifies a session and deletes it.
-- [ ] `authentication.authorizeLocal` is `false` and `enableSessions` is `true` in HarperDB config.
+- [ ] `authentication.authorizeLocal` is `false` and `enableSessions` is `true` in Harper config.

package/skills/custom-resources.md

@@ -1,8 +1,8 @@
-# Custom Resources in HarperDB
+# Custom Resources in Harper
 
 Custom Resources allow you to define your own REST endpoints with custom logic by writing JavaScript or TypeScript code. This is useful when the automatic CRUD operations provided by `@table @export` are not enough.
 
-HarperDB supports [TypeScript Type Stripping](typescript-type-stripping.md), allowing you to use TypeScript directly without additional build tools on supported Node.js versions.
+Harper supports [TypeScript Type Stripping](typescript-type-stripping.md), allowing you to use TypeScript directly without additional build tools on supported Node.js versions.
 
 ## Defining a Custom Resource
 
@@ -21,7 +21,7 @@ interface GreetingRecord {
 }
 
 export class Greeting extends Resource<GreetingRecord> {
-	// Set to false if you want HarperDB to manage the instance lifecycle
+	// Set to false if you want Harper to manage the instance lifecycle
 	static loadAsInstance = false;
 
 	async get(target?: RequestTargetOrId): Promise<GreetingRecord> {
@@ -79,4 +79,4 @@ Once defined and configured, your resource will be available at a REST endpoint
 
 ### Case Sensitivity
 
-Paths in HarperDB are **case-sensitive**. A resource class named `MyResource` will be accessible only at `/MyResource/`, not `/myresource/`.
+Paths in Harper are **case-sensitive**. A resource class named `MyResource` will be accessible only at `/MyResource/`, not `/myresource/`.

package/skills/defining-relationships.md

@@ -1,6 +1,6 @@
-# Defining Relationships in HarperDB
+# Defining Relationships in Harper
 
-HarperDB allows you to define relationships between tables using the `@relationship` directive in your GraphQL schema. This enables powerful features like automatic joins when querying through REST APIs.
+Harper allows you to define relationships between tables using the `@relationship` directive in your GraphQL schema. This enables powerful features like automatic joins when querying through REST APIs.
 
 ## The `@relationship` Directive
 
@@ -67,5 +67,5 @@ This returns authors with their names and a list of their books (only the titles
 ## Benefits of `@relationship`
 
 - **Simplified Queries**: No need for complex manual joins in your code.
-- **Efficient Data Fetching**: HarperDB optimizes relationship lookups.
+- **Efficient Data Fetching**: Harper optimizes relationship lookups.
 - **Improved API Discoverability**: Related data structures are clearly defined in your schema.

package/skills/extending-tables.md

@@ -1,6 +1,6 @@
-# Extending Table Resources in HarperDB
+# Extending Table Resources in Harper
 
-In HarperDB, when you define a table in GraphQL and export it, you can extend the automatically generated resource class to add custom logic, validation, or hooks to standard CRUD operations.
+In Harper, when you define a table in GraphQL and export it, you can extend the automatically generated resource class to add custom logic, validation, or hooks to standard CRUD operations.
 
 ## How to Extend a Table Resource
 
@@ -53,7 +53,7 @@ export class ExamplePeople extends tables.ExamplePeople<ExamplePerson> {
 
 ## Important Note
 
-When you extend a table resource, HarperDB uses your custom class for all REST API interactions with that table. Make sure to call `super[method]` if you still want the default behavior to occur after your custom logic.
+When you extend a table resource, Harper uses your custom class for all REST API interactions with that table. Make sure to call `super[method]` if you still want the default behavior to occur after your custom logic.
 
 Extended tables do not need to be `@export`ed in their schema .graphql.
 

package/skills/handling-binary-data.md

@@ -1,6 +1,6 @@
-# Handling Binary Data in HarperDB
+# Handling Binary Data in Harper
 
-When working with binary data (such as images or audio files) in HarperDB, you often receive this data as base64-encoded strings through JSON REST APIs. To store this data efficiently in a `Blob` field, you should convert it to a `Buffer`.
+When working with binary data (such as images or audio files) in Harper, you often receive this data as base64-encoded strings through JSON REST APIs. To store this data efficiently in a `Blob` field, you should convert it to a `Buffer`.
 
 ## Storing Base64 Strings as Buffers
 
@@ -63,5 +63,5 @@ export class TrackResource extends Resource {
 ## Why Use Blobs?
 
 - **Efficiency**: `Blob` fields are optimized for storing binary data. Buffers are the standard way to handle binary data in Node.js.
-- **Compatibility**: Many HarperDB features and external libraries expect binary data to be in `Buffer` or `Uint8Array` format.
+- **Compatibility**: Many Harper features and external libraries expect binary data to be in `Buffer` or `Uint8Array` format.
 - **Storage**: Storing data as binary is more compact than storing it as a base64-encoded string.

package/skills/programmatic-table-requests.md

@@ -1,10 +1,10 @@
-# Programmatic Requests with HarperDB Tables
+# Programmatic Requests with Harper Tables
 
-In HarperDB, you can interact with your database tables programmatically using the global `tables` object. Each table defined in your schema is available as a property on this object.
+In Harper, you can interact with your database tables programmatically using the global `tables` object. Each table defined in your schema is available as a property on this object.
 
 ## Basic Usage
 
-The `tables` object provides a direct way to perform CRUD operations from within your HarperDB resources or scripts.
+The `tables` object provides a direct way to perform CRUD operations from within your Harper resources or scripts.
 
 ```typescript
 const track = await tables.ExamplePeople.get(id) as ExamplePerson;

package/skills/querying-rest-apis.md

@@ -1,6 +1,6 @@
-# Querying through REST APIs in HarperDB
+# Querying through REST APIs in Harper
 
-HarperDB's automatic REST APIs support powerful querying capabilities directly through URL query parameters. This allows you to filter, sort, paginate, and join data without writing complex queries.
+Harper's automatic REST APIs support powerful querying capabilities directly through URL query parameters. This allows you to filter, sort, paginate, and join data without writing complex queries.
 
 ## Basic Filtering
 

package/skills/real-time-apps.md

@@ -1,10 +1,14 @@
-# Real-time Applications in HarperDB
+# Real-time Applications in Harper
 
-HarperDB provides built-in support for real-time data synchronization using WebSockets and a Pub/Sub mechanism. This allows clients to receive immediate updates when data changes in the database.
+Harper provides built-in support for real-time data synchronization using WebSockets and a Pub/Sub mechanism. This allows clients to receive immediate updates when data changes in the database.
+
+## Automatic WebSockets
+
+For many use cases, the [Automatic APIs](automatic-apis.md) provided by Harper are more than enough. When you `@export` a table, Harper automatically provides a WebSocket endpoint that publishes events whenever data in that table is updated.
 
 ## Implementing a WebSocket Resource
 
-To handle WebSocket connections, implement the `connect` method in your custom resource class.
+Customizing resources by implementing a `connect` method is only necessary when you want to come up with a more specific back-and-forth or custom message handling. To handle WebSocket connections, implement the `connect` method in your custom resource class.
 
 ### Example: `resources/exampleSocket.ts`
 
@@ -68,4 +72,4 @@ socket.send(JSON.stringify({ type: 'ping' }));
 
 - **Automatic Table Subscriptions**: Easily stream changes from any database table.
 - **Bi-directional Communication**: Send and receive messages in real-time.
-- **Scalable Pub/Sub**: HarperDB handles the efficient distribution of messages to subscribers.
+- **Scalable Pub/Sub**: Harper handles the efficient distribution of messages to subscribers.

package/skills/typescript-type-stripping.md

@@ -1,16 +1,16 @@
 # TypeScript Type Stripping
 
-HarperDB supports using TypeScript directly without any additional build tools (like `tsc` or `esbuild`) by leveraging Node.js's native Type Stripping capability. This allows you to write `.ts` files for your Custom Resources and have them run directly in HarperDB.
+Harper supports using TypeScript directly without any additional build tools (like `tsc` or `esbuild`) by leveraging Node.js's native Type Stripping capability. This allows you to write `.ts` files for your Custom Resources and have them run directly in Harper.
 
 ## Requirements
 
 - **Node.js Version**: You must be running a version of Node.js that supports type stripping (Node.js v22.6.0 or higher).
-- **No Experimental Flags**: When running on supported Node.js versions, HarperDB can automatically handle type stripping for your resource files.
+- **No Experimental Flags**: When running on supported Node.js versions, Harper can automatically handle type stripping for your resource files.
 
 ## Benefits
 
 - **Faster Development**: No need to wait for a build step or manage complex build pipelines.
-- **Simplified Tooling**: You don't need to install or configure `ts-node`, `tsx`, or other TypeScript execution engines for your HarperDB resources.
+- **Simplified Tooling**: You don't need to install or configure `ts-node`, `tsx`, or other TypeScript execution engines for your Harper resources.
 - **Native Performance**: Leverages Node.js's built-in support for stripping types, which is highly efficient.
 
 ## Usage
@@ -44,4 +44,4 @@ jsResource:
   files: 'resources/*.ts'
 ```
 
-When HarperDB starts, it will detect the `.ts` files and, if running on a compatible Node.js version, will execute them using type stripping.
+When Harper starts, it will detect the `.ts` files and, if running on a compatible Node.js version, will execute them using type stripping.