create-harper 1.2.2 → 1.3.0

package/template-vanilla/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/template-vanilla/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/template-vanilla/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/template-vanilla/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/template-vanilla/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.

package/template-vanilla/skills/using-blob-datatype.md

@@ -1,131 +0,0 @@
-# Blob (Binary Large Objects)
-
-Harper supports **Blobs** — binary large objects for storing unstructured or large binary data — with integrated streaming support and efficient storage. Blobs are ideal for media files, documents, and any data where size or throughput makes standard JSON fields impractical.
-
----
-
-## What Are Blobs
-
-Blobs extend the native JavaScript `Blob` type and allow you to store **binary or arbitrary data** inside Harper tables. The blob reference is stored in the record, while the blob’s contents are streamed to and from storage.
-
-- Designed for binary data such as images, audio, and documents
-- Supports streaming reads and writes
-- Blob data is stored separately from record attributes
-- Optimized for large payloads
-
----
-
-## Defining Blob Fields
-
-Declare a blob field using the `Blob` type in your schema:
-
-```graphql
-type MyTable @table {
-	id: ID @primaryKey
-	data: Blob
-}
-```
-
-Any record written to this field will store a reference to the blob’s contents.
-
----
-
-## Creating and Storing Blobs
-
-### Creating a Blob from a Buffer
-
-```js
-const blob = createBlob(largeBuffer);
-await MyTable.put({ id: 'my-record', data: blob });
-```
-
-- `createBlob()` returns a blob reference
-- Data is streamed to storage asynchronously
-- Records may be committed before the blob finishes writing
-
----
-
-### Creating a Blob from a Stream
-
-```js
-const blob = createBlob(stream);
-await MyTable.put({ id: 'streamed-record', data: blob });
-```
-
-Streaming allows large data to be written without loading it fully into memory.
-
----
-
-## Reading Blob Data
-
-Retrieve a record and read its blob contents:
-
-```js
-const record = await MyTable.get('my-record');
-const buffer = await record.data.bytes();
-```
-
-Blob objects also support streaming interfaces for large reads.
-
----
-
-## Blob Attributes and Events
-
-### Size
-
-The blob size may not be immediately available when streaming:
-
-```js
-if (blob.size === undefined) {
-	blob.on('size', size => {
-		console.log('Blob size:', size);
-	});
-}
-```
-
----
-
-### saveBeforeCommit
-
-Blobs are not atomic while streaming. To ensure the blob is fully written before committing the record:
-
-```js
-const blob = createBlob(stream, { saveBeforeCommit: true });
-await MyTable.put({ id: 'safe-record', data: blob });
-```
-
----
-
-## Error Handling
-
-Handle streaming errors by attaching an error listener:
-
-```js
-blob.on('error', () => {
-	MyTable.invalidate('my-record');
-});
-```
-
-This prevents partially written blobs from being used.
-
----
-
-## Automatic Coercion
-
-When a field is defined as `Blob`, assigning a string or buffer automatically converts it into a blob when using `put`, `patch`, or `publish`.
-
----
-
-## Related Skill
-
-- [Handling Binary Data with Blobs](handling-binary-data.md) How to store and serve binary data like images or MP3s using the Blob data type.
-
----
-
-## Summary
-
-- Blobs store large or binary data efficiently
-- Blob fields reference streamed content
-- Supports buffered and streamed writes
-- Optional write-before-commit behavior
-- Integrates seamlessly with Harper tables