From e797676a02380273d8031d07dbb04cd2fe1622d0 Mon Sep 17 00:00:00 2001
From: Jarvis <jarvis@mosaicstack.dev>
Date: Thu, 2 Apr 2026 20:22:55 -0500
Subject: [PATCH] feat(storage): define StorageAdapter interface types +
 scaffold package

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 packages/storage/package.json  | 32 +++++++++++++++++++++++++
 packages/storage/src/index.ts  |  1 +
 packages/storage/src/types.ts  | 43 ++++++++++++++++++++++++++++++++++
 packages/storage/tsconfig.json |  9 +++++++
 4 files changed, 85 insertions(+)
 create mode 100644 packages/storage/package.json
 create mode 100644 packages/storage/src/index.ts
 create mode 100644 packages/storage/src/types.ts
 create mode 100644 packages/storage/tsconfig.json

diff --git a/packages/storage/package.json b/packages/storage/package.json
new file mode 100644
index 0000000..3b233ec
--- /dev/null
+++ b/packages/storage/package.json
@@ -0,0 +1,32 @@
+{
+  "name": "@mosaic/storage",
+  "version": "0.0.2",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "lint": "eslint src",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --passWithNoTests"
+  },
+  "dependencies": {
+    "@mosaic/types": "workspace:*"
+  },
+  "devDependencies": {
+    "typescript": "^5.8.0",
+    "vitest": "^2.0.0"
+  },
+  "publishConfig": {
+    "registry": "https://git.mosaicstack.dev/api/packages/mosaic/npm/",
+    "access": "public"
+  },
+  "files": [
+    "dist"
+  ]
+}
diff --git a/packages/storage/src/index.ts b/packages/storage/src/index.ts
new file mode 100644
index 0000000..ae787eb
--- /dev/null
+++ b/packages/storage/src/index.ts
@@ -0,0 +1 @@
+export type { StorageAdapter, StorageConfig } from './types.js';
diff --git a/packages/storage/src/types.ts b/packages/storage/src/types.ts
new file mode 100644
index 0000000..75d1d0d
--- /dev/null
+++ b/packages/storage/src/types.ts
@@ -0,0 +1,43 @@
+export interface StorageAdapter {
+  readonly name: string;
+
+  create<T extends Record<string, unknown>>(
+    collection: string,
+    data: T,
+  ): Promise<T & { id: string }>;
+
+  read<T extends Record<string, unknown>>(collection: string, id: string): Promise<T | null>;
+
+  update(collection: string, id: string, data: Record<string, unknown>): Promise<boolean>;
+
+  delete(collection: string, id: string): Promise<boolean>;
+
+  find<T extends Record<string, unknown>>(
+    collection: string,
+    filter?: Record<string, unknown>,
+    opts?: {
+      limit?: number;
+      offset?: number;
+      orderBy?: string;
+      order?: 'asc' | 'desc';
+    },
+  ): Promise<T[]>;
+
+  findOne<T extends Record<string, unknown>>(
+    collection: string,
+    filter: Record<string, unknown>,
+  ): Promise<T | null>;
+
+  count(collection: string, filter?: Record<string, unknown>): Promise<number>;
+
+  transaction<T>(fn: (tx: StorageAdapter) => Promise<T>): Promise<T>;
+
+  migrate(): Promise<void>;
+
+  close(): Promise<void>;
+}
+
+export type StorageConfig =
+  | { type: 'postgres'; url: string }
+  | { type: 'sqlite'; path: string }
+  | { type: 'files'; dataDir: string; format?: 'json' | 'md' };
diff --git a/packages/storage/tsconfig.json b/packages/storage/tsconfig.json
new file mode 100644
index 0000000..c973386
--- /dev/null
+++ b/packages/storage/tsconfig.json
@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}