@workglow/storage 0.0.85 → 0.0.86

package/dist/vector/PostgresVectorStorage.d.ts

@@ -0,0 +1,57 @@
+/**
+ * @license
+ * Copyright 2025 Steven Roussey <sroussey@gmail.com>
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { DataPortSchemaObject, FromSchema, TypedArray, TypedArraySchemaOptions } from "@workglow/util";
+import type { Pool } from "pg";
+import { PostgresTabularStorage } from "../tabular/PostgresTabularStorage";
+import { type HybridSearchOptions, type IVectorStorage, type VectorSearchOptions } from "./IVectorStorage";
+/**
+ * PostgreSQL vector repository implementation using pgvector extension.
+ * Extends PostgresTabularStorage for storage.
+ * Provides efficient vector similarity search with native database support.
+ *
+ * Requirements:
+ * - PostgreSQL database with pgvector extension installed
+ * - CREATE EXTENSION vector;
+ *
+ * @template Metadata - The metadata type
+ * @template Vector - The vector type
+ */
+export declare class PostgresVectorStorage<Schema extends DataPortSchemaObject, PrimaryKeyNames extends ReadonlyArray<keyof Schema["properties"]>, Metadata extends Record<string, unknown> = Record<string, unknown>, Vector extends TypedArray = Float32Array, Entity = FromSchema<Schema, TypedArraySchemaOptions>> extends PostgresTabularStorage<Schema, PrimaryKeyNames, Entity> implements IVectorStorage<Metadata, Schema, Entity, PrimaryKeyNames> {
+    private vectorDimensions;
+    private VectorType;
+    private vectorPropertyName;
+    private metadataPropertyName;
+    /**
+     * Creates a new PostgreSQL vector repository
+     * @param db - PostgreSQL connection pool
+     * @param table - The name of the table to use for storage
+     * @param schema - The schema definition for the entity
+     * @param primaryKeyNames - Array of property names that form the primary key
+     * @param indexes - Array of columns or column arrays to make searchable
+     * @param dimensions - The number of dimensions of the vector
+     * @param VectorType - The type of vector to use (defaults to Float32Array)
+     */
+    constructor(db: Pool, table: string, schema: Schema, primaryKeyNames: PrimaryKeyNames, indexes: readonly (keyof Entity | readonly (keyof Entity)[])[] | undefined, dimensions: number, VectorType?: new (array: number[]) => TypedArray);
+    getVectorDimensions(): number;
+    similaritySearch(query: TypedArray, options?: VectorSearchOptions<Metadata>): Promise<Array<Entity & {
+        score: number;
+    }>>;
+    hybridSearch(query: TypedArray, options: HybridSearchOptions<Metadata>): Promise<(Entity & {
+        score: number;
+    })[]>;
+    /**
+     * Fallback search using in-memory cosine similarity
+     */
+    private searchFallback;
+    /**
+     * Fallback hybrid search
+     */
+    private hybridSearchFallback;
+    private getPrimaryKeyWhereClause;
+    private getPrimaryKeyValues;
+    private matchesFilter;
+}
+//# sourceMappingURL=PostgresVectorStorage.d.ts.map

package/dist/vector/PostgresVectorStorage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PostgresVectorStorage.d.ts","sourceRoot":"","sources":["../../src/vector/PostgresVectorStorage.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EACV,oBAAoB,EACpB,UAAU,EACV,UAAU,EACV,uBAAuB,EACxB,MAAM,gBAAgB,CAAC;AAExB,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,IAAI,CAAC;AAC/B,OAAO,EAAE,sBAAsB,EAAE,MAAM,mCAAmC,CAAC;AAC3E,OAAO,EAGL,KAAK,mBAAmB,EACxB,KAAK,cAAc,EACnB,KAAK,mBAAmB,EACzB,MAAM,kBAAkB,CAAC;AAE1B;;;;;;;;;;;GAWG;AACH,qBAAa,qBAAqB,CAChC,MAAM,SAAS,oBAAoB,EACnC,eAAe,SAAS,aAAa,CAAC,MAAM,MAAM,CAAC,YAAY,CAAC,CAAC,EACjE,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAClE,MAAM,SAAS,UAAU,GAAG,YAAY,EACxC,MAAM,GAAG,UAAU,CAAC,MAAM,EAAE,uBAAuB,CAAC,CAEpD,SAAQ,sBAAsB,CAAC,MAAM,EAAE,eAAe,EAAE,MAAM,CAC9D,YAAW,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,eAAe,CAAC;IAEpE,OAAO,CAAC,gBAAgB,CAAS;IACjC,OAAO,CAAC,UAAU,CAAsC;IACxD,OAAO,CAAC,kBAAkB,CAAe;IACzC,OAAO,CAAC,oBAAoB,CAA2B;IAEvD;;;;;;;;;OASG;gBAED,EAAE,EAAE,IAAI,EACR,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,eAAe,EAAE,eAAe,EAChC,OAAO,EAAE,SAAS,CAAC,MAAM,MAAM,GAAG,SAAS,CAAC,MAAM,MAAM,CAAC,EAAE,CAAC,EAAE,YAAK,EACnE,UAAU,EAAE,MAAM,EAClB,UAAU,GAAE,KAAK,KAAK,EAAE,MAAM,EAAE,KAAK,UAAyB;IAgBhE,mBAAmB,IAAI,MAAM;IAIvB,gBAAgB,CACpB,KAAK,EAAE,UAAU,EACjB,OAAO,GAAE,mBAAmB,CAAC,QAAQ,CAAM,GAC1C,OAAO,CAAC,KAAK,CAAC,MAAM,GAAG;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAkEvC,YAAY,CAAC,KAAK,EAAE,UAAU,EAAE,OAAO,EAAE,mBAAmB,CAAC,QAAQ,CAAC;eAlEzC,MAAM;;IA+IzC;;OAEG;YACW,cAAc;IA4B5B;;OAEG;YACW,oBAAoB;IA4ClC,OAAO,CAAC,wBAAwB;IAOhC,OAAO,CAAC,mBAAmB;IAI3B,OAAO,CAAC,aAAa;CAQtB"}

package/dist/vector/SqliteVectorStorage.d.ts

@@ -0,0 +1,45 @@
+/**
+ * @license
+ * Copyright 2025 Steven Roussey <sroussey@gmail.com>
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Sqlite } from "@workglow/sqlite";
+import type { DataPortSchemaObject, FromSchema, TypedArray, TypedArraySchemaOptions } from "@workglow/util";
+import { SqliteTabularStorage } from "../tabular/SqliteTabularStorage";
+import { type HybridSearchOptions, type IVectorStorage, type VectorSearchOptions } from "./IVectorStorage";
+/**
+ * SQLite vector repository implementation using tabular storage underneath.
+ * Stores vectors as JSON-encoded arrays with metadata.
+ *
+ * @template Vector - The vector type for the vector
+ * @template Metadata - The metadata type for the vector
+ * @template Schema - The schema for the vector
+ * @template PrimaryKeyNames - The primary key names for the vector
+ */
+export declare class SqliteVectorStorage<Schema extends DataPortSchemaObject, PrimaryKeyNames extends ReadonlyArray<keyof Schema["properties"]>, Vector extends TypedArray = Float32Array, Metadata extends Record<string, unknown> | undefined = Record<string, unknown>, Entity = FromSchema<Schema, TypedArraySchemaOptions>> extends SqliteTabularStorage<Schema, PrimaryKeyNames, Entity> implements IVectorStorage<Metadata, Schema, Entity, PrimaryKeyNames> {
+    private vectorDimensions;
+    private VectorType;
+    private vectorPropertyName;
+    private metadataPropertyName;
+    /**
+     * Creates a new SQLite vector repository
+     * @param dbOrPath - Either a Database instance or a path to the SQLite database file
+     * @param table - The name of the table to use for storage (defaults to 'vectors')
+     * @param dimensions - The number of dimensions of the vector
+     * @param VectorType - The type of vector to use (defaults to Float32Array)
+     */
+    constructor(dbOrPath: string | Sqlite.Database, table: string | undefined, schema: Schema, primaryKeyNames: PrimaryKeyNames, indexes: readonly (keyof Entity | readonly (keyof Entity)[])[] | undefined, dimensions: number, VectorType?: new (array: number[]) => TypedArray);
+    getVectorDimensions(): number;
+    /**
+     * Deserialize vector from JSON string
+     * Defaults to Float32Array for compatibility with typical embedding vectors
+     */
+    private deserializeVector;
+    similaritySearch(query: TypedArray, options?: VectorSearchOptions<Metadata>): Promise<(Entity & {
+        score: number;
+    })[]>;
+    hybridSearch(query: TypedArray, options: HybridSearchOptions<Metadata>): Promise<(Entity & {
+        score: number;
+    })[]>;
+}
+//# sourceMappingURL=SqliteVectorStorage.d.ts.map

package/dist/vector/SqliteVectorStorage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SqliteVectorStorage.d.ts","sourceRoot":"","sources":["../../src/vector/SqliteVectorStorage.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAC1C,OAAO,KAAK,EACV,oBAAoB,EACpB,UAAU,EACV,UAAU,EACV,uBAAuB,EACxB,MAAM,gBAAgB,CAAC;AAExB,OAAO,EAAE,oBAAoB,EAAE,MAAM,iCAAiC,CAAC;AACvE,OAAO,EAGL,KAAK,mBAAmB,EACxB,KAAK,cAAc,EACnB,KAAK,mBAAmB,EACzB,MAAM,kBAAkB,CAAC;AAc1B;;;;;;;;GAQG;AACH,qBAAa,mBAAmB,CAC9B,MAAM,SAAS,oBAAoB,EACnC,eAAe,SAAS,aAAa,CAAC,MAAM,MAAM,CAAC,YAAY,CAAC,CAAC,EACjE,MAAM,SAAS,UAAU,GAAG,YAAY,EACxC,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9E,MAAM,GAAG,UAAU,CAAC,MAAM,EAAE,uBAAuB,CAAC,CAEpD,SAAQ,oBAAoB,CAAC,MAAM,EAAE,eAAe,EAAE,MAAM,CAC5D,YAAW,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,eAAe,CAAC;IAEpE,OAAO,CAAC,gBAAgB,CAAS;IACjC,OAAO,CAAC,UAAU,CAAsC;IACxD,OAAO,CAAC,kBAAkB,CAAe;IACzC,OAAO,CAAC,oBAAoB,CAA2B;IAEvD;;;;;;OAMG;gBAED,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC,QAAQ,EAClC,KAAK,EAAE,MAAM,YAAY,EACzB,MAAM,EAAE,MAAM,EACd,eAAe,EAAE,eAAe,EAChC,OAAO,EAAE,SAAS,CAAC,MAAM,MAAM,GAAG,SAAS,CAAC,MAAM,MAAM,CAAC,EAAE,CAAC,EAAE,YAAK,EACnE,UAAU,EAAE,MAAM,EAClB,UAAU,GAAE,KAAK,KAAK,EAAE,MAAM,EAAE,KAAK,UAAyB;IAgBhE,mBAAmB,IAAI,MAAM;IAI7B;;;OAGG;IACH,OAAO,CAAC,iBAAiB;IAMnB,gBAAgB,CAAC,KAAK,EAAE,UAAU,EAAE,OAAO,GAAE,mBAAmB,CAAC,QAAQ,CAAM;eAE5C,MAAM;;IAsCzC,YAAY,CAAC,KAAK,EAAE,UAAU,EAAE,OAAO,EAAE,mBAAmB,CAAC,QAAQ,CAAC;eAtCnC,MAAM;;CAoGhD"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@workglow/storage",
   "type": "module",
-  "version": "0.0.85",
+  "version": "0.0.86",
   "description": "Storage abstraction layer for Workglow, supporting IndexedDB, PostgreSQL, and Supabase with unified interfaces.",
   "scripts": {
     "watch": "concurrently -c 'auto' 'bun:watch-*'",
@@ -20,8 +20,8 @@
     "prepare": "node -e \"const pkg=require('./package.json');pkg.exports['.'].bun='./dist/bun.js';pkg.exports['.'].types='./dist/types.d.ts';require('fs').writeFileSync('package.json',JSON.stringify(pkg,null,2))\""
   },
   "peerDependencies": {
-    "@workglow/sqlite": "0.0.85",
-    "@workglow/util": "0.0.85",
+    "@workglow/sqlite": "0.0.86",
+    "@workglow/util": "0.0.86",
     "pg": "^8.16.3",
     "@supabase/supabase-js": "^2.89.0"
   },
@@ -34,8 +34,8 @@
     }
   },
   "devDependencies": {
-    "@workglow/sqlite": "0.0.85",
-    "@workglow/util": "0.0.85",
+    "@workglow/sqlite": "0.0.86",
+    "@workglow/util": "0.0.86",
     "pg": "^8.16.3",
     "@types/pg": "^8.15.5",
     "@supabase/supabase-js": "^2.89.0",

package/src/kv/README.md

@@ -23,7 +23,7 @@ A flexible key-value storage solution with multiple backend implementations. Pro
   - 💾 `IndexedDbKvRepository` - Browser IndexedDB storage
   - 🐘 `PostgresKvRepository` - PostgreSQL database storage
   - 📁 `SqliteKvRepository` - SQLite database storage
-  - 🧠 `InMemoryKvRepository` - Volatile memory storage
+  - 🧠 `InMemoryKvStorage` - Volatile memory storage
 - Type-safe key/value definitions
 - JSON value serialization support
 - Event emitter for storage operations (put/get/delete)
@@ -104,9 +104,9 @@ await sqliteRepo.put("temp:789", "cached_value");
 ### In-Memory Storage
 
 ```typescript
-import { InMemoryKvRepository } from "@workglow/storage/kv";
+import { InMemoryKvStorage } from "@workglow/storage/kv";
 
-const memRepo = new InMemoryKvRepository(
+const memRepo = new InMemoryKvStorage(
   "string", // Key type
   "json" // Value type
 );

package/src/tabular/README.md

@@ -9,11 +9,11 @@ A collection of storage implementations for tabular data with multiple backend s
   - [Using TypeBox](#using-typebox)
   - [Using Zod 4](#using-zod-4)
 - [Implementations](#implementations)
-  - [InMemoryTabularRepository](#inmemorytabularrepository)
-  - [SqliteTabularRepository](#sqlitetabularrepository)
-  - [PostgresTabularRepository](#postgrestabularrepository)
-  - [IndexedDbTabularRepository](#indexeddbtabularrepository)
-  - [FsFolderTabularRepository](#fsfoldertabularrepository)
+  - [InMemoryTabularStorage](#inmemorytabularrepository)
+  - [SqliteTabularStorage](#sqlitetabularrepository)
+  - [PostgresTabularStorage](#postgrestabularrepository)
+  - [IndexedDbTabularStorage](#indexeddbtabularrepository)
+  - [FsFolderTabularStorage](#fsfoldertabularrepository)
 - [Events](#events)
 - [Testing](#testing)
 - [License](#license)
@@ -43,7 +43,7 @@ npm install @workglow/storage
 ## Basic Usage
 
 ```typescript
-import { InMemoryTabularRepository } from "@workglow/storage/tabular";
+import { InMemoryTabularStorage } from "@workglow/storage/tabular";
 
 // Define schema and primary keys
 const schema = {
@@ -55,8 +55,8 @@ const schema = {
 
 const primaryKeys = ["id"] as const;
 // Create repository instance (when using const schemas, the next three generics
-// on InMemoryTabularRepository are automatically created for you)
-const repo = new InMemoryTabularRepository<typeof schema, typeof primaryKeys>(schema, primaryKeys);
+// on InMemoryTabularStorage are automatically created for you)
+const repo = new InMemoryTabularStorage<typeof schema, typeof primaryKeys>(schema, primaryKeys);
 
 // Basic operations
 await repo.put({ id: "1", name: "Alice", age: 30, active: true });
@@ -75,9 +75,9 @@ You can define schemas using plain JSON Schema objects, or use schema libraries
 TypeBox schemas are JSON Schema compatible and can be used directly:
 
 ```typescript
-import { InMemoryTabularRepository } from "@workglow/storage/tabular";
+import { InMemoryTabularStorage } from "@workglow/storage/tabular";
 import { Type, Static } from "@sinclair/typebox";
-import { DataPortSchemaObject, FromSchema, IncludeProps, ExcludeProps } from "@workglow/util";
+import { DataPortSchemaObject, FromSchema } from "@workglow/util";
 
 // Define schema using TypeBox
 const userSchema = Type.Object({
@@ -98,7 +98,7 @@ type UserEntity = FromSchema<typeof userSchema>;
 
 // IMPORTANT: You must explicitly provide generic type parameters for t
 // TypeScript cannot infer them from TypeBox schemas
-const repo = new InMemoryTabularRepository<typeof userSchema, typeof primaryKeys, UserEntity>(
+const repo = new InMemoryTabularStorage<typeof userSchema, typeof primaryKeys, UserEntity>(
   userSchema,
   primaryKeys,
   ["email", "active"] as const // Indexes
@@ -119,7 +119,7 @@ await repo.put({
 Zod 4 has built-in JSON Schema support using the `.toJSONSchema()` method:
 
 ```typescript
-import { InMemoryTabularRepository } from "@workglow/storage/tabular";
+import { InMemoryTabularStorage } from "@workglow/storage/tabular";
 import { z } from "zod";
 import { DataPortSchemaObject } from "@workglow/util";
 
@@ -141,7 +141,7 @@ type UserEntity = z.infer<typeof userSchemaZod>;
 
 // IMPORTANT: You must explicitly provide generic type parameters
 // TypeScript cannot infer them from Zod schemas (even after conversion)
-const repo = new InMemoryTabularRepository<typeof userSchema, typeof primaryKeys, UserEntity>(
+const repo = new InMemoryTabularStorage<typeof userSchema, typeof primaryKeys, UserEntity>(
   userSchema,
   primaryKeys,
   ["email", "active"] as const // Indexes
@@ -157,16 +157,179 @@ await repo.put({
 });
 ```
 
+## Auto-Generated Primary Keys
+
+TabularStorage supports automatic generation of primary keys, allowing the storage backend to generate IDs when entities are inserted without them. This is useful for:
+
+- Security: Preventing clients from choosing arbitrary IDs
+- Simplicity: No need to generate IDs client-side
+- Database features: Leveraging native auto-increment and UUID generation
+
+### Schema Configuration
+
+Mark a primary key column as auto-generated using the `x-auto-generated: true` annotation:
+
+```typescript
+const UserSchema = {
+  type: "object",
+  properties: {
+    id: { type: "integer", "x-auto-generated": true }, // Auto-increment
+    name: { type: "string" },
+    email: { type: "string" },
+  },
+  required: ["id", "name", "email"],
+  additionalProperties: false,
+} as const satisfies DataPortSchemaObject;
+
+const DocumentSchema = {
+  type: "object",
+  properties: {
+    id: { type: "string", "x-auto-generated": true }, // UUID
+    title: { type: "string" },
+    content: { type: "string" },
+  },
+  required: ["id", "title", "content"],
+  additionalProperties: false,
+} as const satisfies DataPortSchemaObject;
+```
+
+**Generation Strategy (inferred from column type):**
+
+- `type: "integer"` → Auto-increment (SERIAL, INTEGER PRIMARY KEY, counter)
+- `type: "string"` → UUID via `uuid4()` from `@workglow/util`
+
+**Constraints:**
+
+- Only the **first column** in a compound primary key can be auto-generated
+- Only **one column** can be auto-generated per table
+
+### Basic Usage
+
+```typescript
+import { InMemoryTabularStorage } from "@workglow/storage/tabular";
+
+const userStorage = new InMemoryTabularStorage(UserSchema, ["id"] as const);
+await userStorage.setupDatabase();
+
+// Insert without providing ID - it will be auto-generated
+const user = await userStorage.put({
+  name: "Alice",
+  email: "alice@example.com",
+});
+console.log(user.id); // 1 (auto-generated)
+
+// TypeScript enforces: id is optional on insert, required on returned entity
+```
+
+### Client-Provided Keys Configuration
+
+Control whether clients can provide values for auto-generated keys:
+
+```typescript
+const storage = new PostgresTabularStorage(
+  db,
+  "users",
+  UserSchema,
+  ["id"] as const,
+  [], // indexes
+  { clientProvidedKeys: "if-missing" } // configuration
+);
+```
+
+**Options:**
+
+| Setting                  | Behavior                                         | Use Case                                                          |
+| ------------------------ | ------------------------------------------------ | ----------------------------------------------------------------- |
+| `"if-missing"` (default) | Use client value if provided, generate otherwise | Flexible - supports both auto-generation and client-specified IDs |
+| `"never"`                | Always generate, ignore client values            | Maximum security - never trust client IDs                         |
+| `"always"`               | Require client to provide value                  | Testing/migration - enforce client-side ID generation             |
+
+**Examples:**
+
+```typescript
+// Default: "if-missing" - flexible
+const flexibleStorage = new InMemoryTabularStorage(UserSchema, ["id"] as const);
+
+// Without ID - auto-generated
+await flexibleStorage.put({ name: "Bob", email: "bob@example.com" });
+
+// With ID - uses client value
+await flexibleStorage.put({ id: 999, name: "Charlie", email: "charlie@example.com" });
+
+// Secure mode: "never" - always generate
+const secureStorage = new PostgresTabularStorage(db, "users", UserSchema, ["id"] as const, [], {
+  clientProvidedKeys: "never",
+});
+
+// Even if client provides id, it will be ignored and regenerated
+const result = await secureStorage.put({
+  id: 999, // Ignored!
+  name: "Diana",
+  email: "diana@example.com",
+});
+// result.id will be database-generated, NOT 999
+
+// Testing mode: "always" - require client ID
+const testStorage = new InMemoryTabularStorage(UserSchema, ["id"] as const, [], {
+  clientProvidedKeys: "always",
+});
+
+// Must provide ID or throws error
+await testStorage.put({
+  id: 1,
+  name: "Eve",
+  email: "eve@example.com",
+}); // OK
+
+await testStorage.put({
+  name: "Frank",
+  email: "frank@example.com",
+}); // Throws Error!
+```
+
+### Backend-Specific Behavior
+
+Each storage backend implements auto-generation differently:
+
+| Backend                     | Integer (autoincrement)             | String (UUID)                     |
+| --------------------------- | ----------------------------------- | --------------------------------- |
+| **InMemoryTabularStorage**  | Internal counter (1, 2, 3...)       | `uuid4()` from `@workglow/util`   |
+| **SqliteTabularStorage**    | `INTEGER PRIMARY KEY AUTOINCREMENT` | `uuid4()` client-side             |
+| **PostgresTabularStorage**  | `SERIAL`/`BIGSERIAL`                | `gen_random_uuid()` database-side |
+| **SupabaseTabularStorage**  | `SERIAL`                            | `gen_random_uuid()` database-side |
+| **IndexedDbTabularStorage** | `autoIncrement: true`               | `uuid4()` client-side             |
+| **FsFolderTabularStorage**  | Internal counter                    | `uuid4()` from `@workglow/util`   |
+
+### Constraints
+
+1. **Only first column**: Only the first primary key column can be auto-generated
+2. **Single auto-gen key**: Only one column per table can be auto-generated
+3. **Type inference**: Generation strategy is inferred from column type (integer → autoincrement, string → UUID)
+
+### Type Safety
+
+TypeScript enforces correct usage through the type system:
+
+```typescript
+// Auto-generated key is OPTIONAL on insert
+const entity = { name: "Alice", email: "alice@example.com" };
+await storage.put(entity); // ✅ OK - id can be omitted
+
+// Returned entity has ALL fields REQUIRED
+const result = await storage.put(entity);
+const id: number = result.id; // ✅ OK - id is guaranteed to exist
+```
+
 ## Implementations
 
-### InMemoryTabularRepository
+### InMemoryTabularStorage
 
 - Ideal for testing/development
 - No persistence
 - Fast search capabilities
 
 ```typescript
-const repo = new InMemoryTabularRepository<
+const repo = new InMemoryTabularStorage<
   typeof schema,
   typeof primaryKeys,
   Entity, // required if using TypeBox, Zod, etc, otherwise automatically created
@@ -175,13 +338,13 @@ const repo = new InMemoryTabularRepository<
 >(schema, primaryKeys, ["name", "active"]);
 ```
 
-### SqliteTabularRepository
+### SqliteTabularStorage
 
 - Embedded SQLite database
 - File-based or in-memory
 
 ```typescript
-const repo = new SqliteTabularRepository<
+const repo = new SqliteTabularStorage<
   typeof schema,
   typeof primaryKeys,
   Entity, // required if using TypeBox, Zod, etc, otherwise automatically created
@@ -196,7 +359,7 @@ const repo = new SqliteTabularRepository<
 );
 ```
 
-### PostgresTabularRepository
+### PostgresTabularStorage
 
 - PostgreSQL backend
 - Connection pooling support
@@ -207,7 +370,7 @@ import { Pool } from "pg";
 const pool = new Pool({
   /* config */
 });
-const repo = new PostgresTabularRepository<
+const repo = new PostgresTabularStorage<
   typeof schema,
   typeof primaryKeys,
   Entity, // required if using TypeBox, Zod, etc, otherwise automatically created
@@ -222,13 +385,13 @@ const repo = new PostgresTabularRepository<
 );
 ```
 
-### IndexedDbTabularRepository
+### IndexedDbTabularStorage
 
 - Browser-based storage
 - Automatic schema migration
 
 ```typescript
-const repo = new IndexedDbTabularRepository<
+const repo = new IndexedDbTabularStorage<
   typeof schema,
   typeof primaryKeys,
   Entity, // required if using TypeBox, Zod, etc, otherwise automatically created
@@ -242,13 +405,13 @@ const repo = new IndexedDbTabularRepository<
 );
 ```
 
-### FsFolderTabularRepository
+### FsFolderTabularStorage
 
 - Filesystem storage (one JSON file per record)
 - Simple persistence format
 
 ```typescript
-const repo = new FsFolderTabularRepository<
+const repo = new FsFolderTabularStorage<
   typeof schema,
   typeof primaryKeys,
   Entity, // required if using TypeBox, Zod, etc, otherwise automatically created