create-harper 0.12.3 → 0.13.0

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "create-harper",
 	"description": "Scaffold a new Harper project in JavaScript or TypeScript.",
-	"version": "0.12.3",
+	"version": "0.13.0",
 	"type": "module",
 	"author": {
 		"name": "HarperDB",

package/template-react/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,6 @@ 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.
+- [Caching](skills/caching.md): How caching is defined and implemented in Harper applications.
+- [Using Blobs](skills/using-blob-datatype.md): How to store and retrieve large data in HarperDB.
+- [Vector Indexing](skills/vector-indexing.md): How to define and use vector indexes for efficient similarity search.

package/template-react/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/template-react/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/template-react/skills/automatic-apis.md

@@ -0,0 +1,53 @@
+# 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.
+
+## Customizing Resources
+
+If the automatic APIs don't behave how you need, then you can look to [customize the resources](./custom-resources.md).

package/template-react/skills/caching.md

@@ -0,0 +1,113 @@
+# Harper Caching
+
+Harper includes integrated support for **caching data from external sources**, enabling high-performance, low-latency cache storage that is fully queryable and interoperable with your applications. With built-in caching capabilities and distributed responsiveness, Harper makes an ideal **data caching server** for both edge and centralized use cases.
+
+---
+
+## What is Harper Caching?
+
+Harper caching lets you store **cached content** in standard tables, enabling you to:
+
+- Expose cached entries as **queryable structured data** (e.g., JSON or CSV)
+- Serve data to clients with **flexible formats and custom querying**
+- Manage cache control with **timestamps and ETags** for downstream caching layers
+- Implement **active or passive caching** patterns depending on your source and invalidation strategy
+
+---
+
+## Configuring a Cache Table
+
+Define a cache table in your `schema.graphql`:
+
+```graphql
+type MyCache @table(expiration: 3600) @export {
+	id: ID @primaryKey
+}
+```
+
+- `expiration` is defined in seconds
+- Expired records are refreshed on access
+- Evicted records are removed after expiration
+
+---
+
+## Connecting an External Source
+
+Create a resource:
+
+```js
+import { Resource } from 'harperdb';
+
+export class ThirdPartyAPI extends Resource {
+	async get() {
+		const id = this.getId();
+		const response = await fetch(`https://api.example.com/items/${id}`);
+		if (!response.ok) {
+			throw new Error('Source fetch failed');
+		}
+		return await response.json();
+	}
+}
+```
+
+Attach it to your table:
+
+```js
+import { tables } from 'harperdb';
+import { ThirdPartyAPI } from './ThirdPartyAPI.js';
+
+const { MyCache } = tables;
+MyCache.sourcedFrom(ThirdPartyAPI);
+```
+
+---
+
+## Cache Behavior
+
+1. Fresh data is returned immediately
+2. Missing or stale data triggers a fetch
+3. Concurrent misses are deduplicated
+
+---
+
+## Active Caching
+
+Use `subscribe()` to proactively update or invalidate cache entries:
+
+```js
+class MyAPI extends Resource {
+	async *subscribe() {
+		// stream updates
+	}
+}
+```
+
+See [Real Time Apps](real-time-apps.md) for more details.
+
+---
+
+## Write-Through Caching
+
+Propagate updates upstream:
+
+```js
+class ThirdPartyAPI extends Resource {
+	async put(data) {
+		await fetch(`https://some-api.com/${this.getId()}`, {
+			method: 'PUT',
+			body: JSON.stringify(data),
+		});
+	}
+}
+```
+
+---
+
+## Summary
+
+Harper Caching allows you to:
+
+- Cache external APIs efficiently
+- Query cached data like native tables
+- Prevent cache stampedes
+- Build real-time or write-through caches

package/template-react/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,13 +174,108 @@ 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.
 
+## Token-based auth (JWT + refresh token) for non-browser clients
+
+Cookie-backed sessions are great for browser flows. For CLI tools, mobile apps, or other non-browser clients, it’s often easier to use **explicit tokens**:
+
+- **JWT (`operation_token`)**: short-lived bearer token used to authorize API requests.
+- **Refresh token (`refresh_token`)**: longer-lived token used to mint a new JWT when it expires.
+
+This project includes two Resource patterns for that flow:
+
+### Issuing tokens: `IssueTokens`
+
+**Description / use case:** Generate `{ refreshToken, jwt }` either:
+
+- with an existing Authorization token (either Basic Auth or a JWT) and you want to issue new tokens, or
+- from an explicit `{ username, password }` payload (useful for direct “login” from a CLI/mobile client).
+
+```
+js
+export class IssueTokens extends Resource {
+static loadAsInstance = false;
+
+	async get(target) {
+		const { refresh_token: refreshToken, operation_token: jwt } =
+			await databases.system.hdb_user.operation(
+				{ operation: 'create_authentication_tokens' },
+				this.getContext(),
+			);
+		return { refreshToken, jwt };
+	}
+
+	async post(target, data) {
+		if (!data.username || !data.password) {
+			throw new Error('username and password are required');
+		}
+
+		const { refresh_token: refreshToken, operation_token: jwt } =
+			await databases.system.hdb_user.operation({
+				operation: 'create_authentication_tokens',
+				username: data.username,
+				password: data.password,
+			});
+		return { refreshToken, jwt };
+	}
+}
+```
+
+**Recommended documentation notes to include:**
+
+- `GET` variant: intended for “I already have an Authorization token, give me new tokens”.
+- `POST` variant: intended for “I have credentials, give me tokens”.
+- Response shape:
+  - `refreshToken`: store securely (long-lived).
+  - `jwt`: attach to requests (short-lived).
+
+### Refreshing a JWT: `RefreshJWT`
+
+**Description / use case:** When the JWT expires, the client uses the refresh token to get a new JWT without re-supplying username/password.
+
+```
+js
+export class RefreshJWT extends Resource {
+static loadAsInstance = false;
+
+	async post(target, data) {
+		if (!data.refreshToken) {
+			throw new Error('refreshToken is required');
+		}
+
+		const { operation_token: jwt } = await databases.system.hdb_user.operation({
+			operation: 'refresh_operation_token',
+			refresh_token: data.refreshToken,
+		});
+		return { jwt };
+	}
+}
+```
+
+**Recommended documentation notes to include:**
+
+- Requires `refreshToken` in the request body.
+- Returns a new `{ jwt }`.
+- If refresh fails (expired/revoked), client must re-authenticate (e.g., call `IssueTokens.post` again).
+
+### Suggested client flow (high-level)
+
+1. **Sign in (token flow)**
+   - POST /IssueTokens/ with a body of `{ "username": "your username", "password": "your password" }` or GET /IssueTokens/ with an existing Authorization token.
+   - Receive `{ jwt, refreshToken }` in the response
+2. **Call protected APIs**
+   - Send the JWT with each request in the Authorization header (as your auth mechanism expects)
+3. **JWT expires**
+   - POST /RefreshJWT/ with a body of `{ "refreshToken": "your refresh token" }`.
+   - Receive `{ jwt }` in the response and continue
+
 ## Quick checklist
 
 - [ ] Public endpoints explicitly `allowRead`/`allowCreate` as needed.
 - [ ] 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.
+- [ ] If using tokens: `IssueTokens` issues `{ jwt, refreshToken }`, `RefreshJWT` refreshes `{ jwt }` with a `refreshToken`.

package/template-react/skills/custom-resources.md

@@ -1,8 +1,12 @@
-# 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.
+
+## Do you need a custom resource?
+
+Exported tables have [automatic APIs](./automatic-apis.md) as a part of them. These APIs may be enough for what you need. Take a look at [extendings tables](./extending-tables.md) to learn more about resources with a backing table.
 
 ## Defining a Custom Resource
 
@@ -21,7 +25,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 +83,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/template-react/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/template-react/skills/extending-tables.md

@@ -1,6 +1,10 @@
-# 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.
+
+## 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
 
@@ -53,7 +57,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/template-react/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/template-react/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/template-react/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/template-react/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/template-react/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.

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

@@ -0,0 +1,131 @@
+# 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