postgresdk 0.18.30 → 0.19.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 postgresdk contributors
+Copyright (c) 2026 postgresdk contributors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -55,6 +55,7 @@ const filtered = await sdk.users.list({
 - ✅ **Runtime Validation** - Zod schemas for request/response validation
 - 🔗 **Smart Relationships** - Automatic handling of 1:N and M:N relationships with eager loading
 - 🔍 **Vector Search** - Built-in pgvector support for similarity search with multiple distance metrics
+- ⚡ **Atomic Transactions** - Execute multiple operations atomically via `sdk.$transaction([...])`
 - 🔐 **Built-in Auth** - API key and JWT authentication
 - 🎯 **Zero Config** - Works out of the box with sensible defaults
 - 📦 **Lightweight** - Minimal dependencies, optimized bundle size
@@ -124,7 +125,7 @@ const sdk = new SDK({ baseUrl: "http://localhost:3000" });
 const user = await sdk.users.create({ name: "Alice", email: "alice@example.com" });
 const users = await sdk.users.list({ include: { posts: true } });
 await sdk.users.update(user.id, { name: "Alice Smith" });
-await sdk.users.delete(user.id);
+await sdk.users.hardDelete(user.id);
 ```
 
 ---
@@ -145,10 +146,12 @@ export default {
   // Optional (with defaults)
   schema: "public",                    // Database schema to introspect
   outDir: "./api",                     // Output directory (or { client: "./sdk", server: "./api" })
-  softDeleteColumn: null,              // Column name for soft deletes (e.g., "deleted_at")
-  softDeleteColumnOverrides: {         // Per-table overrides (null = disable soft delete for that table)
-    // captures: "hidden_at",          //   different column name for a specific table
-    // audit_logs: null,               //   hard deletes only for this table
+  delete: {                            // Soft/hard delete configuration (optional)
+    softDeleteColumn: "deleted_at",    //   Column name for soft deletes (omit = hard deletes only)
+    exposeHardDelete: true,            //   Also expose hardDelete() — set false to disable (default: true)
+    softDeleteColumnOverrides: {       //   Per-table overrides
+      // audit_logs: null,             //     hard deletes only for this table
+    },
   },
   numericMode: "auto",                 // "auto" | "number" | "string" - How to type numeric columns
   includeMethodsDepth: 2,              // Max depth for nested includes
@@ -567,8 +570,50 @@ const users = result.data;  // Array of users
 // Update
 const updated = await sdk.users.update(123, { name: "Robert" });
 
+// Upsert — insert if no conflict, update otherwise (Prisma-style)
+const upserted = await sdk.users.upsert({
+  where:  { email: "alice@example.com" },       // conflict target (must be a unique constraint)
+  create: { email: "alice@example.com", name: "Alice" },
+  update: { name: "Alice Updated" },
+});
+
 // Delete
-const deleted = await sdk.users.delete(123);
+const deleted = await sdk.users.hardDelete(123);     // permanent deletion
+// await sdk.users.softDelete(123);                  // soft-delete (when softDeleteColumn is configured)
+```
+
+#### Atomic Transactions
+
+Execute multiple operations in a single PostgreSQL transaction — all succeed or all roll back:
+
+```typescript
+const [order, updatedUser] = await sdk.$transaction([
+  sdk.orders.$create({ user_id: user.id, total: 99 }),
+  sdk.users.$update(user.id, { last_order_at: new Date().toISOString() }),
+]);
+// TypeScript infers: [SelectOrders, SelectUsers | null]
+```
+
+- `$create`, `$update`, `$delete`, `$upsert` are **lazy builders** — nothing executes until `$transaction` is called
+- All ops are Zod-validated **before** `BEGIN` is issued (fail-fast, no partial state)
+- On any failure the transaction rolls back; an error is thrown with a `.failedAt` index
+
+```typescript
+try {
+  const results = await sdk.$transaction([
+    sdk.inventory.$update(itemId, { stock: newStock }),
+    sdk.orders.$create({ item_id: itemId, qty: 1 }),
+    sdk.audit_log.$create({ action: "purchase", item_id: itemId }),
+    // $upsert also works inside transactions:
+    sdk.users.$upsert({
+      where:  { email: "alice@example.com" },
+      create: { email: "alice@example.com", name: "Alice" },
+      update: { name: "Alice Updated" },
+    }),
+  ]);
+} catch (err: any) {
+  console.error(`Failed at op ${err.failedAt}:`, err.message);
+}
 ```
 
 #### Relationships & Eager Loading
@@ -744,7 +789,13 @@ const nested = await sdk.users.list({
   }
 });
 
-// Soft deletes — when softDeleteColumn is configured, deleted records are hidden by default.
+// Soft deletes — when `delete.softDeleteColumn` is configured in postgresdk.config.ts,
+// the SDK exposes softDelete() and hardDelete() instead of a single delete():
+//
+//   softDelete(id)   → sets the soft-delete column (e.g. deleted_at = NOW())
+//   hardDelete(id)   → permanent DELETE (available unless exposeHardDelete: false)
+//
+// Soft-deleted rows are hidden from list/getByPk by default.
 // Pass includeSoftDeleted: true to opt into seeing them (e.g., for admin/recovery UIs).
 const allUsers = await sdk.users.list({ includeSoftDeleted: true });
 const deletedUser = await sdk.users.getByPk("123", { includeSoftDeleted: true });
@@ -786,7 +837,7 @@ const updated = await sdk.users.update(
 );
 
 const fetched = await sdk.users.getByPk(userId, { select: ['id', 'name'] });
-const deleted = await sdk.users.delete(userId, { select: ['id', 'email'] });
+const deleted = await sdk.users.hardDelete(userId, { select: ['id', 'email'] });
 
 // Nested select/exclude in includes
 const withNestedSelect = await sdk.authors.list({

package/dist/cli-config-utils.d.ts

@@ -11,4 +11,5 @@ export declare function parseExistingConfig(configPath: string): {
     raw: string;
 };
 export declare function extractConfigFields(configContent: string): ConfigField[];
-export declare function generateMergedConfig(existingFields: ConfigField[], mergeStrategy: "keep-existing" | "use-defaults" | "interactive", userChoices?: Map<string, any> | undefined): string;
+export type MergeChoice = "keep" | "new";
+export declare function generateMergedConfig(existingFields: ConfigField[], mergeStrategy: "keep-existing" | "use-defaults" | "interactive", userChoices?: Map<string, MergeChoice> | undefined): string;