@mastra/cloudflare 0.1.0-alpha.5 → 0.1.0-alpha.7

package/README.md

@@ -0,0 +1,175 @@
+# @mastra/cloudflare
+
+Cloudflare KV store for Mastra, providing scalable and serverless storage for threads, messages, workflow snapshots, and evaluations. Supports both Cloudflare Workers KV Bindings and the REST API for flexible deployment in serverless and Node.js environments.
+
+## Installation
+
+```bash
+npm install @mastra/cloudflare
+```
+
+## Prerequisites
+
+- Cloudflare account with KV namespaces set up
+- Node.js 16 or higher
+- (Optional) Cloudflare Worker for Workers API mode
+
+## Usage
+
+```typescript
+import { CloudflareStore } from '@mastra/cloudflare';
+
+// Using Workers Binding API
+const store = new CloudflareStore({
+  bindings: {
+    threads: THREADS_KV_NAMESPACE,
+    messages: MESSAGES_KV_NAMESPACE,
+    workflow_snapshot: WORKFLOW_KV_NAMESPACE,
+    evals: EVALS_KV_NAMESPACE,
+    traces: TRACES_KV_NAMESPACE,
+  },
+  keyPrefix: 'myapp_', // Optional
+});
+
+// Or using REST API
+const store = new CloudflareStore({
+  accountId: process.env.CLOUDFLARE_ACCOUNT_ID!,
+  apiToken: process.env.CLOUDFLARE_API_TOKEN!,
+  namespacePrefix: 'myapp_', // Optional
+});
+
+// Save a thread
+await store.saveThread({
+  id: 'thread-123',
+  resourceId: 'resource-456',
+  title: 'My Thread',
+  metadata: { key: 'value' },
+  createdAt: new Date(),
+  updatedAt: new Date(),
+});
+
+// Add messages
+await store.saveMessages({
+  messages: [
+    {
+      id: 'msg-1',
+      threadId: 'thread-123',
+      content: 'Hello Cloudflare!',
+      role: 'user',
+      createdAt: new Date(),
+    },
+  ],
+});
+
+// Query messages
+const messages = await store.getMessages({ threadId: 'thread-123' });
+```
+
+## Configuration
+
+- **Workers API**: Use the `bindings` option to pass KV namespaces directly (for Cloudflare Workers).
+- **REST API**: Use `accountId`, `apiToken`, and (optionally) `namespacePrefix` for server-side usage.
+- `keyPrefix`/`namespacePrefix`: Useful for isolating environments (e.g., dev/test/prod).
+
+## Features
+
+### Storage Features
+
+- Thread and message storage with JSON support
+- Rich metadata support (JSON-encoded)
+- Timestamp tracking for all records
+- Workflow snapshot persistence
+- Trace and evaluation storage
+- Sorted message order using simulated sorted sets
+- Supports both Cloudflare Workers KV Bindings and REST API
+- Automatic JSON serialization/deserialization for metadata and custom fields
+- Error handling and logging for all operations
+
+### Consistency & Performance
+
+- Eventually consistent (see Limitations)
+- Low-latency access via Workers Binding API
+- Scalable and serverless
+
+## Supported Methods
+
+### Thread Operations
+
+- `saveThread(thread)`: Create or update a thread
+- `getThreadById({ threadId })`: Get a thread by ID
+- `getThreadsByResourceId({ resourceId })`: Fetch all threads associated with a resource.
+- `updateThread({ id, title, metadata })`: Update thread title and metadata
+- `deleteThread({ threadId })`: Delete a thread and its messages
+
+### Message Operations
+
+- `saveMessages({ messages })`: Save multiple messages
+- `getMessages({ threadId, selectBy? })`: Get messages for a thread with optional filtering (last N, includes, etc)
+
+### Workflow Operations
+
+- `persistWorkflowSnapshot({ workflowName, runId, snapshot })`: Save workflow state for a given workflow/run.
+- `loadWorkflowSnapshot({ workflowName, runId })`: Load ed workflow state.
+
+### Trace Operations
+
+- `getTraces({ name?, scope?, page, perPage, attributes? })`: Query trace records with optional filters and pagination.
+
+### Utility
+
+- `clearTable({ tableName })`: Remove all records from a logical table
+- `batchInsert({ tableName, records })`: Batch insert multiple records.
+- `insert({ tableName, record })`: Insert a single record into a table.
+
+## Data Types
+
+- `text`: String
+- `timestamp`: ISO8601 string (converted to/from Date)
+- `uuid`: String
+- `jsonb`: JSON-encoded object
+
+All records are stored as JSON in KV, with automatic serialization/deserialization for metadata, arrays, and custom fields.
+
+## Configuration Reference
+
+- **Workers Binding API**: Use the `bindings` option to pass KV namespaces directly (for Cloudflare Workers).
+- **REST API**: Use `accountId`, `apiToken`, and (optionally) `namespacePrefix` for server-side usage.
+- `keyPrefix`/`namespacePrefix`: Useful for isolating environments (e.g., dev/test/prod).
+
+Example:
+
+```typescript
+const store = new CloudflareStore({
+  bindings: { ... }, // for Workers
+  keyPrefix: 'dev_',
+});
+// or
+const store = new CloudflareStore({
+  accountId: '...',
+  apiToken: '...',
+  namespacePrefix: 'prod_',
+});
+```
+
+## Table/Namespace Mapping
+
+Each logical Mastra table (threads, messages, workflow_snapshot, evals, traces) maps to a separate KV namespace. Keys are structured as `${prefix}${tableName}:${primaryKey}` or `${prefix}${tableName}:${threadId}:${messageId}` for messages. The prefix is set by `keyPrefix`/`namespacePrefix`.
+
+## Limitations
+
+- **Eventual Consistency:** Cloudflare KV is eventually consistent; concurrent operations may not be immediately visible across all reads.
+- **No Transactions:** Atomic multi-key operations are not supported.
+- **Rate Limits:** Large objects or high-frequency updates may be subject to Cloudflare KV rate limits.
+- **Query Limitations:** No native querying; all filtering is done in-memory after fetching keys/records.
+- **Best for:** Use for serverless, low-latency, and moderate-volume workloads. For relational or strongly consistent needs, consider D1 or a SQL backend.
+
+## Cloudflare-Specific Notes
+
+- **Workers Binding API** is recommended for production Workers deployments (low-latency, no API token required at runtime).
+- **REST API** is ideal for server-side Node.js or test environments.
+- Ensure your KV namespaces are provisioned and accessible by your Worker or API token.
+- Namespaces and keys are automatically created as needed.
+
+## Cleanup/Disconnect
+
+No explicit cleanup or disconnect is required; Cloudflare KV is fully managed.

package/dist/_tsup-dts-rollup.d.cts

@@ -3,6 +3,7 @@ import type { KVNamespace as KVNamespace_2 } from '@cloudflare/workers-types';
 import { KVNamespaceListKey as KVNamespaceListKey_2 } from '@cloudflare/workers-types';
 import { MastraStorage } from '@mastra/core/storage';
 import type { MessageType } from '@mastra/core/memory';
+import type { MessageType as MessageType_2 } from '@mastra/core';
 import type { StorageColumn } from '@mastra/core/storage';
 import type { StorageGetMessagesArg } from '@mastra/core/storage';
 import type { StorageThreadType } from '@mastra/core/memory';
@@ -14,6 +15,7 @@ import type { TABLE_TRACES } from '@mastra/core/storage';
 import type { TABLE_WORKFLOW_SNAPSHOT } from '@mastra/core/storage';
 import type { WorkflowRuns } from '@mastra/core/storage';
 import type { WorkflowRunState } from '@mastra/core/workflows';
+import type { WorkflowRunState as WorkflowRunState_2 } from '@mastra/core';
 
 /**
  * Configuration for Cloudflare KV using REST API
@@ -190,6 +192,19 @@ export declare interface CloudflareWorkersConfig {
     keyPrefix?: string;
 }
 
+export declare const createSampleMessage: (threadId: string) => MessageType_2;
+
+export declare const createSampleThread: () => {
+    id: string;
+    resourceId: string;
+    title: string;
+    createdAt: Date;
+    updatedAt: Date;
+    metadata: {
+        key: string;
+    };
+};
+
 export declare const createSampleTrace: (name: string, scope?: string, attributes?: Record<string, string>) => {
     id: string;
     parentSpanId: string;
@@ -207,6 +222,8 @@ export declare const createSampleTrace: (name: string, scope?: string, attribute
     createdAt: string;
 };
 
+export declare const createSampleWorkflowSnapshot: (threadId: string) => WorkflowRunState_2;
+
 /**
  * Helper to determine if a config is using Workers bindings
  */
@@ -234,4 +251,7 @@ export declare type RecordTypes = {
     [TABLE_TRACES]: any;
 };
 
+export declare const retryUntil: <T>(fn: () => Promise<T>, condition: (result: T) => boolean, timeout?: number, // REST API needs longer timeout due to higher latency
+interval?: number) => Promise<T>;
+
 export { }

package/dist/_tsup-dts-rollup.d.ts

@@ -3,6 +3,7 @@ import type { KVNamespace as KVNamespace_2 } from '@cloudflare/workers-types';
 import { KVNamespaceListKey as KVNamespaceListKey_2 } from '@cloudflare/workers-types';
 import { MastraStorage } from '@mastra/core/storage';
 import type { MessageType } from '@mastra/core/memory';
+import type { MessageType as MessageType_2 } from '@mastra/core';
 import type { StorageColumn } from '@mastra/core/storage';
 import type { StorageGetMessagesArg } from '@mastra/core/storage';
 import type { StorageThreadType } from '@mastra/core/memory';
@@ -14,6 +15,7 @@ import type { TABLE_TRACES } from '@mastra/core/storage';
 import type { TABLE_WORKFLOW_SNAPSHOT } from '@mastra/core/storage';
 import type { WorkflowRuns } from '@mastra/core/storage';
 import type { WorkflowRunState } from '@mastra/core/workflows';
+import type { WorkflowRunState as WorkflowRunState_2 } from '@mastra/core';
 
 /**
  * Configuration for Cloudflare KV using REST API
@@ -190,6 +192,19 @@ export declare interface CloudflareWorkersConfig {
     keyPrefix?: string;
 }
 
+export declare const createSampleMessage: (threadId: string) => MessageType_2;
+
+export declare const createSampleThread: () => {
+    id: string;
+    resourceId: string;
+    title: string;
+    createdAt: Date;
+    updatedAt: Date;
+    metadata: {
+        key: string;
+    };
+};
+
 export declare const createSampleTrace: (name: string, scope?: string, attributes?: Record<string, string>) => {
     id: string;
     parentSpanId: string;
@@ -207,6 +222,8 @@ export declare const createSampleTrace: (name: string, scope?: string, attribute
     createdAt: string;
 };
 
+export declare const createSampleWorkflowSnapshot: (threadId: string) => WorkflowRunState_2;
+
 /**
  * Helper to determine if a config is using Workers bindings
  */
@@ -234,4 +251,7 @@ export declare type RecordTypes = {
     [TABLE_TRACES]: any;
 };
 
+export declare const retryUntil: <T>(fn: () => Promise<T>, condition: (result: T) => boolean, timeout?: number, // REST API needs longer timeout due to higher latency
+interval?: number) => Promise<T>;
+
 export { }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/cloudflare",
-  "version": "0.1.0-alpha.5",
+  "version": "0.1.0-alpha.7",
   "description": "Cloudflare provider for Mastra - includes db storage capabilities",
   "type": "module",
   "files": [
@@ -24,7 +24,7 @@
   "license": "MIT",
   "dependencies": {
     "cloudflare": "^4.1.0",
-    "@mastra/core": "^0.9.0-alpha.5"
+    "@mastra/core": "^0.9.0-alpha.7"
   },
   "devDependencies": {
     "@cloudflare/workers-types": "^4.20250313.0",