@harperfast/template-react-ts-studio 0.8.8 → 0.9.1

package/AGENTS.md

@@ -0,0 +1,16 @@
+# HarperDB Agent Skills
+
+This repository contains "skills" that guide AI agents in developing Harper applications.
+
+## Available Skills
+
+- [Adding Tables](skills/adding-tables.md): Learn how to define schemas and enable automatic REST APIs for your database tables.
+- [Automatic REST APIs](skills/automatic-rest-apis.md): Details on the CRUD endpoints automatically generated for exported tables.
+- [Querying REST APIs](skills/querying-rest-apis.md): How to use filters, operators, sorting, and pagination in REST requests.
+- [Custom Resources](skills/custom-resources.md): How to define custom REST endpoints using JavaScript or TypeScript (Note: Paths are case-sensitive).
+- [Extending Table Resources](skills/extending-tables.md): Adding custom logic to automatically generated table resources.
+- [Defining Relationships](skills/defining-relationships.md): Using the `@relationship` directive to link tables.
+- [Real-time Applications](skills/real-time-apps.md): Implementing WebSockets and Pub/Sub for live data updates.
+- [TypeScript Type Stripping](skills/typescript-type-stripping.md): Using TypeScript directly without build tools via Node.js Type Stripping.
+- [Handling Binary Data](skills/handling-binary-data.md): How to store and serve binary data like images or MP3s.
+- [Checking Authentication](skills/checking-authentication.md): How to use `this.getCurrentUser()` to verify user identity and roles.

package/package.json

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

package/skills/adding-tables.md

@@ -0,0 +1,32 @@
+# Adding Tables to HarperDB
+
+To add tables to a Harper database, follow these guidelines:
+
+1. **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. **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`.
+
+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.
+
+   - `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.
+   - `POST /{TableName}/`: Creates a new record.
+   - `PUT /{TableName}/{id}`: Updates an existing record.
+   - `PATCH /{TableName}/{id}`: Performs a partial update on a record.
+   - `DELETE /{TableName}/`: Deletes all records or filtered records.
+   - `DELETE /{TableName}/{id}`: Deletes a single record by its ID.
+
+### Example
+
+In `schemas/ExampleTable.graphql`:
+
+```graphql
+type ExampleTable @table @export {
+	id: ID @primaryKey
+	name: String
+	email: String @indexed
+}
+```

package/skills/automatic-rest-apis.md

@@ -0,0 +1,41 @@
+# Automatic REST APIs in HarperDB
+
+When you define a GraphQL type with the `@table` and `@export` directives, HarperDB automatically generates a fully-functional REST API for that table. This allows for immediate CRUD (Create, Read, Update, Delete) operations without writing any additional code.
+
+## Enabling REST APIs
+
+To enable the automatic REST API for a table, ensure your GraphQL schema includes the `@export` directive:
+
+```graphql
+type MyTable @table @export {
+	id: ID @primaryKey
+	# ... other fields
+}
+```
+
+## Available 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`.
+
+## Filtering and Querying
+
+The `GET /{TableName}/` and `DELETE /{TableName}/` endpoints can be filtered using query parameters. While basic equality filters are straightforward, HarperDB 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

@@ -0,0 +1,52 @@
+# Checking Authentication in HarperDB
+
+Custom resources and table resource overrides often need to restrict access based on the current user's identity or role. HarperDB provides the `this.getCurrentUser()` method within resource classes to access information about the authenticated user making the request.
+
+## Using `this.getCurrentUser()`
+
+The `this.getCurrentUser()` method returns an object containing details about the authenticated user, such as their username and role. If the request is unauthenticated, it may return `null` or `undefined`.
+
+### Example: Role-Based Access Control
+
+You can check the user's role to determine if they have permission to perform a specific action.
+
+```typescript
+import { RequestTargetOrId, Resource } from 'harperdb';
+
+export class MyResource extends Resource {
+	async post(target: RequestTargetOrId, record: any) {
+		const user = this.getCurrentUser();
+
+		// Check if the user has the 'super_user' role
+		if (user?.role?.role !== 'super_user') {
+			throw {
+				message: 'Only super users are allowed to make changes',
+				statusCode: 403,
+			};
+		}
+
+		return super.post(target, record);
+	}
+}
+```
+
+## Handling Unauthenticated Requests
+
+Always ensure you handle cases where `this.getCurrentUser()` returns `null`, especially if your resource is accessible to unauthenticated users.
+
+```typescript
+const user = this.getCurrentUser();
+if (!user) {
+	throw {
+		message: 'Authentication required',
+		statusCode: 401,
+	};
+}
+```
+
+## User Object Structure
+
+The object returned by `this.getCurrentUser()` typically includes:
+
+- `username`: The username of the authenticated user.
+- `role`: An object containing role information, including the `role` name itself (e.g., `user.role.role`).

package/skills/custom-resources.md

@@ -0,0 +1,82 @@
+# Custom Resources in HarperDB
+
+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.
+
+## Defining a Custom Resource
+
+To create a custom resource:
+
+1. Create a `.ts` (or `.js`) file in the directory specified by `jsResource` in `config.yaml` (usually `resources/`).
+2. Export a class that extends the `Resource` class from the `harperdb` module.
+
+### Example: `resources/greeting.ts`
+
+```typescript
+import { type RecordObject, type RequestTargetOrId, Resource } from 'harperdb';
+
+interface GreetingRecord {
+	greeting: string;
+}
+
+export class Greeting extends Resource<GreetingRecord> {
+	// Set to false if you want HarperDB to manage the instance lifecycle
+	static loadAsInstance = false;
+
+	async get(target?: RequestTargetOrId): Promise<GreetingRecord> {
+		return { greeting: 'Hello from a custom GET endpoint!' };
+	}
+
+	async post(
+		target: RequestTargetOrId,
+		newRecord: Partial<GreetingRecord & RecordObject>,
+	): Promise<GreetingRecord> {
+		// Custom logic for handling POST requests
+		return { greeting: `Hello, ${newRecord.greeting || 'stranger'}!` };
+	}
+}
+```
+
+## Supported HTTP Methods
+
+You can implement any of the following methods in your resource class to handle the corresponding HTTP requests:
+
+- `get(target?: RequestTargetOrId)`
+- `post(target: RequestTargetOrId, body: any)`
+- `put(target: RequestTargetOrId, body: any)`
+- `patch(target: RequestTargetOrId, body: any)`
+- `delete(target: RequestTargetOrId)`
+
+The `target` parameter typically contains the ID or sub-path from the URL.
+
+## Accessing Tables
+
+Within your custom resource, you can easily access your database tables using the `tables` object:
+
+```typescript
+import { Resource, tables } from 'harperdb';
+
+export class MyCustomResource extends Resource {
+	async get() {
+		// Query a table
+		const results = await tables.ExamplePeople.list();
+		return results;
+	}
+}
+```
+
+## Configuration
+
+Ensure your `config.yaml` is configured to load your resources:
+
+```yaml
+jsResource:
+  files: 'resources/*.ts'
+```
+
+Once defined and configured, your resource will be available at a REST endpoint matching the class name exactly.
+
+### Case Sensitivity
+
+Paths in HarperDB are **case-sensitive**. A resource class named `MyResource` will be accessible only at `/MyResource/`, not `/myresource/`.

package/skills/defining-relationships.md

@@ -0,0 +1,71 @@
+# Defining Relationships in HarperDB
+
+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.
+
+## The `@relationship` Directive
+
+The `@relationship` directive is applied to a field in your GraphQL type and takes two optional arguments:
+
+- `from`: The field in the _current_ table that holds the foreign key.
+- `to`: The field in the _related_ table that holds the foreign key.
+
+## Relationship Types
+
+### One-to-One and Many-to-One
+
+To define a relationship where the current table holds the foreign key, use the `from` argument.
+
+```graphql
+type Author @table @export {
+	id: ID @primaryKey
+	name: String
+}
+
+type Book @table @export {
+	id: ID @primaryKey
+	title: String
+	authorId: ID
+	# This field resolves to an Author object using authorId
+	author: Author @relationship(from: "authorId")
+}
+```
+
+### One-to-Many and Many-to-Many
+
+To define a relationship where the _related_ table holds the foreign key, use the `to` argument. The field type should be an array.
+
+```graphql
+type Author @table @export {
+	id: ID @primaryKey
+	name: String
+	# This field resolves to an array of Books that have this author's ID in their authorId field
+	books: [Book] @relationship(to: "authorId")
+}
+
+type Book @table @export {
+	id: ID @primaryKey
+	title: String
+	authorId: ID
+}
+```
+
+## Querying Relationships
+
+Once relationships are defined, you can use them in your REST API queries using dot syntax.
+
+Example:
+`GET /Book/?author.name=Harper`
+
+This will automatically perform a join and return all books whose author's name is "Harper".
+
+You can also use the `select()` operator to include related data in the response:
+
+`GET /Author/?select(name,books(title))`
+
+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.
+- **Improved API Discoverability**: Related data structures are clearly defined in your schema.

package/skills/extending-tables.md

@@ -0,0 +1,56 @@
+# Extending Table Resources in HarperDB
+
+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.
+
+## How to Extend a Table Resource
+
+1. Identify the table you want to extend (e.g., `ExamplePeople`).
+2. Create a TypeScript file in your `resources/` folder.
+3. Export a class that extends `tables.YourTableName`.
+4. Override the desired methods (e.g., `post`, `get`, `put`, `patch`, `delete`).
+
+### Example: `resources/examplePeople.ts`
+
+```typescript
+import { type RequestTargetOrId, tables } from 'harperdb';
+
+export interface ExamplePerson {
+	id: string;
+	name: string;
+	tag: string;
+}
+
+// Extend the automatically generated table resource
+export class ExamplePeople extends tables.ExamplePeople<ExamplePerson> {
+	// Override the custom POST handler
+	async post(target: RequestTargetOrId, newRecord: Omit<ExamplePerson, 'id'>) {
+		// Add custom validation or transformation logic
+		if (!newRecord.name) {
+			throw new Error('Name is required');
+		}
+
+		console.log(`Adding new person: ${newRecord.name}`);
+
+		// Call the super method to perform the actual insertion
+		return super.post(target, newRecord);
+	}
+
+	// Override the custom GET handler
+	async get(target: RequestTargetOrId) {
+		const record = await super.get(target);
+		// Modify the record before returning if necessary
+		return record;
+	}
+}
+```
+
+## Why Extend Tables?
+
+- **Validation**: Ensure data meets specific criteria before it's saved to the database.
+- **Side Effects**: Send an email, trigger a webhook, or log an event when a record is created or updated.
+- **Data Transformation**: Format or enrich data before it's returned to the client.
+- **Access Control**: Add custom logic to determine if a user has permission to access or modify a specific record.
+
+## 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.

package/skills/handling-binary-data.md

@@ -0,0 +1,65 @@
+# Handling Binary Data in HarperDB
+
+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`.
+
+## Storing Base64 Strings as Buffers
+
+In a custom resource or a table resource override, you can intercept the incoming record and convert base64 strings to buffers before saving them to the database.
+
+### Example
+
+Suppose you have a table with a `Blob` field named `data`. You can use `Buffer.from(string, 'base64')` to perform the conversion.
+
+```typescript
+import { RequestTargetOrId, Resource } from 'harperdb';
+
+export class MyResource extends Resource {
+	async post(target: RequestTargetOrId, record: any) {
+		if (record.data) {
+			// Convert base64-encoded string to a Buffer
+			record.data = Buffer.from(record.data, 'base64');
+		}
+		// Call the super method to perform the actual storage
+		return super.post(target, record);
+	}
+}
+```
+
+## Responding with Binary Data
+
+When you want to serve binary data (like an image or an MP3 file) back to the client, you can return a response object from your resource's `get` method. This object should include the appropriate `status`, `headers`, and the binary data itself in the `body`.
+
+### Example: Streaming an MP3 File
+
+In this example, we retrieve a track from the database. If it contains binary data in the `data` field, we return it with the `audio/mpeg` content type.
+
+```typescript
+import { RequestTarget, RequestTargetOrId, Resource } from 'harperdb';
+
+export class TrackResource extends Resource {
+	async get(target: RequestTargetOrId) {
+		const id = (target as RequestTarget)?.id;
+		if (!id) {
+			return super.get(target);
+		}
+		const track = await super.get(target) as any;
+		if (track?.data) {
+			return {
+				status: 200,
+				headers: {
+					'Content-Type': 'audio/mpeg',
+					'Content-Disposition': `inline; filename="${track.name}.mp3"`,
+				},
+				body: track.data,
+			};
+		}
+		return track;
+	}
+}
+```
+
+## Why Use Buffers?
+
+- **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.
+- **Storage**: Storing data as binary is more compact than storing it as a base64-encoded string.

package/skills/querying-rest-apis.md

@@ -0,0 +1,69 @@
+# Querying through REST APIs in HarperDB
+
+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.
+
+## Basic Filtering
+
+The simplest way to filter is by using attribute names as query parameters:
+
+`GET /ExamplePeople/?tag=friend`
+
+This returns all records where `tag` equals `friend`.
+
+## Comparison Operators (FIQL-style)
+
+You can use standard comparison operators by appending them to the attribute name with an `=` sign:
+
+- `gt`: Greater than
+- `ge`: Greater than or equal to
+- `lt`: Less than
+- `le`: Less than or equal to
+- `ne`: Not equal
+
+Example:
+`GET /Products/?price=gt=100&price=lt=200`
+
+## Logic Operators
+
+- **AND**: Use the `&` operator (default).
+- **OR**: Use the `|` operator.
+
+Example:
+`GET /Products/?rating=5|featured=true`
+
+## Grouping
+
+Use parentheses `()` to group conditions and indicate order of operations.
+
+Example:
+`GET /Products/?(rating=5|featured=true)&price=lt=50`
+
+## Selection
+
+Use `select()` to limit the returned fields:
+
+`GET /Products/?select(name,price)`
+
+## Pagination
+
+Use `limit(start, end)` or `limit(end)`:
+
+- `limit(10)`: Returns the first 10 records.
+- `limit(20, 10)`: Skips the first 20 records and returns the next 10.
+
+Example:
+`GET /Products/?limit(0,20)`
+
+## Sorting
+
+Use `sort()` with `+` (ascending) or `-` (descending) prefixes:
+
+`GET /Products/?sort(+price,-rating)`
+
+## Joins and Chained Attributes
+
+If you have defined relationships in your schema using the `@relationship` directive, you can use dot syntax to query across tables. For more on defining these, see the [Defining Relationships](defining-relationships.md) skill.
+
+`GET /Book/?author.name=Harper`
+
+This will perform an automatic join and filter books based on the related author's name.

package/skills/real-time-apps.md

@@ -0,0 +1,71 @@
+# Real-time Applications in HarperDB
+
+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.
+
+## Implementing a WebSocket Resource
+
+To handle WebSocket connections, implement the `connect` method in your custom resource class.
+
+### Example: `resources/exampleSocket.ts`
+
+```typescript
+import {
+	type IterableEventQueue,
+	RequestTarget,
+	Resource,
+	tables,
+} from 'harperdb';
+
+export class ExampleSocket extends Resource {
+	async *connect(
+		target: RequestTarget,
+		incomingMessages: IterableEventQueue<any>,
+	): AsyncIterable<any> {
+		// Subscribe to changes in a specific table
+		const subscription = await tables.ExamplePeople.subscribe(target);
+
+		if (!incomingMessages) {
+			// Server-Sent Events (SSE) mode: only outgoing messages
+			return subscription;
+		}
+
+		// Handle incoming messages from the client
+		for await (let message of incomingMessages) {
+			// Process message and optionally yield responses
+			yield { received: message };
+		}
+	}
+}
+```
+
+## Pub/Sub with `tables.subscribe()`
+
+You can subscribe to change events on any table using the `subscribe()` method. This is typically used within the `connect` method of a resource to stream updates to a connected client.
+
+- `tables.TableName.subscribe(target)`: Subscribes to all changes in the specified table.
+- The `target` parameter can include filters to only subscribe to a subset of changes.
+
+## Server-Sent Events (SSE)
+
+If the client connects using a protocol that only supports one-way communication from the server (like standard SSE), the `incomingMessages` parameter will be null. Your `connect` method should handle this by only returning the subscription or yielding messages.
+
+## Using WebSockets from the Client
+
+You can connect to your real-time resource using a standard WebSocket client.
+
+```javascript
+const socket = new WebSocket('ws://your-harper-instance/ExampleSocket');
+
+socket.onmessage = (event) => {
+	const data = JSON.parse(event.data);
+	console.log('Real-time update:', data);
+};
+
+socket.send(JSON.stringify({ type: 'ping' }));
+```
+
+## Key Real-time Features
+
+- **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.

package/skills/typescript-type-stripping.md

@@ -0,0 +1,47 @@
+# 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.
+
+## 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.
+
+## 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.
+- **Native Performance**: Leverages Node.js's built-in support for stripping types, which is highly efficient.
+
+## Usage
+
+Simply name your resource files with a `.ts` extension in your `resources/` directory.
+
+### Example: `resources/my-resource.ts`
+
+```typescript
+import { Resource } from 'harperdb';
+
+export class MyResource extends Resource {
+	async get() {
+		return { message: 'This is running directly from TypeScript!' };
+	}
+}
+```
+
+When cross-referencing between modules, ensure that the file path contains the appropriate extension.
+
+```typescript
+import { MyResource } from './my-resource.ts';
+```
+
+## Configuration
+
+In your `config.yaml`, ensure your `jsResource` points to your `.ts` files:
+
+```yaml
+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.