@mastra/cloudflare-d1 1.0.0-beta.7 → 1.0.0-beta.9

package/CHANGELOG.md

@@ -1,5 +1,94 @@
 # @mastra/cloudflare-d1
 
+## 1.0.0-beta.9
+
+### Patch Changes
+
+- Add embedded documentation support for Mastra packages ([#11472](https://github.com/mastra-ai/mastra/pull/11472))
+
+  Mastra packages now include embedded documentation in the published npm package under `dist/docs/`. This enables coding agents and AI assistants to understand and use the framework by reading documentation directly from `node_modules`.
+
+  Each package includes:
+  - **SKILL.md** - Entry point explaining the package's purpose and capabilities
+  - **SOURCE_MAP.json** - Machine-readable index mapping exports to types and implementation files
+  - **Topic folders** - Conceptual documentation organized by feature area
+
+  Documentation is driven by the `packages` frontmatter field in MDX files, which maps docs to their corresponding packages. CI validation ensures all docs include this field.
+
+- Added `startExclusive` and `endExclusive` options to `dateRange` filter for message queries. ([#11479](https://github.com/mastra-ai/mastra/pull/11479))
+
+  **What changed:** The `filter.dateRange` parameter in `listMessages()` and `Memory.recall()` now supports `startExclusive` and `endExclusive` boolean options. When set to `true`, messages with timestamps exactly matching the boundary are excluded from results.
+
+  **Why this matters:** Enables cursor-based pagination for chat applications. When new messages arrive during a session, offset-based pagination can skip or duplicate messages. Using `endExclusive: true` with the oldest message's timestamp as a cursor ensures consistent pagination without gaps or duplicates.
+
+  **Example:**
+
+  ```typescript
+  // Get first page
+  const page1 = await memory.recall({
+    threadId: 'thread-123',
+    perPage: 10,
+    orderBy: { field: 'createdAt', direction: 'DESC' },
+  });
+
+  // Get next page using cursor-based pagination
+  const oldestMessage = page1.messages[page1.messages.length - 1];
+  const page2 = await memory.recall({
+    threadId: 'thread-123',
+    perPage: 10,
+    orderBy: { field: 'createdAt', direction: 'DESC' },
+    filter: {
+      dateRange: {
+        end: oldestMessage.createdAt,
+        endExclusive: true, // Excludes the cursor message
+      },
+    },
+  });
+  ```
+
+- Updated dependencies [[`d2d3e22`](https://github.com/mastra-ai/mastra/commit/d2d3e22a419ee243f8812a84e3453dd44365ecb0), [`bc72b52`](https://github.com/mastra-ai/mastra/commit/bc72b529ee4478fe89ecd85a8be47ce0127b82a0), [`05b8bee`](https://github.com/mastra-ai/mastra/commit/05b8bee9e50e6c2a4a2bf210eca25ee212ca24fa), [`c042bd0`](https://github.com/mastra-ai/mastra/commit/c042bd0b743e0e86199d0cb83344ca7690e34a9c), [`940a2b2`](https://github.com/mastra-ai/mastra/commit/940a2b27480626ed7e74f55806dcd2181c1dd0c2), [`e0941c3`](https://github.com/mastra-ai/mastra/commit/e0941c3d7fc75695d5d258e7008fd5d6e650800c), [`0c0580a`](https://github.com/mastra-ai/mastra/commit/0c0580a42f697cd2a7d5973f25bfe7da9055038a), [`28f5f89`](https://github.com/mastra-ai/mastra/commit/28f5f89705f2409921e3c45178796c0e0d0bbb64), [`e601b27`](https://github.com/mastra-ai/mastra/commit/e601b272c70f3a5ecca610373aa6223012704892), [`3d3366f`](https://github.com/mastra-ai/mastra/commit/3d3366f31683e7137d126a3a57174a222c5801fb), [`5a4953f`](https://github.com/mastra-ai/mastra/commit/5a4953f7d25bb15ca31ed16038092a39cb3f98b3), [`eb9e522`](https://github.com/mastra-ai/mastra/commit/eb9e522ce3070a405e5b949b7bf5609ca51d7fe2), [`20e6f19`](https://github.com/mastra-ai/mastra/commit/20e6f1971d51d3ff6dd7accad8aaaae826d540ed), [`4f0b3c6`](https://github.com/mastra-ai/mastra/commit/4f0b3c66f196c06448487f680ccbb614d281e2f7), [`74c4f22`](https://github.com/mastra-ai/mastra/commit/74c4f22ed4c71e72598eacc346ba95cdbc00294f), [`81b6a8f`](https://github.com/mastra-ai/mastra/commit/81b6a8ff79f49a7549d15d66624ac1a0b8f5f971), [`e4d366a`](https://github.com/mastra-ai/mastra/commit/e4d366aeb500371dd4210d6aa8361a4c21d87034), [`a4f010b`](https://github.com/mastra-ai/mastra/commit/a4f010b22e4355a5fdee70a1fe0f6e4a692cc29e), [`73b0bb3`](https://github.com/mastra-ai/mastra/commit/73b0bb394dba7c9482eb467a97ab283dbc0ef4db), [`5627a8c`](https://github.com/mastra-ai/mastra/commit/5627a8c6dc11fe3711b3fa7a6ffd6eb34100a306), [`3ff45d1`](https://github.com/mastra-ai/mastra/commit/3ff45d10e0c80c5335a957ab563da72feb623520), [`251df45`](https://github.com/mastra-ai/mastra/commit/251df4531407dfa46d805feb40ff3fb49769f455), [`f894d14`](https://github.com/mastra-ai/mastra/commit/f894d148946629af7b1f452d65a9cf864cec3765), [`c2b9547`](https://github.com/mastra-ai/mastra/commit/c2b9547bf435f56339f23625a743b2147ab1c7a6), [`580b592`](https://github.com/mastra-ai/mastra/commit/580b5927afc82fe460dfdf9a38a902511b6b7e7f), [`58e3931`](https://github.com/mastra-ai/mastra/commit/58e3931af9baa5921688566210f00fb0c10479fa), [`08bb631`](https://github.com/mastra-ai/mastra/commit/08bb631ae2b14684b2678e3549d0b399a6f0561e), [`4fba91b`](https://github.com/mastra-ai/mastra/commit/4fba91bec7c95911dc28e369437596b152b04cd0), [`12b0cc4`](https://github.com/mastra-ai/mastra/commit/12b0cc4077d886b1a552637dedb70a7ade93528c)]:
+  - @mastra/core@1.0.0-beta.20
+
+## 1.0.0-beta.8
+
+### Patch Changes
+
+- Add storage composition to MastraStorage ([#11401](https://github.com/mastra-ai/mastra/pull/11401))
+
+  `MastraStorage` can now compose storage domains from different adapters. Use it when you need different databases for different purposes - for example, PostgreSQL for memory and workflows, but a different database for observability.
+
+  ```typescript
+  import { MastraStorage } from '@mastra/core/storage';
+  import { MemoryPG, WorkflowsPG, ScoresPG } from '@mastra/pg';
+  import { MemoryLibSQL } from '@mastra/libsql';
+
+  // Compose domains from different stores
+  const storage = new MastraStorage({
+    id: 'composite',
+    domains: {
+      memory: new MemoryLibSQL({ url: 'file:./local.db' }),
+      workflows: new WorkflowsPG({ connectionString: process.env.DATABASE_URL }),
+      scores: new ScoresPG({ connectionString: process.env.DATABASE_URL }),
+    },
+  });
+  ```
+
+  **Breaking changes:**
+  - `storage.supports` property no longer exists
+  - `StorageSupports` type is no longer exported from `@mastra/core/storage`
+
+  All stores now support the same features. For domain availability, use `getStore()`:
+
+  ```typescript
+  const store = await storage.getStore('memory');
+  if (store) {
+    // domain is available
+  }
+  ```
+
+- Updated dependencies [[`3d93a15`](https://github.com/mastra-ai/mastra/commit/3d93a15796b158c617461c8b98bede476ebb43e2), [`efe406a`](https://github.com/mastra-ai/mastra/commit/efe406a1353c24993280ebc2ed61dd9f65b84b26), [`119e5c6`](https://github.com/mastra-ai/mastra/commit/119e5c65008f3e5cfca954eefc2eb85e3bf40da4), [`74e504a`](https://github.com/mastra-ai/mastra/commit/74e504a3b584eafd2f198001c6a113bbec589fd3), [`e33fdbd`](https://github.com/mastra-ai/mastra/commit/e33fdbd07b33920d81e823122331b0c0bee0bb59), [`929f69c`](https://github.com/mastra-ai/mastra/commit/929f69c3436fa20dd0f0e2f7ebe8270bd82a1529), [`8a73529`](https://github.com/mastra-ai/mastra/commit/8a73529ca01187f604b1f3019d0a725ac63ae55f)]:
+  - @mastra/core@1.0.0-beta.16
+
 ## 1.0.0-beta.7
 
 ### Minor Changes

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-beta.9

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-beta.9
+> **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-beta.9",
+  "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

@@ -1211,12 +1211,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 +1245,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 });
@@ -2103,19 +2107,6 @@ var D1Store = class extends storage.MastraStorage {
       memory
     };
   }
-  get supports() {
-    return {
-      selectByIncludeResourceScope: true,
-      resourceWorkingMemory: true,
-      hasColumn: true,
-      createTable: true,
-      deleteMessages: true,
-      observability: false,
-      indexManagement: false,
-      listScoresBySpan: true,
-      agents: false
-    };
-  }
   /**
    * Close the database connection
    * No explicit cleanup needed for D1 in either REST or Workers Binding mode
@@ -2126,5 +2117,8 @@ var D1Store = class extends storage.MastraStorage {
 };
 
 exports.D1Store = D1Store;
+exports.MemoryStorageD1 = MemoryStorageD1;
+exports.ScoresStorageD1 = ScoresStorageD1;
+exports.WorkflowsStorageD1 = WorkflowsStorageD1;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map