@harperfast/template-react-studio 1.2.1 → 1.3.0

package/skills/extending-tables.md

@@ -1,70 +0,0 @@
-# Extending Table Resources in Harper
-
-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.
-
-## Do you need to extend tables?
-
-Exported tables have [automatic APIs](./automatic-apis.md) as a part of them. These APIs may be sufficient for what you need.
-
-## 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, 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.
-
-```graphql
-type ExamplePerson @table {
-	id: ID @primaryKey
-	name: String
-	tag: String @indexed
-}
-```

package/skills/handling-binary-data.md

@@ -1,67 +0,0 @@
-# Handling Binary Data in Harper
-
-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
-
-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 to a buffer, and then use Harper's `createBlob` function to turn that buffer into a blob with a type such as `{ type: 'image/jpeg' }`.
-
-```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 = createBlob(Buffer.from(record.artwork, 'base64'), {
-				type: 'image/jpeg',
-			});
-		}
-		// 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: Responding with a JPEG File
-
-In this example, we retrieve a thumbnail from the database. If it contains binary data in the `data` field, we return it with the `image/jpeg` 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 thumbnail = await super.get(target);
-		if (thumbnail?.data) {
-			return {
-				status: 200,
-				headers: {
-					'Content-Type': 'image/jpeg',
-					'Content-Disposition': `inline; filename="${thumbnail.name}.jpg"`,
-				},
-				body: thumbnail.data,
-			};
-		}
-		return thumbnail;
-	}
-}
-```
-
-## 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 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,185 +0,0 @@
-# Programmatic Requests with Harper Tables
-
-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 Harper resources or scripts.
-
-```typescript
-const track = await tables.ExamplePeople.get(id) as ExamplePerson;
-```
-
-## Available Methods
-
-The following methods are available on each table object:
-
-### `get(idOrQuery)`
-
-Retrieves a single record by ID or multiple records matching a query.
-
-- **By ID**:
-  ```typescript
-  const person = await tables.ExamplePeople.get('person-123');
-  ```
-- **By Query**:
-  ```typescript
-  const albums = await tables.ExamplePeople.get({
-  	conditions: [{ attribute: 'name', value: 'John' }],
-  });
-  ```
-
-### `put(id, record)`
-
-Replaces an entire record with the provided data. If the record doesn't exist, it will be created.
-
-```typescript
-await tables.ExamplePeople.put('person-123', {
-	name: 'Michael Jackson',
-	tag: 'entertainer',
-});
-```
-
-### `patch(id, partialRecord)`
-
-Performs a partial update on a record. Only the specified fields will be updated.
-
-```typescript
-await tables.ExamplePeople.patch('person-123', {
-	tag: 'tragedy',
-});
-```
-
-### `delete(idOrQuery)`
-
-Deletes a record by ID or multiple records matching a query.
-
-```typescript
-await tables.ExamplePeople.delete('person-123');
-```
-
-### `post(record)`
-
-Creates a new record. Use this when you want the database to auto-generate a primary key.
-
-```typescript
-const newAlbum = await tables.ExamplePeople.post({
-	name: 'John Smith',
-	tag: 'anonymous',
-});
-```
-
-### `update(id, updates)`
-
-The `update` method is a versatile tool for modifying records. While it can perform simple partial updates like `patch`, its primary power lies in its ability to return an **Updatable Record** object for complex or atomic operations.
-
-#### Partial Update (like `patch`)
-
-When called with both an ID and an update object, it performs a partial update:
-
-```typescript
-await tables.ExamplePeople.update('person-123', {
-	name: 'Updated Name',
-});
-```
-
-#### Getting an Updatable Record
-
-When called without an update object (only an ID), `update` returns a reference to the record that can be modified directly.
-
-```typescript
-const person = await tables.ExamplePeople.update('person-123');
-person.name = 'New Person Name';
-// Properties can be assigned directly and are tracked
-```
-
-#### Atomic Operations
-
-Updatable records provide methods for safe, atomic modifications, which are essential for avoiding race conditions during increments or decrements:
-
-- `addTo(attribute, value)`: Atomically adds to a numeric value.
-- `subtractFrom(attribute, value)`: Atomically subtracts from a numeric value.
-
-```typescript
-const stats = await tables.Stats.update('daily');
-stats.addTo('viewCount', 1);
-```
-
-#### Update without an ID or with Context
-
-Calling `update()` without an ID can be used when the target is implied by the context (e.g., inside a resource method) or when you want to get an updatable reference to a collection.
-
-```typescript
-// Inside a custom resource method
-const record = await this.update();
-record.set('status', 'processed');
-
-// Passing specific context (like a transaction)
-const person = await tables.ExamplePeople.update('person-123', null, {
-	transaction,
-});
-person.addTo('playCount', 1);
-```
-
-### `search(query)`
-
-Performs a search based on the provided query criteria. It returns an `AsyncIterable` which is efficient for streaming large result sets.
-
-```typescript
-const results = await tables.ExamplePeople.search({
-	conditions: [{ attribute: 'artist', value: 'Michael Jackson' }],
-});
-
-for await (const person of results) {
-	console.log(person.name);
-}
-```
-
-### `subscribe(query)`
-
-Subscribes to real-time changes in the table. You can provide a query to filter which changes trigger a notification.
-
-```typescript
-const subscription = await tables.ExamplePeople.subscribe({
-	conditions: [{ attribute: 'name', value: 'Thriller' }],
-});
-
-for await (const event of subscription) {
-	console.log('Record changed:', event.value);
-}
-```
-
-### `publish(id, message)`
-
-Publishes a message to a specific record or topic. This triggers any active subscriptions without necessarily persisting data to the table.
-
-```typescript
-await tables.ExamplePeople.publish('person-123', {
-	type: 'REVALIDATE',
-	timestamp: Date.now(),
-});
-```
-
-## Querying Options
-
-Many methods accept a `Query` (or `RequestTarget`) object. Common options include:
-
-- `conditions`: Array of filter conditions.
-- `limit`: Number of records to return.
-- `offset`: Number of records to skip.
-- `sort`: Attribute and direction for sorting.
-- `select`: Array of specific attributes to return.
-
-Example of a complex query:
-
-```typescript
-const recentAlbums = await tables.ExamplePeople.get({
-	conditions: [{
-		attribute: 'releaseDate',
-		comparator: 'ge',
-		value: '2020-01-01',
-	}],
-	sort: { attribute: 'releaseDate', descending: true },
-	limit: 10,
-});
-```

package/skills/querying-rest-apis.md

@@ -1,69 +0,0 @@
-# Querying through REST APIs in Harper
-
-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
-
-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

@@ -1,75 +0,0 @@
-# Real-time Applications in Harper
-
-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
-
-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`
-
-```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**: Harper handles the efficient distribution of messages to subscribers.

package/skills/serving-web-content.md

@@ -1,82 +0,0 @@
-# Serving Web Content with Harper
-
-Harper provides two primary ways to include and serve HTTP web content such as HTML, CSS, JavaScript, and React applications. These methods are mutually exclusive.
-
-## 1. Using the Static Plugin
-
-The `static` plugin is the simplest way to serve static files. It maps a directory on your filesystem to your Harper REST endpoint.
-
-### Configuration
-
-Add the `static` configuration to your `config.yaml`:
-
-```yaml
-static:
-  files: 'web/*'
-```
-
-### Usage
-
-1. Create a `web` folder in your project root.
-2. Place your static files (e.g., `index.html`, `styles.css`, `app.js`) inside the `web` folder.
-3. Your files will be accessible from your REST endpoint. For example, if Harper is running on `http://localhost:9926/`, your `index.html` will be available at that address.
-
-### Key Characteristics
-
-- **Precedence**: Static files are searched first. If a matching file is found, it is served; otherwise, Harper proceeds to check your other resource and table APIs.
-- **No Directory Listings**: Browsing the directory structure via the browser is not supported.
-- **Simple Deployment**: Ideal for pre-built applications or simple static sites.
-
----
-
-## 2. Using the Vite Plugin
-
-The Vite plugin integrates Vite's development server directly into Harper, providing features like Hot Module Replacement (HMR) during development.
-
-### Configuration
-
-Add the Vite plugin to your `config.yaml`:
-
-```yaml
-'@harperfast/vite-plugin':
-  package: '@harperfast/vite-plugin'
-```
-
-### Setup
-
-This plugin expects a `vite.config.ts` and an `index.html` file in your project root. It handles rendering your app through Vite during development.
-
-### Package Configuration
-
-To use the Vite plugin effectively, you should configure your `package.json` with the appropriate scripts and dependencies.
-
-#### Scripts
-
-Copy these script examples to manage your development and deployment workflows:
-
-```json
-"scripts": {
-  "dev": "harper run .",
-  "build": "tsc -b && vite build",
-  "build-and-deploy": "rm -Rf deploy && npm run build && mkdir deploy && mv web deploy/ && cp -R deploy-template/* deploy/ && dotenv -- npm run deploy-web && rm -Rf deploy",
-  "deploy-web": "(cd deploy && harperdb deploy_component . project=web restart=rolling replicated=true)"
-}
-```
-
-#### Dependencies and Overrides
-
-Include the Vite plugin and other related dependencies in your `devDependencies`:
-
-```bash
-npm install --save-dev vite @harperfast/vite-plugin @vitejs/plugin-react dotenv-cli
-```
-
-### Deploying to Production
-
-Vite's HMR server is meant for development, not production. For that, the `build-and-deploy` script above builds the Vite app into a `web` folder, places the static handler, and then deploys that subdirectory as a Harper app to production.
-
-### Key Characteristics
-
-- **Development Experience**: Provides Vite's HMR for a fast development cycle.
-- **Integrated Rendering**: Automatically handles the rendering of your React/Vite app.
-- **Mutual Exclusivity**: Use this approach **instead of** the static plugin if you want Vite integration.

package/skills/typescript-type-stripping.md

@@ -1,47 +0,0 @@
-# TypeScript Type Stripping
-
-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, 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 Harper 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 Harper starts, it will detect the `.ts` files and, if running on a compatible Node.js version, will execute them using type stripping.