@mastra/spanner 0.0.0 → 1.0.0-alpha.0

package/dist/storage/domains/skills/index.d.ts

@@ -0,0 +1,64 @@
+import { SkillsStorage } from '@mastra/core/storage';
+import type { CreateIndexOptions, StorageSkillType, StorageCreateSkillInput, StorageListSkillsInput, StorageListSkillsOutput, StorageUpdateSkillInput } from '@mastra/core/storage';
+import type { CreateSkillVersionInput, ListSkillVersionsInput, ListSkillVersionsOutput, SkillVersion } from '@mastra/core/storage/domains/skills';
+import type { SpannerDomainConfig } from '../../db/index.js';
+/**
+ * Spanner-backed storage for skills and their immutable versions.
+ * Mirrors the thin-record + versions pattern used by agents/prompt-blocks/scorer-definitions.
+ */
+export declare class SkillsSpanner extends SkillsStorage {
+    private database;
+    private db;
+    private readonly skipDefaultIndexes?;
+    private readonly indexes?;
+    static readonly MANAGED_TABLES: readonly ["mastra_skills", "mastra_skill_versions"];
+    constructor(config: SpannerDomainConfig);
+    /** Creates the skill tables, indexes, and (when opted in) sweeps stale drafts. */
+    init(): Promise<void>;
+    /**
+     * Sweeps orphaned draft thin-rows whose paired version row was never written.
+     * Skipped under `initMode: 'validate'` (no destructive DML in validate mode).
+     */
+    private cleanupStaleDrafts;
+    /** Returns the default index set this domain creates during `init()`. */
+    getDefaultIndexDefinitions(): CreateIndexOptions[];
+    /** Creates the default indexes; no-op when `skipDefaultIndexes` was set. */
+    createDefaultIndexes(): Promise<void>;
+    /** Creates custom indexes routed to this domain's tables; no-op when none supplied. */
+    createCustomIndexes(): Promise<void>;
+    /** Removes every row from this domain's tables. Intended for tests. */
+    dangerouslyClearAll(): Promise<void>;
+    /** Decodes a raw Spanner thin-row into the public skill shape. */
+    private parseSkillRow;
+    /** Decodes a raw Spanner version row into the public version shape. */
+    private parseVersionRow;
+    /** Fetches the thin skill record by id, or `null` when absent. */
+    getById(id: string): Promise<StorageSkillType | null>;
+    /** Atomically inserts a draft thin row + version 1 in a single Spanner transaction. */
+    create(input: {
+        skill: StorageCreateSkillInput;
+    }): Promise<StorageSkillType>;
+    /** Updates thin-record fields (status, activeVersionId, authorId). */
+    update(input: StorageUpdateSkillInput): Promise<StorageSkillType>;
+    /** Removes a skill and all its versions atomically in a single transaction. */
+    delete(id: string): Promise<void>;
+    /** Paginated listing with optional authorId filter. */
+    list(args?: StorageListSkillsInput): Promise<StorageListSkillsOutput>;
+    /** Inserts a new immutable version row for an existing skill. */
+    createVersion(input: CreateSkillVersionInput): Promise<SkillVersion>;
+    /** Fetches a version row by its id, or `null` when absent. */
+    getVersion(id: string): Promise<SkillVersion | null>;
+    /** Fetches a specific version by `(skillId, versionNumber)`. */
+    getVersionByNumber(skillId: string, versionNumber: number): Promise<SkillVersion | null>;
+    /** Returns the highest-numbered version for a skill. */
+    getLatestVersion(skillId: string): Promise<SkillVersion | null>;
+    /** Paginated listing of versions for a single skill. */
+    listVersions(input: ListSkillVersionsInput): Promise<ListSkillVersionsOutput>;
+    /** Deletes a single version row by id. */
+    deleteVersion(id: string): Promise<void>;
+    /** Deletes every version row belonging to the given skill. */
+    deleteVersionsByParentId(entityId: string): Promise<void>;
+    /** Returns the total number of version rows for the given skill. */
+    countVersions(skillId: string): Promise<number>;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/storage/domains/skills/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/storage/domains/skills/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAIL,aAAa,EAKd,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EACV,kBAAkB,EAClB,gBAAgB,EAChB,uBAAuB,EACvB,sBAAsB,EACtB,uBAAuB,EACvB,uBAAuB,EACxB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EACV,uBAAuB,EACvB,sBAAsB,EACtB,uBAAuB,EACvB,YAAY,EACb,MAAM,qCAAqC,CAAC;AAE7C,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAC;AAIpD;;;GAGG;AACH,qBAAa,aAAc,SAAQ,aAAa;IAC9C,OAAO,CAAC,QAAQ,CAAW;IAC3B,OAAO,CAAC,EAAE,CAAY;IACtB,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAC,CAAU;IAC9C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAuB;IAEhD,MAAM,CAAC,QAAQ,CAAC,cAAc,sDAAiD;gBAEnE,MAAM,EAAE,mBAAmB;IAUvC,kFAAkF;IAC5E,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAS3B;;;OAGG;YACW,kBAAkB;IAmBhC,yEAAyE;IACzE,0BAA0B,IAAI,kBAAkB,EAAE;IAuBlD,4EAA4E;IACtE,oBAAoB,IAAI,OAAO,CAAC,IAAI,CAAC;IAK3C,uFAAuF;IACjF,mBAAmB,IAAI,OAAO,CAAC,IAAI,CAAC;IAK1C,uEAAuE;IACjE,mBAAmB,IAAI,OAAO,CAAC,IAAI,CAAC;IAK1C,kEAAkE;IAClE,OAAO,CAAC,aAAa;IAYrB,uEAAuE;IACvE,OAAO,CAAC,eAAe;IA0BvB,kEAAkE;IAC5D,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC;IAuB3D,uFAAuF;IACjF,MAAM,CAAC,KAAK,EAAE;QAAE,KAAK,EAAE,uBAAuB,CAAA;KAAE,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAwFlF,sEAAsE;IAChE,MAAM,CAAC,KAAK,EAAE,uBAAuB,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAgDvE,+EAA+E;IACzE,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAkCvC,uDAAuD;IACjD,IAAI,CAAC,IAAI,CAAC,EAAE,sBAAsB,GAAG,OAAO,CAAC,uBAAuB,CAAC;IAqE3E,iEAAiE;IAC3D,aAAa,CAAC,KAAK,EAAE,uBAAuB,GAAG,OAAO,CAAC,YAAY,CAAC;IAwC1E,8DAA8D;IACxD,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC;IAuB1D,gEAAgE;IAC1D,kBAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC;IA0B9F,wDAAwD;IAClD,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC;IA0BrE,wDAAwD;IAClD,YAAY,CAAC,KAAK,EAAE,sBAAsB,GAAG,OAAO,CAAC,uBAAuB,CAAC;IA8DnF,0CAA0C;IACpC,aAAa,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAoB9C,8DAA8D;IACxD,wBAAwB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAoB/D,oEAAoE;IAC9D,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;CAqBtD"}

package/dist/storage/domains/utils.d.ts

@@ -0,0 +1,17 @@
+import type { DateRange, TABLE_NAMES } from '@mastra/core/storage';
+import { quoteIdent } from '../db/utils.js';
+export { quoteIdent };
+/**
+ * Build storage filter entries for a date range, using the operator suffixes
+ * understood by `SpannerDB.prepareWhereClause`.
+ */
+export declare function buildDateRangeFilter(dateRange: DateRange | undefined, fieldName: string): Record<string, any>;
+/**
+ * Convert a Spanner JSON-serialized row into the storage-layer expected shape.
+ * Mirrors the helper exported by other adapters so domain code can stay similar.
+ */
+export declare function transformFromSpannerRow<T>({ tableName, row, }: {
+    tableName: TABLE_NAMES;
+    row: Record<string, any>;
+}): T;
+//# sourceMappingURL=utils.d.ts.map

package/dist/storage/domains/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../../src/storage/domains/utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAEnE,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC,OAAO,EAAE,UAAU,EAAE,CAAC;AAEtB;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,SAAS,GAAG,SAAS,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAW7G;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,CAAC,EAAE,EACzC,SAAS,EACT,GAAG,GACJ,EAAE;IACD,SAAS,EAAE,WAAW,CAAC;IACvB,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CAC1B,GAAG,CAAC,CA6CJ"}

package/dist/storage/domains/workflows/index.d.ts

@@ -0,0 +1,97 @@
+import { WorkflowsStorage } from '@mastra/core/storage';
+import type { StorageListWorkflowRunsInput, WorkflowRun, WorkflowRuns, UpdateWorkflowStateOptions, CreateIndexOptions } from '@mastra/core/storage';
+import type { StepResult, WorkflowRunState } from '@mastra/core/workflows';
+import type { SpannerDomainConfig } from '../../db/index.js';
+/**
+ * Spanner-backed storage for workflow run snapshots, including persistence,
+ * incremental updates, and listing of historical runs.
+ */
+export declare class WorkflowsSpanner extends WorkflowsStorage {
+    private database;
+    private db;
+    private readonly skipDefaultIndexes?;
+    private readonly indexes?;
+    static readonly MANAGED_TABLES: readonly ["mastra_workflow_snapshot"];
+    constructor(config: SpannerDomainConfig);
+    /** Spanner serialises read-write transactions, so concurrent updates are safe. */
+    supportsConcurrentUpdates(): boolean;
+    /** Returns the default index set this domain creates during `init()`. */
+    getDefaultIndexDefinitions(): CreateIndexOptions[];
+    /**
+     * Creates the default indexes; no-op when `skipDefaultIndexes` was set.
+     * Filters out the snapshotStatus index when that generated column is absent
+     * (e.g. ensureStatusColumn() failed, or `initMode: 'validate'` skipped the
+     * DDL). Otherwise the createIndex call would fail on a missing column.
+     */
+    createDefaultIndexes(): Promise<void>;
+    /** Creates the workflow snapshot table, the snapshotStatus generated column, and indexes. */
+    init(): Promise<void>;
+    /**
+     * Spanner-specific optimization: add a STORED generated column that extracts
+     * `status` from the JSON snapshot, so the listWorkflowRuns status filter can
+     * use a regular secondary index instead of a full JSON_VALUE scan.
+     *
+     * The column is owned and maintained entirely by the Spanner adapter; the
+     * shared `@mastra/core` schema doesn't reference it. The DDL is idempotent
+     * (`ADD COLUMN IF NOT EXISTS`) and the schema operation is awaited; Spanner
+     * backfills existing rows asynchronously after the operation returns, while
+     * new rows pick up the value on every write.
+     */
+    private ensureStatusColumn;
+    /**
+     * Cached lookup for whether the `snapshotStatus` generated column exists.
+     * Resolves true after `ensureStatusColumn()` succeeds, otherwise falls back
+     * to an INFORMATION_SCHEMA probe (lets us still pick up the fast path on
+     * databases that already had the column from a prior deploy).
+     */
+    private statusColumnAvailable;
+    /** Returns true when the `snapshotStatus` generated column exists. */
+    private hasStatusColumn;
+    /** Creates custom indexes routed to this domain's tables; no-op when none supplied. */
+    createCustomIndexes(): Promise<void>;
+    /** Removes every workflow snapshot row. Intended for tests. */
+    dangerouslyClearAll(): Promise<void>;
+    /** Decodes a raw Spanner snapshot row into the public `WorkflowRun` shape. */
+    private parseWorkflowRun;
+    /** Upserts a workflow run snapshot, preserving the original `createdAt` on update. */
+    persistWorkflowSnapshot({ workflowName, runId, resourceId, snapshot, createdAt, updatedAt, }: {
+        workflowName: string;
+        runId: string;
+        resourceId?: string;
+        snapshot: WorkflowRunState;
+        createdAt?: Date;
+        updatedAt?: Date;
+    }): Promise<void>;
+    /** Loads the snapshot payload for a `(workflowName, runId)` pair, or `null` when absent. */
+    loadWorkflowSnapshot({ workflowName, runId, }: {
+        workflowName: string;
+        runId: string;
+    }): Promise<WorkflowRunState | null>;
+    /** Merges a step result and request-context delta into a snapshot inside an RW transaction. */
+    updateWorkflowResults({ workflowName, runId, stepId, result, requestContext, }: {
+        workflowName: string;
+        runId: string;
+        stepId: string;
+        result: StepResult<any, any, any, any>;
+        requestContext: Record<string, any>;
+    }): Promise<Record<string, StepResult<any, any, any, any>>>;
+    /** Applies a top-level snapshot patch (e.g. status, value) inside an RW transaction. */
+    updateWorkflowState({ workflowName, runId, opts, }: {
+        workflowName: string;
+        runId: string;
+        opts: UpdateWorkflowStateOptions;
+    }): Promise<WorkflowRunState | undefined>;
+    /** Fetches a single workflow run by `runId` (optionally narrowed by `workflowName`). */
+    getWorkflowRunById({ runId, workflowName, }: {
+        runId: string;
+        workflowName?: string;
+    }): Promise<WorkflowRun | null>;
+    /** Deletes the snapshot row for a `(workflowName, runId)` pair. */
+    deleteWorkflowRunById({ runId, workflowName }: {
+        runId: string;
+        workflowName: string;
+    }): Promise<void>;
+    /** Paginated listing with optional workflowName, status, resourceId, and date-range filters. */
+    listWorkflowRuns({ workflowName, fromDate, toDate, page, perPage, resourceId, status, }?: StorageListWorkflowRunsInput): Promise<WorkflowRuns>;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/storage/domains/workflows/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/storage/domains/workflows/index.ts"],"names":[],"mappings":"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"}

package/dist/storage/index.d.ts

@@ -0,0 +1,178 @@
+import { Spanner } from '@google-cloud/spanner';
+import type { Database, Instance } from '@google-cloud/spanner';
+import { MastraCompositeStore } from '@mastra/core/storage';
+import type { StorageDomains, CreateIndexOptions } from '@mastra/core/storage';
+import type { SpannerInitMode } from './db/index.js';
+import { AgentsSpanner } from './domains/agents/index.js';
+import { BackgroundTasksSpanner } from './domains/background-tasks/index.js';
+import { BlobsSpanner } from './domains/blobs/index.js';
+import { MCPClientsSpanner } from './domains/mcp-clients/index.js';
+import { MCPServersSpanner } from './domains/mcp-servers/index.js';
+import { MemorySpanner } from './domains/memory/index.js';
+import { ObservabilitySpanner } from './domains/observability/index.js';
+import { PromptBlocksSpanner } from './domains/prompt-blocks/index.js';
+import { SchedulesSpanner } from './domains/schedules/index.js';
+import { ScorerDefinitionsSpanner } from './domains/scorer-definitions/index.js';
+import { ScoresSpanner } from './domains/scores/index.js';
+import { SkillsSpanner } from './domains/skills/index.js';
+import { WorkflowsSpanner } from './domains/workflows/index.js';
+export { AgentsSpanner, BackgroundTasksSpanner, BlobsSpanner, MCPClientsSpanner, MCPServersSpanner, MemorySpanner, ObservabilitySpanner, PromptBlocksSpanner, SchedulesSpanner, ScorerDefinitionsSpanner, ScoresSpanner, SkillsSpanner, WorkflowsSpanner, };
+export type { SpannerDomainConfig, SpannerInitMode } from './db/index.js';
+/** Domain keys this adapter implements; the only valid values for `enabledDomains`. */
+export declare const SPANNER_DOMAIN_KEYS: readonly ["scores", "workflows", "memory", "backgroundTasks", "agents", "mcpClients", "mcpServers", "skills", "blobs", "promptBlocks", "scorerDefinitions", "schedules", "observability"];
+export type SpannerDomainKey = (typeof SPANNER_DOMAIN_KEYS)[number];
+/**
+ * Cloud Spanner configuration accepted by `SpannerStore`.
+ *
+ * Supports either:
+ * - Pre-configured `database` (a `@google-cloud/spanner` Database handle), or
+ * - Connection details (`projectId`, `instanceId`, `databaseId`) from which the
+ *   store creates a Spanner client internally.
+ */
+export type SpannerConfigType = {
+    id: string;
+    /**
+     * When true, automatic initialization (table creation/migrations) is disabled.
+     *
+     * When `disableInit` is true, the store will not automatically create or alter
+     * tables on first use. You must call `storage.init()` explicitly during a
+     * separate deploy/migration step.
+     */
+    disableInit?: boolean;
+    /**
+     * When true, default indexes will not be created during initialization.
+     * @default false
+     */
+    skipDefaultIndexes?: boolean;
+    /**
+     * Custom indexes to create during initialization. Each index must specify the
+     * table it belongs to; the store routes indexes to the correct domain.
+     */
+    indexes?: CreateIndexOptions[];
+    /**
+     * Controls whether `init()` is allowed to apply schema changes.
+     *
+     * - `'sync'` (default): the adapter creates missing tables, columns, and
+     *   indexes during `init()`. This is the historical behavior.
+     * - `'validate'`: the adapter applies no DDL during `init()` and instead
+     *   verifies that every table, column, and default/custom index it would
+     *   have created already exists. Missing schema elements throw a typed
+     *   user error so the operator can reconcile the externally-managed
+     *   schema with what the adapter expects.
+     *
+     * `'validate'` is intended for environments where another process
+     * (Terraform, Liquibase, a release pipeline, etc.) owns the schema.
+     * @default 'sync'
+     */
+    initMode?: SpannerInitMode;
+    /**
+     * When true, versioned domains (agents / skills / prompt-blocks /
+     * mcp-clients / mcp-servers / scorer-definitions) sweep orphaned draft
+     * thin-row records during `init()`  i.e. drafts whose paired version
+     * row was never written. The transactional `create()` rewrite makes
+     * these orphans impossible going forward; this opt-in is for cleaning
+     * up legacy data left by older deployments or for environments where
+     * the small startup cost is acceptable.
+     * @default false
+     */
+    cleanupStaleDraftsOnStartup?: boolean;
+    /**
+     * Restricts which storage domains this adapter constructs and initializes.
+     *
+     * When omitted (the default), all domains the adapter implements are
+     * registered, matching historical behavior. When provided, only the listed
+     * domains are constructed and added to `this.stores`; `init()` will only
+     * touch those domains, and `getStore()` returns `undefined` for the rest.
+     *
+     * Useful when another store owns some domains in a composite, or when the
+     * deployment environment manages only a subset of the schema (e.g. a
+     * workflows-only Spanner database in `initMode: 'validate'`, where
+     * validating tables for unused domains would fail).
+     */
+    enabledDomains?: ReadonlyArray<SpannerDomainKey>;
+    /**
+     * Maximum acceptable staleness (in milliseconds) for the observability
+     * domain's read paths (metrics list / aggregates / breakdowns /
+     * time-series / percentiles / discovery). When set to a positive value,
+     * those queries run as bounded-staleness single-use reads, which Spanner
+     * can route to any replica that's at least that fresh. They stop
+     * competing with leader-region writes for CPU and can land on a closer
+     * replica.
+     *
+     * Default is `10000` (weak reads against the leader).
+     * @default 10000
+     */
+    dashboardStalenessMs?: number;
+    /**
+     * When true (the default), the observability domain's metric methods
+     * throw `*_NOT_IMPLEMENTED` and the metrics table is not created during
+     * `init()`. The `MastraStorageExporter` reads those errors and silently
+     * drops metric emissions.
+     *
+     * This is the recommended default because Spanner is row-oriented and
+     * OLTP-shaped — the metrics workload is write-heavy, scan-heavy, and
+     * benefits from columnar storage. Pair Spanner spans with a dedicated
+     * OLAP metrics store (DuckDB, ClickHouse) via a
+     * `MastraCompositeStore`-level wrapper that fans out by signal.
+     * @default true
+     */
+    disableMetrics?: boolean;
+} & ({
+    /** Pre-configured Spanner Database handle. */
+    database: Database;
+} | {
+    projectId: string;
+    instanceId: string;
+    databaseId: string;
+    /**
+     * Optional pass-through to the `@google-cloud/spanner` client constructor.
+     * Useful for credentials, custom service paths (e.g. against the emulator),
+     * or auth overrides.
+     */
+    spannerOptions?: ConstructorParameters<typeof Spanner>[0];
+});
+export type SpannerConfig = SpannerConfigType;
+/**
+ * Google Cloud Spanner storage adapter for Mastra. Implements the GoogleSQL
+ * dialect of Cloud Spanner.
+ *
+ * @example
+ * ```typescript
+ * const storage = new SpannerStore({
+ *   id: 'my-store',
+ *   projectId: 'my-project',
+ *   instanceId: 'my-instance',
+ *   databaseId: 'mastra',
+ * });
+ *
+ * const memory = await storage.getStore('memory');
+ * await memory?.saveThread({ thread });
+ * ```
+ */
+export declare class SpannerStore extends MastraCompositeStore {
+    database: Database;
+    spanner?: Spanner;
+    instance?: Instance;
+    private readonly ownsClient;
+    stores: StorageDomains;
+    constructor(config: SpannerConfigType);
+    /**
+     * Initializes the storage by running each domain's `init()` sequentially.
+     *
+     * Spanner does not allow concurrent schema changes against the same database,
+     * so the default `MastraCompositeStore.init()` (which fans out via
+     * `Promise.all`) cannot be used here.
+     *
+     * Concurrent callers all await the same in-flight promise: the first call
+     * installs a pending `hasInitialized` immediately, before any awaits, so a
+     * second caller landing on `init()` sees it and queues behind the same loop
+     * instead of starting its own.
+     */
+    init(): Promise<void>;
+    /**
+     * Closes the Spanner client and database handle if this store owns them.
+     * Pre-configured databases are left alone for the caller to manage.
+     */
+    close(): Promise<void>;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/storage/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/storage/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAC;AAChD,OAAO,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAEhE,OAAO,EAAwB,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAClF,OAAO,KAAK,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAE/E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,MAAM,CAAC;AAC5C,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACjD,OAAO,EAAE,sBAAsB,EAAE,MAAM,4BAA4B,CAAC;AACpE,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAC/C,OAAO,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAC1D,OAAO,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAC1D,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACjD,OAAO,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AAC/D,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAC9D,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,EAAE,wBAAwB,EAAE,MAAM,8BAA8B,CAAC;AACxE,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACjD,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAGvD,OAAO,EACL,aAAa,EACb,sBAAsB,EACtB,YAAY,EACZ,iBAAiB,EACjB,iBAAiB,EACjB,aAAa,EACb,oBAAoB,EACpB,mBAAmB,EACnB,gBAAgB,EAChB,wBAAwB,EACxB,aAAa,EACb,aAAa,EACb,gBAAgB,GACjB,CAAC;AACF,YAAY,EAAE,mBAAmB,EAAE,eAAe,EAAE,MAAM,MAAM,CAAC;AAEjE,uFAAuF;AACvF,eAAO,MAAM,mBAAmB,2LAcwB,CAAC;AAEzD,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,mBAAmB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEpE;;;;;;;GAOG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX;;;;;;OAMG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;;OAGG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B;;;OAGG;IACH,OAAO,CAAC,EAAE,kBAAkB,EAAE,CAAC;IAC/B;;;;;;;;;;;;;;OAcG;IACH,QAAQ,CAAC,EAAE,eAAe,CAAC;IAC3B;;;;;;;;;OASG;IACH,2BAA2B,CAAC,EAAE,OAAO,CAAC;IACtC;;;;;;;;;;;;OAYG;IACH,cAAc,CAAC,EAAE,aAAa,CAAC,gBAAgB,CAAC,CAAC;IACjD;;;;;;;;;;;OAWG;IACH,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B;;;;;;;;;;;;OAYG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B,GAAG,CACA;IACE,8CAA8C;IAC9C,QAAQ,EAAE,QAAQ,CAAC;CACpB,GACD;IACE,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,cAAc,CAAC,EAAE,qBAAqB,CAAC,OAAO,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC;CAC3D,CACJ,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG,iBAAiB,CAAC;AAK9C;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,YAAa,SAAQ,oBAAoB;IAC7C,QAAQ,EAAE,QAAQ,CAAC;IACnB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,QAAQ,CAAC,EAAE,QAAQ,CAAC;IAC3B,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAU;IACrC,MAAM,EAAE,cAAc,CAAC;gBAEX,MAAM,EAAE,iBAAiB;IA8ErC;;;;;;;;;;;OAWG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAgE3B;;;OAGG;IACG,KAAK;CAaZ"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/spanner",
-  "version": "0.0.0",
+  "version": "1.0.0-alpha.0",
   "description": "Google Cloud Spanner provider for Mastra - db storage capabilities (GoogleSQL dialect)",
   "type": "module",
   "main": "dist/index.js",
@@ -31,8 +31,8 @@
     "typescript": "^6.0.3",
     "vitest": "4.1.5",
     "@internal/lint": "0.0.97",
-    "@mastra/core": "1.37.0-alpha.7",
     "@internal/storage-test-utils": "0.0.93",
+    "@mastra/core": "1.37.0-alpha.8",
     "@internal/types-builder": "0.0.72"
   },
   "peerDependencies": {