@mastra/cloudflare-d1 1.0.0-beta.8 → 1.0.0

package/dist/docs/README.md

@@ -0,0 +1,31 @@
+# @mastra/cloudflare-d1 Documentation
+
+> Embedded documentation for coding agents
+
+## Quick Start
+
+```bash
+# Read the skill overview
+cat docs/SKILL.md
+
+# Get the source map
+cat docs/SOURCE_MAP.json
+
+# Read topic documentation
+cat docs/<topic>/01-overview.md
+```
+
+## Structure
+
+```
+docs/
+├── SKILL.md           # Entry point
+├── README.md          # This file
+├── SOURCE_MAP.json    # Export index
+├── storage/ (1 files)
+```
+
+## Version
+
+Package: @mastra/cloudflare-d1
+Version: 1.0.0

package/dist/docs/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: mastra-cloudflare-d1-docs
+description: Documentation for @mastra/cloudflare-d1. Includes links to type definitions and readable implementation code in dist/.
+---
+
+# @mastra/cloudflare-d1 Documentation
+
+> **Version**: 1.0.0
+> **Package**: @mastra/cloudflare-d1
+
+## Quick Navigation
+
+Use SOURCE_MAP.json to find any export:
+
+```bash
+cat docs/SOURCE_MAP.json
+```
+
+Each export maps to:
+- **types**: `.d.ts` file with JSDoc and API signatures
+- **implementation**: `.js` chunk file with readable source
+- **docs**: Conceptual documentation in `docs/`
+
+## Top Exports
+
+
+
+See SOURCE_MAP.json for the complete list.
+
+## Available Topics
+
+- [Storage](storage/) - 1 file(s)

package/dist/docs/SOURCE_MAP.json

@@ -0,0 +1,6 @@
+{
+  "version": "1.0.0",
+  "package": "@mastra/cloudflare-d1",
+  "exports": {},
+  "modules": {}
+}

package/dist/docs/storage/01-reference.md

@@ -0,0 +1,110 @@
+# Storage API Reference
+
+> API reference for storage - 1 entries
+
+
+---
+
+## Reference: Cloudflare D1 Storage
+
+> Documentation for the Cloudflare D1 SQL storage implementation in Mastra.
+
+The Cloudflare D1 storage implementation provides a serverless SQL database solution using Cloudflare D1, supporting relational operations and transactional consistency.
+
+## Installation
+
+```bash
+npm install @mastra/cloudflare-d1@beta
+```
+
+## Usage
+
+```typescript
+import { D1Store } from "@mastra/cloudflare-d1";
+
+type Env = {
+  // Add your bindings here, e.g. Workers KV, D1, Workers AI, etc.
+  D1Database: D1Database;
+};
+
+// --- Example 1: Using Workers Binding ---
+const storageWorkers = new D1Store({
+  binding: D1Database, // D1Database binding provided by the Workers runtime
+  tablePrefix: "dev_", // Optional: isolate tables per environment
+});
+
+// --- Example 2: Using REST API ---
+const storageRest = new D1Store({
+  accountId: process.env.CLOUDFLARE_ACCOUNT_ID!, // Cloudflare Account ID
+  databaseId: process.env.CLOUDFLARE_D1_DATABASE_ID!, // D1 Database ID
+  apiToken: process.env.CLOUDFLARE_API_TOKEN!, // Cloudflare API Token
+  tablePrefix: "dev_", // Optional: isolate tables per environment
+});
+```
+
+And add the following to your `wrangler.toml` or `wrangler.jsonc` file:
+
+```
+[[d1_databases]]
+binding = "D1Database"
+database_name = "db-name"
+database_id = "db-id"
+```
+
+## Parameters
+
+## Additional Notes
+
+### Schema Management
+
+The storage implementation handles schema creation and updates automatically. It creates the following tables:
+
+- `threads`: Stores conversation threads
+- `messages`: Stores individual messages
+- `metadata`: Stores additional metadata for threads and messages
+
+### Initialization
+
+When you pass storage to the Mastra class, `init()` is called automatically before any storage operation:
+
+```typescript
+import { Mastra } from "@mastra/core";
+import { D1Store } from "@mastra/cloudflare-d1";
+
+const storage = new D1Store({
+  binding: D1Database,
+});
+
+const mastra = new Mastra({
+  storage, // init() is called automatically
+});
+```
+
+If you're using storage directly without Mastra, you must call `init()` explicitly to create the tables:
+
+```typescript
+import { D1Store } from "@mastra/cloudflare-d1";
+
+const storage = new D1Store({
+  id: 'd1-storage',
+  binding: D1Database,
+});
+
+// Required when using storage directly
+await storage.init();
+
+// Access domain-specific stores via getStore()
+const memoryStore = await storage.getStore('memory');
+const thread = await memoryStore?.getThreadById({ threadId: "..." });
+```
+
+> **Note:**
+If `init()` is not called, tables won't be created and storage operations will fail silently or throw errors.
+
+### Transactions & Consistency
+
+Cloudflare D1 provides transactional guarantees for single-row operations. This means that multiple operations can be executed as a single, all-or-nothing unit of work.
+
+### Table Creation & Migrations
+
+Tables are created automatically when storage is initialized (and can be isolated per environment using the `tablePrefix` option), but advanced schema changes—such as adding columns, changing data types, or modifying indexes—require manual migration and careful planning to avoid data loss.

package/dist/index.cjs

@@ -846,18 +846,33 @@ var MemoryStorageD1 = class extends storage.MemoryStorage {
       return null;
     }
   }
-  async listThreadsByResourceId(args) {
-    const { resourceId, page = 0, perPage: perPageInput, orderBy } = args;
+  async listThreads(args) {
+    const { page = 0, perPage: perPageInput, orderBy, filter } = args;
+    try {
+      this.validatePaginationInput(page, perPageInput ?? 100);
+    } catch (error$1) {
+      throw new error.MastraError(
+        {
+          id: storage.createStorageErrorId("CLOUDFLARE_D1", "LIST_THREADS", "INVALID_PAGE"),
+          domain: error.ErrorDomain.STORAGE,
+          category: error.ErrorCategory.USER,
+          details: { page, ...perPageInput !== void 0 && { perPage: perPageInput } }
+        },
+        error$1 instanceof Error ? error$1 : new Error("Invalid pagination parameters")
+      );
+    }
     const perPage = storage.normalizePerPage(perPageInput, 100);
-    if (page < 0) {
+    try {
+      this.validateMetadataKeys(filter?.metadata);
+    } catch (error$1) {
       throw new error.MastraError(
         {
-          id: storage.createStorageErrorId("CLOUDFLARE_D1", "LIST_THREADS_BY_RESOURCE_ID", "INVALID_PAGE"),
+          id: storage.createStorageErrorId("CLOUDFLARE_D1", "LIST_THREADS", "INVALID_METADATA_KEY"),
           domain: error.ErrorDomain.STORAGE,
           category: error.ErrorCategory.USER,
-          details: { page }
+          details: { metadataKeys: filter?.metadata ? Object.keys(filter.metadata).join(", ") : "" }
         },
-        new Error("page must be >= 0")
+        error$1 instanceof Error ? error$1 : new Error("Invalid metadata key")
       );
     }
     const { offset, perPage: perPageForResponse } = storage.calculatePagination(page, perPageInput, perPage);
@@ -870,11 +885,51 @@ var MemoryStorageD1 = class extends storage.MemoryStorage {
       metadata: typeof row.metadata === "string" ? JSON.parse(row.metadata || "{}") : row.metadata || {}
     });
     try {
-      const countQuery = createSqlBuilder().count().from(fullTableName).where("resourceId = ?", resourceId);
+      let countQuery = createSqlBuilder().count().from(fullTableName);
+      let selectQuery = createSqlBuilder().select("*").from(fullTableName);
+      if (filter?.resourceId) {
+        countQuery = countQuery.whereAnd("resourceId = ?", filter.resourceId);
+        selectQuery = selectQuery.whereAnd("resourceId = ?", filter.resourceId);
+      }
+      if (filter?.metadata && Object.keys(filter.metadata).length > 0) {
+        for (const [key, value] of Object.entries(filter.metadata)) {
+          if (value !== null && typeof value === "object") {
+            throw new error.MastraError(
+              {
+                id: storage.createStorageErrorId("CLOUDFLARE_D1", "LIST_THREADS", "INVALID_METADATA_VALUE"),
+                domain: error.ErrorDomain.STORAGE,
+                category: error.ErrorCategory.USER,
+                text: `Metadata filter value for key "${key}" must be a scalar type (string, number, boolean, or null), got ${Array.isArray(value) ? "array" : "object"}`,
+                details: { key, valueType: Array.isArray(value) ? "array" : "object" }
+              },
+              new Error("Invalid metadata filter value type")
+            );
+          }
+          if (value === null) {
+            const condition = `json_extract(metadata, '$.${key}') IS NULL`;
+            countQuery = countQuery.whereAnd(condition);
+            selectQuery = selectQuery.whereAnd(condition);
+          } else {
+            const condition = `json_extract(metadata, '$.${key}') = ?`;
+            const filterValue = value;
+            countQuery = countQuery.whereAnd(condition, filterValue);
+            selectQuery = selectQuery.whereAnd(condition, filterValue);
+          }
+        }
+      }
       const countResult = await this.#db.executeQuery(countQuery.build());
       const total = Number(countResult?.[0]?.count ?? 0);
+      if (total === 0) {
+        return {
+          threads: [],
+          total: 0,
+          page,
+          perPage: perPageForResponse,
+          hasMore: false
+        };
+      }
       const limitValue = perPageInput === false ? total : perPage;
-      const selectQuery = createSqlBuilder().select("*").from(fullTableName).where("resourceId = ?", resourceId).orderBy(field, direction).limit(limitValue).offset(offset);
+      selectQuery = selectQuery.orderBy(field, direction).limit(limitValue).offset(offset);
       const results = await this.#db.executeQuery(selectQuery.build());
       const threads = results.map(mapRowToStorageThreadType);
       return {
@@ -885,13 +940,19 @@ var MemoryStorageD1 = class extends storage.MemoryStorage {
         hasMore: perPageInput === false ? false : offset + perPage < total
       };
     } catch (error$1) {
+      if (error$1 instanceof error.MastraError && error$1.category === error.ErrorCategory.USER) {
+        throw error$1;
+      }
       const mastraError = new error.MastraError(
         {
-          id: storage.createStorageErrorId("CLOUDFLARE_D1", "LIST_THREADS_BY_RESOURCE_ID", "FAILED"),
+          id: storage.createStorageErrorId("CLOUDFLARE_D1", "LIST_THREADS", "FAILED"),
           domain: error.ErrorDomain.STORAGE,
           category: error.ErrorCategory.THIRD_PARTY,
-          text: `Error getting threads by resourceId ${resourceId}: ${error$1 instanceof Error ? error$1.message : String(error$1)}`,
-          details: { resourceId }
+          text: `Error listing threads: ${error$1 instanceof Error ? error$1.message : String(error$1)}`,
+          details: {
+            ...filter?.resourceId && { resourceId: filter.resourceId },
+            hasMetadataFilter: !!filter?.metadata
+          }
         },
         error$1
       );
@@ -1211,12 +1272,14 @@ var MemoryStorageD1 = class extends storage.MemoryStorage {
       const dateRange = filter?.dateRange;
       if (dateRange?.start) {
         const startDate = dateRange.start instanceof Date ? storage.serializeDate(dateRange.start) : storage.serializeDate(new Date(dateRange.start));
-        query += ` AND createdAt >= ?`;
+        const startOp = dateRange.startExclusive ? ">" : ">=";
+        query += ` AND createdAt ${startOp} ?`;
         queryParams.push(startDate);
       }
       if (dateRange?.end) {
         const endDate = dateRange.end instanceof Date ? storage.serializeDate(dateRange.end) : storage.serializeDate(new Date(dateRange.end));
-        query += ` AND createdAt <= ?`;
+        const endOp = dateRange.endExclusive ? "<" : "<=";
+        query += ` AND createdAt ${endOp} ?`;
         queryParams.push(endDate);
       }
       const { field, direction } = this.parseOrderBy(orderBy, "ASC");
@@ -1243,12 +1306,14 @@ var MemoryStorageD1 = class extends storage.MemoryStorage {
       }
       if (dateRange?.start) {
         const startDate = dateRange.start instanceof Date ? storage.serializeDate(dateRange.start) : storage.serializeDate(new Date(dateRange.start));
-        countQuery += ` AND createdAt >= ?`;
+        const startOp = dateRange.startExclusive ? ">" : ">=";
+        countQuery += ` AND createdAt ${startOp} ?`;
         countParams.push(startDate);
       }
       if (dateRange?.end) {
         const endDate = dateRange.end instanceof Date ? storage.serializeDate(dateRange.end) : storage.serializeDate(new Date(dateRange.end));
-        countQuery += ` AND createdAt <= ?`;
+        const endOp = dateRange.endExclusive ? "<" : "<=";
+        countQuery += ` AND createdAt ${endOp} ?`;
         countParams.push(endDate);
       }
       const countResult = await this.#db.executeQuery({ sql: countQuery, params: countParams });
@@ -1887,7 +1952,7 @@ var WorkflowsStorageD1 = class extends storage.WorkflowsStorage {
       try {
         parsedSnapshot = JSON.parse(row.snapshot);
       } catch (e) {
-        console.warn(`Failed to parse snapshot for workflow ${row.workflow_name}: ${e}`);
+        this.logger.warn(`Failed to parse snapshot for workflow ${row.workflow_name}: ${e}`);
       }
     }
     return {
@@ -1923,7 +1988,7 @@ var WorkflowsStorageD1 = class extends storage.WorkflowsStorage {
           builder.whereAnd("resourceId = ?", resourceId);
           countBuilder.whereAnd("resourceId = ?", resourceId);
         } else {
-          console.warn(`[${fullTableName}] resourceId column not found. Skipping resourceId filter.`);
+          this.logger.warn(`[${fullTableName}] resourceId column not found. Skipping resourceId filter.`);
         }
       }
       if (fromDate) {
@@ -2026,7 +2091,7 @@ var WorkflowsStorageD1 = class extends storage.WorkflowsStorage {
 };
 
 // src/storage/index.ts
-var D1Store = class extends storage.MastraStorage {
+var D1Store = class extends storage.MastraCompositeStore {
   client;
   binding;
   tablePrefix;