@lyku/lockstep-pg 0.1.1 → 1.3.1

package/README.md

@@ -1,14 +1,22 @@
 # @lyku/lockstep-pg
 
-Schema-driven PostgreSQL migration toolkit for [`@lyku/lockstep-core`](../from-schema) models. Detects drift between your code-defined schemas and the live database, then generates safe (and optionally destructive) SQL migrations.
+Schema-driven PostgreSQL migration toolkit for [`@lyku/lockstep-core`](../lockstep-core) models. Detects drift between your code-defined schemas and a live database, then generates safe (and optionally destructive) SQL migrations.
 
 ## Features
 
-- **Drift detection** - Compare `PostgresTableModel` definitions against a live PostgreSQL database
-- **Introspection** - Read table structure, indexes, constraints, and foreign keys from any Postgres database
-- **Diff engine** - Structural diff between introspected tables and code models, categorized into safe vs. destructive operations
-- **SQL generation** - Produces migration SQL from diffs or drift reports, including `CREATE TABLE`, `ALTER COLUMN`, `ADD INDEX`, enum `CHECK` constraint updates, and stock document seeding
-- **Seed data** - Generate `INSERT ... ON CONFLICT DO NOTHING` statements for stock/fixture documents defined in table models
+- **Drift detection** — compare `PostgresTableModel` definitions against a live PostgreSQL database
+- **Introspection** — read table structure, indexes, constraints, and foreign keys from any Postgres database
+- **Diff engine** — structural diff between introspected tables and code models, categorized into safe vs. destructive operations
+- **SQL generation** — produces migration SQL from diffs or drift reports, including `CREATE TABLE`, `ALTER COLUMN`, `ADD INDEX`, enum `CHECK` constraint updates, and stock document seeding
+- **Seed data** — generate `INSERT ... ON CONFLICT DO NOTHING` statements for fixture documents defined in table models
+
+## Installation
+
+```bash
+npm install @lyku/lockstep-pg
+```
+
+Requires `@lyku/lockstep-core` as a peer dependency and `pg` for database connections.
 
 ## Usage
 
@@ -16,17 +24,21 @@ Schema-driven PostgreSQL migration toolkit for [`@lyku/lockstep-core`](../from-s
 
 ```typescript
 import { detectDrift } from '@lyku/lockstep-pg';
-import { tables } from '@lyku/pg-config';
+
+const tables = {
+	users: usersModel,
+	posts: postsModel,
+	// ... your PostgresRecordModel definitions
+};
 
 const drifts = await detectDrift(process.env.PG_CONNECTION_STRING, { tables });
-// Returns Drift[] - missing tables, extra columns, type mismatches, missing indexes, etc.
+// Returns Drift[] — missing tables, extra columns, type mismatches, missing indexes, etc.
 ```
 
 ### Generate a migration
 
 ```typescript
 import { generateMigration } from '@lyku/lockstep-pg';
-import { tables } from '@lyku/pg-config';
 
 const { safe, destructive, driftCount } = await generateMigration(process.env.PG_CONNECTION_STRING, { tables });
 // safe: SQL string wrapped in BEGIN/COMMIT (additive changes)
@@ -54,10 +66,9 @@ await client.end();
 ### Diff and generate SQL
 
 ```typescript
-import { diffDatabase, categorizeOperations } from '@lyku/lockstep-pg';
-import { generateMigrationSql } from '@lyku/lockstep-pg';
+import { diffDatabase, categorizeOperations, generateMigrationSql } from '@lyku/lockstep-pg';
 
-const ops = diffDatabase(dbTables, codeTables);
+const ops = diffDatabase(introspectedTables, codeDefinedTables);
 const { safe, destructive } = categorizeOperations(ops);
 const sql = generateMigrationSql(ops);
 ```
@@ -66,12 +77,75 @@ const sql = generateMigrationSql(ops);
 
 ```typescript
 import { generateSeedSql } from '@lyku/lockstep-pg';
-import { tables } from '@lyku/pg-config';
 
 const sql = generateSeedSql({ tables });
 // INSERT ... ON CONFLICT DO NOTHING for each table's `docs` array
 ```
 
+## Where it fits
+
+<!-- Generated from libs/lockstep-core/diagrams/pipeline.mmd — do not edit manually -->
+
+```mermaid
+graph TD
+    input-tables["Table Schemas<br/><small>PostgresRecordModel</small>"]
+    input-api["API Definitions<br/><small>TsonHandlerModel</small>"]
+
+    core-jsonmodels["generateJsonModels"]
+    core-dbtypes["generateDbTypes"]
+    core-apitypes["generateApiTypes"]
+    core-validators["buildValidator"]
+
+    handles-gen["generateHandles"]
+
+    client-gen["generateTsClient"]
+
+    pg-drift["detectDrift"]
+    pg-migrate["generateMigration"]
+
+    output-jsonschemas["JSON Schemas +<br/>TypeScript Types"]
+    output-kysely["Kysely Database<br/>Interface"]
+    output-reqres["Request / Response<br/>TypeScript Types"]
+    output-handlers["Handler Factories<br/>+ Validators"]
+    output-client["Type-safe<br/>HTTP Client"]
+    output-sql["SQL Migrations"]
+
+    input-tables --> core-jsonmodels
+    core-jsonmodels --> output-jsonschemas
+    output-jsonschemas --> core-dbtypes
+    core-dbtypes --> output-kysely
+
+    input-api --> core-apitypes
+    core-apitypes --> output-reqres
+    input-api --> core-validators
+
+    output-reqres --> handles-gen
+    input-api --> handles-gen
+    core-validators -.-> handles-gen
+    handles-gen --> output-handlers
+
+    output-reqres --> client-gen
+    input-api --> client-gen
+    client-gen --> output-client
+
+    input-tables --> pg-drift
+    pg-drift --> pg-migrate
+    pg-migrate --> output-sql
+
+    classDef highlight fill:#4f46e5,stroke:#3730a3,color:#fff,stroke-width:2px
+    classDef dimmed fill:#f1f5f9,stroke:#cbd5e1,color:#94a3b8,stroke-width:1px
+    classDef inputNode fill:#fef3c7,stroke:#f59e0b,color:#92400e,stroke-width:1px
+    classDef outputNode fill:#d1fae5,stroke:#10b981,color:#065f46,stroke-width:1px
+    classDef ownedOutput fill:#a5b4fc,stroke:#4f46e5,color:#1e1b4b,stroke-width:2px
+    classDef ownedInput fill:#fde68a,stroke:#4f46e5,color:#1e1b4b,stroke-width:2px
+    class pg-drift,pg-migrate highlight
+    class core-jsonmodels,core-dbtypes,core-apitypes,core-validators,handles-gen,client-gen dimmed
+    class input-api inputNode
+    class output-jsonschemas,output-kysely,output-reqres,output-handlers,output-client outputNode
+    class input-tables ownedInput
+    class output-sql ownedOutput
+```
+
 ## Drift types
 
 | Type                        | Description                                      |

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@lyku/lockstep-pg",
-	"version": "0.1.1",
+	"version": "1.3.1",
 	"description": "Schema-driven PostgreSQL migration toolkit: drift detection, introspection, and SQL generation for @lyku/lockstep-core models",
 	"main": "./src/index.js",
 	"types": "./src/index.d.ts",