@mastra/turbopuffer 1.0.0-beta.2 → 1.0.0-beta.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (6) hide show
  1. package/CHANGELOG.md +18 -0
  2. package/dist/docs/README.md +31 -0
  3. package/dist/docs/SKILL.md +32 -0
  4. package/dist/docs/SOURCE_MAP.json +6 -0
  5. package/dist/docs/vectors/01-reference.md +108 -0
  6. package/package.json +7 -7
package/CHANGELOG.md CHANGED
@@ -1,5 +1,23 @@
1
1
  # @mastra/turbopuffer
2
2
 
3
+ ## 1.0.0-beta.3
4
+
5
+ ### Patch Changes
6
+
7
+ - Add embedded documentation support for Mastra packages ([#11472](https://github.com/mastra-ai/mastra/pull/11472))
8
+
9
+ 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`.
10
+
11
+ Each package includes:
12
+ - **SKILL.md** - Entry point explaining the package's purpose and capabilities
13
+ - **SOURCE_MAP.json** - Machine-readable index mapping exports to types and implementation files
14
+ - **Topic folders** - Conceptual documentation organized by feature area
15
+
16
+ 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.
17
+
18
+ - 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)]:
19
+ - @mastra/core@1.0.0-beta.20
20
+
3
21
  ## 1.0.0-beta.2
4
22
 
5
23
  ### Patch Changes
package/dist/docs/README.md ADDED
@@ -0,0 +1,31 @@
1
+ # @mastra/turbopuffer Documentation
2
+
3
+ > Embedded documentation for coding agents
4
+
5
+ ## Quick Start
6
+
7
+ ```bash
8
+ # Read the skill overview
9
+ cat docs/SKILL.md
10
+
11
+ # Get the source map
12
+ cat docs/SOURCE_MAP.json
13
+
14
+ # Read topic documentation
15
+ cat docs/<topic>/01-overview.md
16
+ ```
17
+
18
+ ## Structure
19
+
20
+ ```
21
+ docs/
22
+ ├── SKILL.md # Entry point
23
+ ├── README.md # This file
24
+ ├── SOURCE_MAP.json # Export index
25
+ ├── vectors/ (1 files)
26
+ ```
27
+
28
+ ## Version
29
+
30
+ Package: @mastra/turbopuffer
31
+ Version: 1.0.0-beta.3
package/dist/docs/SKILL.md ADDED
@@ -0,0 +1,32 @@
1
+ ---
2
+ name: mastra-turbopuffer-docs
3
+ description: Documentation for @mastra/turbopuffer. Includes links to type definitions and readable implementation code in dist/.
4
+ ---
5
+
6
+ # @mastra/turbopuffer Documentation
7
+
8
+ > **Version**: 1.0.0-beta.3
9
+ > **Package**: @mastra/turbopuffer
10
+
11
+ ## Quick Navigation
12
+
13
+ Use SOURCE_MAP.json to find any export:
14
+
15
+ ```bash
16
+ cat docs/SOURCE_MAP.json
17
+ ```
18
+
19
+ Each export maps to:
20
+ - **types**: `.d.ts` file with JSDoc and API signatures
21
+ - **implementation**: `.js` chunk file with readable source
22
+ - **docs**: Conceptual documentation in `docs/`
23
+
24
+ ## Top Exports
25
+
26
+
27
+
28
+ See SOURCE_MAP.json for the complete list.
29
+
30
+ ## Available Topics
31
+
32
+ - [Vectors](vectors/) - 1 file(s)
package/dist/docs/SOURCE_MAP.json ADDED
@@ -0,0 +1,6 @@
1
+ {
2
+ "version": "1.0.0-beta.3",
3
+ "package": "@mastra/turbopuffer",
4
+ "exports": {},
5
+ "modules": {}
6
+ }
package/dist/docs/vectors/01-reference.md ADDED
@@ -0,0 +1,108 @@
1
+ # Vectors API Reference
2
+
3
+ > API reference for vectors - 1 entries
4
+
5
+
6
+ ---
7
+
8
+ ## Reference: Turbopuffer Vector Store
9
+
10
+ > Documentation for integrating Turbopuffer with Mastra, a high-performance vector database for efficient similarity search.
11
+
12
+ The TurbopufferVector class provides vector search using [Turbopuffer](https://turbopuffer.com/), a high-performance vector database optimized for RAG applications. Turbopuffer offers fast vector similarity search with advanced filtering capabilities and efficient storage management.
13
+
14
+ ## Constructor Options
15
+
16
+ ## Methods
17
+
18
+ ### createIndex()
19
+
20
+ ### upsert()
21
+
22
+ ### query()
23
+
24
+ ### listIndexes()
25
+
26
+ Returns an array of index names as strings.
27
+
28
+ ### describeIndex()
29
+
30
+ Returns:
31
+
32
+ ```typescript
33
+ interface IndexStats {
34
+ dimension: number;
35
+ count: number;
36
+ metric: "cosine" | "euclidean" | "dotproduct";
37
+ }
38
+ ```
39
+
40
+ ### deleteIndex()
41
+
42
+ ### updateVector()
43
+
44
+ Update a single vector by ID or by metadata filter. Either `id` or `filter` must be provided, but not both.
45
+
46
+ ### deleteVector()
47
+
48
+ ### deleteVectors()
49
+
50
+ Delete multiple vectors by IDs or by metadata filter. Either `ids` or `filter` must be provided, but not both.
51
+
52
+ ## Response Types
53
+
54
+ Query results are returned in this format:
55
+
56
+ ```typescript
57
+ interface QueryResult {
58
+ id: string;
59
+ score: number;
60
+ metadata: Record<string, any>;
61
+ vector?: number[]; // Only included if includeVector is true
62
+ }
63
+ ```
64
+
65
+ ## Schema Configuration
66
+
67
+ The `schemaConfigForIndex` option allows you to define explicit schemas for different indexes:
68
+
69
+ ```typescript
70
+ schemaConfigForIndex: (indexName: string) => {
71
+ // Mastra's default embedding model and index for memory messages:
72
+ if (indexName === "memory_messages_384") {
73
+ return {
74
+ dimensions: 384,
75
+ schema: {
76
+ thread_id: {
77
+ type: "string",
78
+ filterable: true,
79
+ },
80
+ },
81
+ };
82
+ } else {
83
+ throw new Error(`TODO: add schema for index: ${indexName}`);
84
+ }
85
+ };
86
+ ```
87
+
88
+ ## Error Handling
89
+
90
+ The store throws typed errors that can be caught:
91
+
92
+ ```typescript
93
+ try {
94
+ await store.query({
95
+ indexName: "index_name",
96
+ queryVector: queryVector,
97
+ });
98
+ } catch (error) {
99
+ if (error instanceof VectorStoreError) {
100
+ console.log(error.code); // 'connection_failed' | 'invalid_dimension' | etc
101
+ console.log(error.details); // Additional error context
102
+ }
103
+ }
104
+ ```
105
+
106
+ ## Related
107
+
108
+ - [Metadata Filters](../rag/metadata-filters)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@mastra/turbopuffer",
3
- "version": "1.0.0-beta.2",
3
+ "version": "1.0.0-beta.3",
4
4
  "description": "Turbopuffer vector store provider for Mastra",
5
5
  "type": "module",
6
6
  "files": [
@@ -27,19 +27,18 @@
27
27
  "@turbopuffer/turbopuffer": "^0.6.17"
28
28
  },
29
29
  "devDependencies": {
30
- "@microsoft/api-extractor": "^7.52.8",
31
30
  "@types/node": "22.13.17",
32
31
  "@vitest/coverage-v8": "4.0.12",
33
32
  "@vitest/ui": "4.0.12",
34
33
  "dotenv": "^17.0.0",
35
34
  "eslint": "^9.37.0",
36
35
  "tsup": "^8.5.0",
37
- "typescript": "^5.8.3",
38
- "vitest": "4.0.12",
36
+ "typescript": "^5.9.3",
37
+ "vitest": "4.0.16",
39
38
  "@internal/lint": "0.0.53",
40
- "@internal/types-builder": "0.0.28",
41
39
  "@internal/storage-test-utils": "0.0.49",
42
- "@mastra/core": "1.0.0-beta.7"
40
+ "@internal/types-builder": "0.0.28",
41
+ "@mastra/core": "1.0.0-beta.20"
43
42
  },
44
43
  "peerDependencies": {
45
44
  "@mastra/core": ">=1.0.0-0 <2.0.0-0"
@@ -57,7 +56,8 @@
57
56
  "node": ">=22.13.0"
58
57
  },
59
58
  "scripts": {
60
- "build": "tsup --silent --config tsup.config.ts",
59
+ "build:lib": "tsup --silent --config tsup.config.ts",
60
+ "build:docs": "pnpx tsx ../../scripts/generate-package-docs.ts stores/turbopuffer",
61
61
  "build:watch": "tsup --watch --silent --config tsup.config.ts",
62
62
  "test": "vitest run",
63
63
  "lint": "eslint ."