@mastra/express 0.0.2-beta.0 → 0.0.2-beta.2

package/README.md

@@ -1,465 +1,71 @@
-# @mastra/pg
+# @mastra/express
 
-PostgreSQL implementation for Mastra, providing both vector similarity search (using pgvector) and general storage capabilities with connection pooling and transaction support.
+Express server adapter for Mastra, enabling you to run Mastra with the [Express](https://expressjs.com) framework.
 
 ## Installation
 
 ```bash
-npm install @mastra/pg
+npm install @mastra/express express
 ```
 
-## Prerequisites
-
-- PostgreSQL server with pgvector extension installed (if using vector store)
-- PostgreSQL 11 or higher
-
 ## Usage
 
-### Vector Store
-
-#### Basic Configuration
-
-PgVector supports multiple connection methods:
-
-**1. Connection String (Recommended)**
-
 ```typescript
-import { PgVector } from '@mastra/pg';
+import express from 'express';
+import { MastraServer } from '@mastra/express';
+import { mastra } from './mastra';
 
-const vectorStore = new PgVector({
-  connectionString: 'postgresql://user:pass@localhost:5432/db',
-});
-```
+const app = express();
+const server = new MastraServer({ app, mastra });
 
-**2. Host/Port/Database Configuration**
+await server.init();
 
-```typescript
-const vectorStore = new PgVector({
-  host: 'localhost',
-  port: 5432,
-  database: 'mydb',
-  user: 'postgres',
-  password: 'password',
-});
-```
-
-> **Note:** PgVector also supports advanced configurations like Google Cloud SQL Connector via `pg.ClientConfig`.
-
-#### Advanced Options
-
-```typescript
-const vectorStore = new PgVector({
-  connectionString: 'postgresql://user:pass@localhost:5432/db',
-  schemaName: 'custom_schema', // Use custom schema (default: public)
-  max: 30, // Max pool connections (default: 20)
-  idleTimeoutMillis: 60000, // Idle timeout (default: 30000)
-  pgPoolOptions: {
-    // Additional pg pool options
-    connectionTimeoutMillis: 5000,
-    allowExitOnIdle: true,
-  },
+app.listen(3000, () => {
+  console.log('Server running on http://localhost:3000');
 });
 ```
 
-#### Usage Example
-
-```typescript
-// Create a new table with vector support
-await vectorStore.createIndex({
-  indexName: 'my_vectors',
-  dimension: 1536,
-  metric: 'cosine',
-  // Optional: Configure index type and parameters
-  indexConfig: {
-    type: 'hnsw',  // 'ivfflat' (default), 'hnsw', or 'flat'
-    hnsw: {
-      m: 16,              // Number of connections per layer (default: 8)
-      efConstruction: 64  // Size of dynamic list (default: 32)
-    }
-  }
-});
-
-// Add vectors
-const ids = await vectorStore.upsert({
-  indexName: 'my_vectors',
-  vectors: [[0.1, 0.2, ...], [0.3, 0.4, ...]],
-  metadata: [{ text: 'doc1' }, { text: 'doc2' }],
-});
+## Adding Custom Routes
 
-// Query vectors
-const results = await vectorStore.query({
-  indexName: 'my_vectors',
-  queryVector: [0.1, 0.2, ...],
-  topK: 10, // topK
-  filter: { text: 'doc1' }, // filter
-  includeVector: false, // includeVector
-  minScore: 0.5, // minScore
-});
-
-// Clean up
-await vectorStore.disconnect();
-```
-
-### Storage
+Add routes directly to the Express app with access to Mastra context:
 
 ```typescript
-import { PostgresStore } from '@mastra/pg';
-
-const store = new PostgresStore({
-  host: 'localhost',
-  port: 5432,
-  database: 'mastra',
-  user: 'postgres',
-  password: 'postgres',
+// Routes added after init() have access to Mastra context
+app.get('/health', (req, res) => {
+  const mastraInstance = res.locals.mastra;
+  const agents = Object.keys(mastraInstance.listAgents());
+  res.json({ status: 'ok', agents });
 });
-
-// Create a thread
-await store.saveThread({
-  id: 'thread-123',
-  resourceId: 'resource-456',
-  title: 'My Thread',
-  metadata: { key: 'value' },
-});
-
-// Add messages to thread
-await store.saveMessages([
-  {
-    id: 'msg-789',
-    threadId: 'thread-123',
-    role: 'user',
-    type: 'text',
-    content: [{ type: 'text', text: 'Hello' }],
-  },
-]);
-
-// Query threads and messages
-const savedThread = await store.getThread('thread-123');
-const messages = await store.getMessages('thread-123');
-```
-
-## Configuration
-
-### Connection Methods
-
-Both `PgVector` and `PostgresStore` support multiple connection methods:
-
-1. **Connection String**
-
-   ```typescript
-   {
-     connectionString: 'postgresql://user:pass@localhost:5432/db';
-   }
-   ```
-
-2. **Host/Port/Database**
-   ```typescript
-   {
-     host: 'localhost',
-     port: 5432,
-     database: 'mydb',
-     user: 'postgres',
-     password: 'password'
-   }
-   ```
-
-> **Advanced:** Also supports `pg.ClientConfig` for use cases like Google Cloud SQL Connector with IAM authentication.
-
-### Optional Configuration
-
-- `schemaName`: Custom PostgreSQL schema (default: `public`)
-- `ssl`: Enable SSL or provide custom SSL options (`true` | `false` | `ConnectionOptions`)
-- `max`: Maximum pool connections (default: `20`)
-- `idleTimeoutMillis`: Idle connection timeout (default: `30000`)
-- `pgPoolOptions`: Additional pg pool options (PgVector only)
-
-### Default Connection Pool Settings
-
-- Maximum connections: 20
-- Idle timeout: 30 seconds
-- Connection timeout: 2 seconds
-
-## Features
-
-### Vector Store Features
-
-- Vector similarity search with cosine, euclidean, and dot product (inner) metrics
-- Advanced metadata filtering with MongoDB-like query syntax
-- Minimum score threshold for queries
-- Automatic UUID generation for vectors
-- Table management (create, list, describe, delete, truncate)
-- Configurable vector index types:
-  - **IVFFlat** (default): Balanced speed/accuracy, auto-calculates optimal lists parameter
-  - **HNSW**: Fastest queries, higher memory usage, best for large datasets
-  - **Flat**: No index, 100% accuracy, best for small datasets (<1000 vectors)
-
-### Storage Features
-
-- Thread and message storage with JSON support
-- Atomic transactions for data consistency
-- Efficient batch operations
-- Rich metadata support
-- Timestamp tracking
-- Cascading deletes
-
-## Supported Filter Operators
-
-The following filter operators are supported for metadata queries:
-
-- Comparison: `$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte`
-- Logical: `$and`, `$or`
-- Array: `$in`, `$nin`
-- Text: `$regex`, `$like`
-
-Example filter:
-
-```typescript
-{
-  $and: [{ age: { $gt: 25 } }, { tags: { $in: ['tag1', 'tag2'] } }];
-}
 ```
 
-## Vector Index Configuration
-
-pgvector supports three index types, each with different performance characteristics:
-
-### IVFFlat Index (Default)
-
-IVFFlat groups vectors into clusters for efficient searching:
+## Configuration Options
 
 ```typescript
-await vectorStore.createIndex({
-  indexName: 'my_vectors',
-  dimension: 1536,
-  metric: 'cosine',
-  indexConfig: {
-    type: 'ivfflat',
-    ivf: {
-      lists: 1000, // Number of clusters (default: auto-calculated as sqrt(rows) * 2)
-    },
+const server = new MastraServer({
+  app,
+  mastra,
+  prefix: '/api/v2', // Route prefix
+  openapiPath: '/openapi.json', // OpenAPI spec endpoint
+  bodyLimitOptions: {
+    maxSize: 10 * 1024 * 1024, // 10MB
+    onError: err => ({ error: 'Payload too large' }),
   },
+  streamOptions: { redact: true }, // Redact sensitive data from streams
 });
 ```
 
-- **Best for:** Medium to large datasets (10K-1M vectors)
-- **Build time:** Minutes for millions of vectors
-- **Query speed:** Fast (tens of milliseconds)
-- **Memory:** Moderate
-- **Accuracy:** ~95-99%
+## Context Variables
 
-### HNSW Index
+Access these in route handlers via `res.locals`:
 
-HNSW builds a graph structure for extremely fast searches:
-
-```typescript
-await vectorStore.createIndex({
-  indexName: 'my_vectors',
-  dimension: 1536,
-  metric: 'dotproduct', // Recommended for normalized embeddings (OpenAI, etc.)
-  indexConfig: {
-    type: 'hnsw',
-    hnsw: {
-      m: 16, // Connections per layer (default: 8, range: 2-100)
-      efConstruction: 64, // Dynamic list size (default: 32, range: 4-1000)
-    },
-  },
-});
-```
-
-- **Best for:** Large datasets (100K+ vectors) requiring fastest searches
-- **Build time:** Can take hours for large datasets
-- **Query speed:** Very fast (milliseconds even for millions)
-- **Memory:** High (can be 2-3x vector size)
-- **Accuracy:** ~99%
-
-**Tuning HNSW:**
-
-- Higher `m`: Better accuracy, more memory (16-32 for high accuracy)
-- Higher `efConstruction`: Better index quality, slower builds (64-200 for quality)
-
-### Flat Index (No Index)
-
-Uses sequential scan for 100% accuracy:
-
-```typescript
-await vectorStore.createIndex({
-  indexName: 'my_vectors',
-  dimension: 1536,
-  metric: 'cosine',
-  indexConfig: {
-    type: 'flat',
-  },
-});
-```
-
-- **Best for:** Small datasets (<1000 vectors) or when 100% accuracy is required
-- **Build time:** None
-- **Query speed:** Slow for large datasets (linear scan)
-- **Memory:** Minimal (just vectors)
-- **Accuracy:** 100%
-
-### Distance Metrics
-
-Choose the appropriate metric for your embeddings:
-
-- **`cosine`** (default): Angular similarity, good for text embeddings
-- **`euclidean`**: L2 distance, for unnormalized embeddings
-- **`dotproduct`**: Dot product, optimal for normalized embeddings (OpenAI, Cohere)
-
-### Index Recreation
-
-The system automatically detects configuration changes and only rebuilds indexes when necessary, preventing the performance issues from unnecessary recreations.
-
-**Important behaviors:**
-
-- If no `indexConfig` is provided, existing indexes are preserved as-is
-- If `indexConfig` is provided, indexes are only rebuilt if the configuration differs
-- New indexes default to IVFFlat with cosine distance when no config is specified
-
-## Vector Store Methods
-
-- `createIndex({indexName, dimension, metric?, indexConfig?, buildIndex?})`: Create a new table with vector support
-- `buildIndex({indexName, metric?, indexConfig?})`: Build or rebuild vector index
-- `upsert({indexName, vectors, metadata?, ids?})`: Add or update vectors
-- `query({indexName, queryVector, topK?, filter?, includeVector?, minScore?})`: Search for similar vectors
-- `listIndexes()`: List all vector-enabled tables
-- `describeIndex(indexName)`: Get table statistics and index configuration
-- `deleteIndex(indexName)`: Delete a table
-- `truncateIndex(indexName)`: Remove all data from a table
-- `disconnect()`: Close all database connections
-
-## Storage Methods
-
-- `saveThread(thread)`: Create or update a thread
-- `getThread(threadId)`: Get a thread by ID
-- `deleteThread(threadId)`: Delete a thread and its messages
-- `saveMessages(messages)`: Save multiple messages in a transaction
-- `getMessages(threadId)`: Get all messages for a thread
-- `deleteMessages(messageIds)`: Delete specific messages
-
-## Index Management
-
-The PostgreSQL store provides comprehensive index management capabilities to optimize query performance.
-
-### Automatic Performance Indexes
-
-PostgreSQL storage automatically creates composite indexes during initialization for common query patterns:
-
-- `mastra_threads_resourceid_createdat_idx`: (resourceId, createdAt DESC)
-- `mastra_messages_thread_id_createdat_idx`: (thread_id, createdAt DESC)
-- `mastra_traces_name_starttime_idx`: (name, startTime DESC)
-- `mastra_evals_agent_name_created_at_idx`: (agent_name, created_at DESC)
-
-These indexes significantly improve performance for filtered queries with sorting.
-
-### Creating Custom Indexes
-
-Create additional indexes to optimize specific query patterns:
-
-```typescript
-// Basic index for common queries
-await store.createIndex({
-  name: 'idx_threads_resource',
-  table: 'mastra_threads',
-  columns: ['resourceId'],
-});
-
-// Composite index with sort order for filtering + sorting
-await store.createIndex({
-  name: 'idx_messages_composite',
-  table: 'mastra_messages',
-  columns: ['thread_id', 'createdAt DESC'],
-});
-
-// GIN index for JSONB columns (fast JSON queries)
-await store.createIndex({
-  name: 'idx_traces_attributes',
-  table: 'mastra_traces',
-  columns: ['attributes'],
-  method: 'gin',
-});
-```
-
-For more advanced use cases, you can also use:
-
-- `unique: true` for unique constraints
-- `where: 'condition'` for partial indexes
-- `method: 'brin'` for time-series data
-- `storage: { fillfactor: 90 }` for update-heavy tables
-- `concurrent: true` for non-blocking creation (default)
-
-### Managing Indexes
-
-```typescript
-// List all indexes
-const allIndexes = await store.listIndexes();
-
-// List indexes for specific table
-const threadIndexes = await store.listIndexes('mastra_threads');
-
-// Get detailed statistics for an index
-const stats = await store.describeIndex('idx_threads_resource');
-console.log(stats);
-// {
-//   name: 'idx_threads_resource',
-//   table: 'mastra_threads',
-//   columns: ['resourceId', 'createdAt'],
-//   unique: false,
-//   size: '128 KB',
-//   definition: 'CREATE INDEX idx_threads_resource...',
-//   method: 'btree',
-//   scans: 1542,           // Number of index scans
-//   tuples_read: 45230,    // Tuples read via index
-//   tuples_fetched: 12050  // Tuples fetched via index
-// }
-
-// Drop an index
-await store.dropIndex('idx_threads_status');
-```
-
-### Index Types and Use Cases
-
-| Index Type          | Best For                                | Storage    | Speed                      |
-| ------------------- | --------------------------------------- | ---------- | -------------------------- |
-| **btree** (default) | Range queries, sorting, general purpose | Moderate   | Fast                       |
-| **hash**            | Equality comparisons only               | Small      | Very fast for `=`          |
-| **gin**             | JSONB, arrays, full-text search         | Large      | Fast for contains          |
-| **gist**            | Geometric data, full-text search        | Moderate   | Fast for nearest-neighbor  |
-| **spgist**          | Non-balanced data, text patterns        | Small      | Fast for specific patterns |
-| **brin**            | Large tables with natural ordering      | Very small | Fast for ranges            |
-
-### Index Options
-
-- `name` (required): Index name
-- `table` (required): Table name
-- `columns` (required): Array of column names (can include DESC/ASC)
-- `unique`: Create unique index (default: false)
-- `concurrent`: Non-blocking index creation (default: true)
-- `where`: Partial index condition
-- `method`: Index type ('btree' | 'hash' | 'gin' | 'gist' | 'spgist' | 'brin')
-- `opclass`: Operator class for GIN/GIST indexes
-- `storage`: Storage parameters (e.g., { fillfactor: 90 })
-- `tablespace`: Tablespace name for index placement
-
-### Monitoring Index Performance
-
-```typescript
-// Check index usage statistics
-const stats = await store.describeIndex('idx_threads_resource');
-
-// Identify unused indexes
-if (stats.scans === 0) {
-  console.log(`Index ${stats.name} is unused - consider removing`);
-  await store.dropIndex(stats.name);
-}
-
-// Monitor index efficiency
-const efficiency = stats.tuples_fetched / stats.tuples_read;
-if (efficiency < 0.5) {
-  console.log(`Index ${stats.name} has low efficiency: ${efficiency}`);
-}
-```
+| Key              | Description                 |
+| ---------------- | --------------------------- |
+| `mastra`         | Mastra instance             |
+| `requestContext` | Request context map         |
+| `abortSignal`    | Request cancellation signal |
+| `tools`          | Available tools             |
 
 ## Related Links
 
-- [pgvector Documentation](https://github.com/pgvector/pgvector)
-- [PostgreSQL Documentation](https://www.postgresql.org/docs/)
+- [Server Adapters Documentation](https://mastra.ai/docs/v1/server-db/server-adapters)
+- [Express Documentation](https://expressjs.com)

package/dist/auth-middleware.d.ts

@@ -0,0 +1,4 @@
+import type { NextFunction, Request, Response } from 'express';
+export declare const authenticationMiddleware: (req: Request, res: Response, next: NextFunction) => Promise<void | Response<any, Record<string, any>>>;
+export declare const authorizationMiddleware: (req: Request, res: Response, next: NextFunction) => Promise<void | Response<any, Record<string, any>>>;
+//# sourceMappingURL=auth-middleware.d.ts.map

package/dist/auth-middleware.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-middleware.d.ts","sourceRoot":"","sources":["../src/auth-middleware.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,YAAY,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAE/D,eAAO,MAAM,wBAAwB,GAAU,KAAK,OAAO,EAAE,KAAK,QAAQ,EAAE,MAAM,YAAY,uDAmE7F,CAAC;AAEF,eAAO,MAAM,uBAAuB,GAAU,KAAK,OAAO,EAAE,KAAK,QAAQ,EAAE,MAAM,YAAY,uDAkG5F,CAAC"}