@stardeck-customer-apps/data-store-sdk 0.3.0 → 0.3.2

package/SKILL.md

@@ -228,6 +228,36 @@ the schema snapshot is what `@stardeck-customer-apps/testing` applies to its
 in-process Postgres, so a stale snapshot means tests run against the wrong
 schema.
 
+> **Never hand-edit a generated file.** `data-store-types.ts` is a write-only
+> output: it's overwritten in full on every regeneration and contains only the
+> raw table interfaces plus the `DB` type. Any type you append to it is silently
+> wiped the next time the schema changes and you re-run `generate-types`.
+
+App-level / derived types — serialized shapes (`Date` → `string` for API
+responses), typed `jsonb` columns, computed/virtual fields, composite view
+models — belong in a **separate hand-written file** that imports from the
+generated one. This keeps regeneration safe and your types permanent:
+
+```typescript
+// src/lib/order-types.ts  (hand-written — survives every regeneration)
+import type { Selectable } from "kysely";
+import type { DB } from "@/generated/data-store-types";
+
+type OrderRow = Selectable<DB["orders"]>;
+
+// API-serialized shape: Dates become strings, jsonb gets a real type,
+// and we add a computed field the table doesn't store.
+export type Order = Omit<OrderRow, "created_at" | "metadata"> & {
+  created_at: string;
+  metadata: { source: string; tags: string[] };
+  is_overdue: boolean;
+};
+```
+
+If you find hand-written types already living inside a generated file, move them
+into a sibling file like this and update the imports across the codebase rather
+than perpetuating the append-and-restore cycle.
+
 ### Initialize
 
 ```typescript
@@ -324,3 +354,4 @@ try {
 - **Tables auto-generate** `id` (UUID), `created_at`, and `updated_at` columns. Don't include these in create table definitions.
 - **Column deletes are soft-deletes.** The column is renamed to `_deleted_{name}_{timestamp}` and can be restored.
 - **Type changes are restricted** to safe widening conversions (e.g., integer → bigint, boolean → text).
+- **Generated column types: `bigint`/`numeric`/`decimal` map to `string`, not `number`.** `node-postgres` returns these as strings to avoid silent JS precision loss past `Number.MAX_SAFE_INTEGER`, so the generated types are `string` by design (`integer`/`smallint`/`real`/`double precision` stay `number`). `jsonb`/`json` come through as `unknown`. Cast at the boundary (`Number(row.size_bytes)`) or give the column a real type in your derived app type — don't assume `number`.

package/dist/cli/generate-types.js

@@ -339,8 +339,12 @@ async function introspectSchema(connectionString) {
 }
 function generateTypeScript(tables) {
   const lines = [
-    "// Auto-generated by @stardeck-customer-apps/data-store-sdk",
-    "// Do not edit manually \u2014 regenerate with: npx stardeck-data-store generate-types",
+    "// AUTO-GENERATED by @stardeck-customer-apps/data-store-sdk \u2014 DO NOT EDIT.",
+    "// This file is overwritten in full on every run of:",
+    "//   npx stardeck-data-store generate-types",
+    "// Anything you add here (hand-written or derived types) WILL BE LOST on the next",
+    "// regeneration. Put those in a separate file that imports from this one, e.g.",
+    "// src/lib/<domain>-types.ts importing the table types or DB from this file.",
     "",
     'import type { Generated } from "kysely";',
     ""

package/dist/cli/generate-types.mjs

@@ -316,8 +316,12 @@ async function introspectSchema(connectionString) {
 }
 function generateTypeScript(tables) {
   const lines = [
-    "// Auto-generated by @stardeck-customer-apps/data-store-sdk",
-    "// Do not edit manually \u2014 regenerate with: npx stardeck-data-store generate-types",
+    "// AUTO-GENERATED by @stardeck-customer-apps/data-store-sdk \u2014 DO NOT EDIT.",
+    "// This file is overwritten in full on every run of:",
+    "//   npx stardeck-data-store generate-types",
+    "// Anything you add here (hand-written or derived types) WILL BE LOST on the next",
+    "// regeneration. Put those in a separate file that imports from this one, e.g.",
+    "// src/lib/<domain>-types.ts importing the table types or DB from this file.",
     "",
     'import type { Generated } from "kysely";',
     ""

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stardeck-customer-apps/data-store-sdk",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "SDK for accessing Stardeck data stores from deployed projects",
   "main": "dist/index.js",
   "module": "dist/index.mjs",