@pintahub/database-schemas 5.8.0 → 6.0.1

package/docs/migration.md

@@ -0,0 +1,242 @@
+# Migration — v5 → v6 (TypeScript rewrite)
+
+`@pintahub/database-schemas@6.0.0` is a TypeScript rewrite. Runtime behaviour for existing CommonJS services is **backward compatible** — the public entry still resolves to an absolute path string to a schemas directory. The breaking changes are mostly around peer-dep wiring and the new typed `/types` subpath.
+
+This guide covers the two upgrade paths:
+
+1. **JS service staying on `schemis`** — minimal change, mostly `package.json`.
+2. **JS service moving to TypeScript + `schemas-ts`** — bigger, but unblocks typed models.
+
+If you are starting a new service, skip this file and go straight to [usage-ts.md](./usage-ts.md).
+
+---
+
+## What changed in v6
+
+| Area                 | v5 (5.x)                                       | v6 (6.x)                                                       |
+| -------------------- | ---------------------------------------------- | -------------------------------------------------------------- |
+| Source language      | JavaScript (CJS)                               | TypeScript, compiled to CJS in `dist/`                         |
+| Entry                | `index.js` → `path.join(__dirname, 'schemas')` | `dist/index.js` → `path.join(__dirname, 'schemas')`            |
+| Schema files         | `schemas/*.js` (`module.exports = Schema`)     | `dist/schemas/*.js` (`module.exports = Schema` via `export =`) |
+| Types                | none                                           | `@pintahub/database-schemas/types` re-exports `IXxx`           |
+| `peerDependencies`   | `mongoose`, `schemis` (both required)          | `mongoose` (required); `schemis` / `schemas-ts` (optional)     |
+| Files in npm tarball | `index.js`, `schemas/`                         | `dist/` only                                                   |
+
+**No schema field, index, or collection name changed.** A v5 consumer that bumps to v6 sees the same MongoDB behaviour. The breaking part is `peerDependencies` — `schemis` is no longer pulled in automatically, you must install it (or `schemas-ts`) explicitly.
+
+---
+
+## Path 1 — Stay on JS, upgrade in place
+
+For services that currently look like this:
+
+```js
+// src/connections/database.js  (v5)
+const {createConnection, createStore} = require('schemis')
+const schemas = require('@pintahub/database-schemas')
+
+const connection = createConnection(process.env.MONGODB_URI)
+const store = createStore({connection, schemas})
+
+module.exports = store
+```
+
+### Step 1 — bump deps
+
+```bash
+yarn add @pintahub/database-schemas@^6.0.0 schemis@^2.0.2
+```
+
+In v5, `schemis` was a peer of this package and you might have been getting it transitively. In v6 it is **optional**, so add it to your own `dependencies` explicitly.
+
+### Step 2 — confirm no code change
+
+The entry `require('@pintahub/database-schemas')` still returns an absolute path string. `schemis.createStore` still walks that directory. No source-code edits required.
+
+### Step 3 — smoke test
+
+```bash
+node -e "const s = require('@pintahub/database-schemas'); console.log(s)"
+# /…/node_modules/@pintahub/database-schemas/dist/schemas
+```
+
+```bash
+node -e "
+const {createStore, createConnection} = require('schemis');
+const schemas = require('@pintahub/database-schemas');
+const conn = createConnection('mongodb://localhost:27017/test');
+const store = createStore({connection: conn, schemas});
+console.log(Object.keys(store.getModel('Store').schema.paths).slice(0, 5));
+conn.close();
+"
+```
+
+Expected: five field names from the `Store` schema. If you see `Cannot find module 'schemis'`, finish Step 1.
+
+### Step 4 — deploy
+
+Standard CI/CD. Nothing collection-shaped changed, so there is no data migration.
+
+---
+
+## Path 2 — Migrate a service from JS+`schemis` to TS+`schemas-ts`
+
+This is a per-service decision. Do it when the service is being touched substantially anyway — don't migrate for its own sake.
+
+### Step 0 — pre-flight
+
+- Node version ≥ 20.11.0 (`schemas-ts` requires it).
+- The service has no remaining CJS-only deps that block ESM (rare; check `package.json` for `"type": "module"` viability).
+
+### Step 1 — set up TypeScript
+
+`package.json`:
+
+```json
+{
+    "type": "module",
+    "scripts": {
+        "build": "tsc",
+        "dev": "tsx watch src/index.ts",
+        "start": "node dist/index.js"
+    }
+}
+```
+
+`tsconfig.json`:
+
+```json
+{
+    "compilerOptions": {
+        "target": "ES2022",
+        "module": "NodeNext",
+        "moduleResolution": "NodeNext",
+        "esModuleInterop": true,
+        "skipLibCheck": true,
+        "strict": true,
+        "outDir": "./dist",
+        "rootDir": "./src"
+    },
+    "include": ["src/**/*"]
+}
+```
+
+### Step 2 — swap the resolver
+
+```bash
+yarn remove schemis
+yarn add @pintahub/database-schemas@^6.0.0 schemas-ts@^1.0.2
+yarn add -D @types/node typescript tsx
+```
+
+### Step 3 — rewrite the connection module
+
+Before (`src/connections/database.js`):
+
+```js
+const {createConnection, createStore} = require('schemis')
+const schemas = require('@pintahub/database-schemas')
+
+const connection = createConnection(process.env.MONGODB_URI)
+const store = createStore({connection, schemas})
+
+module.exports = store
+```
+
+After (`src/connections/database.ts`):
+
+```ts
+import {createConnection, createStore} from 'schemas-ts'
+import schemasPath from '@pintahub/database-schemas'
+
+const connection = createConnection(process.env.MONGODB_URI!)
+const store = createStore({connection, schemas: schemasPath})
+
+export default store
+```
+
+The API surface (`getModel`, `getConnection`) is identical between `schemis` and `schemas-ts`, so call sites that only use those two methods do not need to change.
+
+### Step 4 — type the call sites incrementally
+
+You can migrate file by file. Start with the hottest collections.
+
+Before:
+
+```js
+const Product = store.getModel('Product')
+const doc = await Product.findOne({_id: id}).lean()
+// doc is `any`
+```
+
+After:
+
+```ts
+import type {IProduct} from '@pintahub/database-schemas/types'
+
+const Product = store.getModel<IProduct>('Product')
+const doc = await Product.findOne({_id: id}).lean()
+// doc is IProduct | null (well, the lean variant — see usage-ts.md)
+```
+
+Untyped `getModel('Product')` still works during the migration; the generic is opt-in.
+
+### Step 5 — extension-explicit imports
+
+ESM under `NodeNext` requires `.js` extensions on relative imports — even for files that are `.ts` on disk (TypeScript rewrites the import on the way out, the runtime sees `.js`):
+
+```ts
+// in src/foo.ts
+import store from './connections/database.js'  // .js, not .ts
+```
+
+The compiled output lands at `dist/connections/database.js`, so this is correct at runtime.
+
+### Step 6 — verify
+
+```bash
+yarn build
+node --input-type=module -e "
+  import('./dist/connections/database.js').then(async ({default: store}) => {
+    const Store = store.getModel('Store')
+    console.log('paths:', Object.keys(Store.schema.paths).length)
+    await store.getConnection().close()
+  })
+"
+```
+
+Then run the actual service against a staging Mongo and exercise a couple of read paths.
+
+### Step 7 — clean up
+
+- Remove the now-unused `schemis` line from `package.json` (Step 2 already did this with `yarn remove`).
+- Update CI: build step is now `yarn build`, runtime is `node dist/index.js`.
+- Re-enable `"strict": true` if you suppressed it during the bulk rewrite.
+
+---
+
+## Mapping cheatsheet
+
+| Concept                                 | v5 (`schemis`)                                 | v6 (`schemas-ts`)                                                |
+| --------------------------------------- | ---------------------------------------------- | ---------------------------------------------------------------- |
+| Import the schemas path                 | `const s = require('@pintahub/database-schemas')` | `import s from '@pintahub/database-schemas'`                     |
+| Import a typed interface                | n/a (no types in v5)                           | `import type {IOrder} from '@pintahub/database-schemas/types'`   |
+| Create connection                       | `require('schemis').createConnection(uri)`     | `import {createConnection} from 'schemas-ts'`                    |
+| Create store                            | `createStore({connection, schemas})`           | `createStore({connection, schemas: schemasPath})`                |
+| Get a model                             | `store.getModel('Order')`                      | `store.getModel<IOrder>('Order')`                                |
+| Custom collection name                  | `store.getModel('Order', 'archived_orders')`   | `store.getModel<IOrder>('Order', 'archived_orders')`             |
+| Populate (always explicit `model`)      | `.populate({path, model, select})`             | `.populate({path, model, select})`                               |
+
+## FAQ
+
+**Can two services share one Mongo connection with different resolvers?**
+Yes. The package only exposes a path string; each service builds its own store. Nothing about the Mongo wire protocol cares which resolver wrapped it.
+
+**Can a v5 service and a v6 service write the same collection at the same time?**
+Yes. v6 did not change any field name, type, index, or collection name. The only thing that changed is how the schemas are *loaded* in Node.
+
+**My CI pulled in `schemis@1.x` after upgrading.**
+v6 marks `schemis` as optional, so your lockfile drops it if you don't list it explicitly. Add `"schemis": "^2.0.2"` (or `"schemas-ts": "^1.0.2"`) to your own `dependencies`.
+
+**I see `dist/schemas/Order.js` but the package source is `src/schemas/Order.ts`.**
+Correct — only `dist/` ships in the npm tarball (`"files": ["dist"]` in `package.json`). When you edit a schema, the build step (`yarn build`) is what produces the file your consumers see.

package/docs/usage-js.md

@@ -0,0 +1,114 @@
+# Usage — CommonJS (JS) services
+
+For services written in plain JavaScript (CommonJS) — e.g. `admin-api`, `admin-worker`, legacy workers. Use the [`schemis`](https://www.npmjs.com/package/schemis) resolver.
+
+## Install
+
+```bash
+yarn add @pintahub/database-schemas schemis mongoose
+```
+
+Peer-dep matrix:
+
+| Package                         | Version   | Notes                       |
+| ------------------------------- | --------- | --------------------------- |
+| `mongoose`                      | `^9.1.3`  | required peer               |
+| `schemis`                       | `^2.0.2`  | CJS resolver                |
+| `@pintahub/database-schemas`    | `^6.0.0`  | this package                |
+
+`schemas-ts` is **not** needed for JS services.
+
+## Bootstrap the store
+
+```js
+// src/connections/database.js
+const {createConnection, createStore} = require('schemis')
+const schemasPath = require('@pintahub/database-schemas')
+
+const uri = process.env.MONGODB_URI || 'mongodb://localhost:27017/dev'
+const connection = createConnection(uri)
+
+const store = createStore({connection, schemas: schemasPath})
+
+module.exports = store
+```
+
+`require('@pintahub/database-schemas')` resolves to an **absolute path string** pointing at `dist/schemas/`. `schemis.createStore` walks that directory and lazy-loads each schema on first `getModel` call.
+
+## Use models
+
+```js
+const store = require('./connections/database')
+
+const Product = store.getModel('Product')
+
+const doc = await Product
+    .findOne({_id: productId, store: storeId})
+    .lean()
+
+await Product.updateOne(
+    {_id: productId},
+    {$set: {status: 'active', updated_at: new Date()}}
+)
+```
+
+Always filter by `store` for tenant-scoped collections.
+
+## Custom collection name
+
+Pass a second argument to override the default collection name (Mongoose pluralisation):
+
+```js
+const ArchivedOrder = store.getModel('Order', 'archived_orders')
+```
+
+## Populate with explicit `model`
+
+`schemis` does not register cross-schema refs globally, so always pass the populated model explicitly:
+
+```js
+const TransferJob = store.getModel('TransferJob')
+const Product = store.getModel('Product')
+const Store = store.getModel('Store')
+
+const jobs = await TransferJob
+    .find({store: storeId})
+    .populate({path: 'product', model: Product, select: {title: 1, code: 1}})
+    .populate({path: 'destination_store', model: Store, select: {name: 1}})
+    .lean()
+```
+
+## Connection lifecycle
+
+`createConnection(uri)` returns a Mongoose `Connection` immediately and connects in the background. Wait for it before serving traffic:
+
+```js
+const store = require('./connections/database')
+
+store.getConnection().once('open', () => {
+    console.log('mongo connected')
+    // start http server here
+})
+
+store.getConnection().on('error', err => {
+    console.error('mongo error', err)
+})
+```
+
+For graceful shutdown:
+
+```js
+process.on('SIGTERM', async () => {
+    await store.getConnection().close()
+    process.exit(0)
+})
+```
+
+## Common pitfalls
+
+- **`Cannot find module '@pintahub/database-schemas'`** — make sure the package is added to `dependencies`, not `devDependencies`.
+- **`Schema hasn't been registered for model "X"`** — you called `mongoose.model('X')` directly instead of `store.getModel('X')`. Always go through the store.
+- **Stale schema after publish** — clear `node_modules/@pintahub/database-schemas` and re-install; the package is pinned by lockfile, not auto-updated.
+- **Two stores for the same connection** — `getModel` caches per store; instantiate one `createStore` per connection and reuse it.
+
+See [Contributing](./contributing.md) for adding/changing schemas and bumping the version.

package/docs/usage-ts.md

@@ -0,0 +1,141 @@
+# Usage — TypeScript / ESM services
+
+For services written in TypeScript with ESM output — e.g. `shopify-gateway` and any new service. Use the [`schemas-ts`](https://www.npmjs.com/package/schemas-ts) resolver.
+
+## Install
+
+```bash
+yarn add @pintahub/database-schemas schemas-ts mongoose
+yarn add -D @types/node typescript
+```
+
+Peer-dep matrix:
+
+| Package                         | Version   | Notes                                |
+| ------------------------------- | --------- | ------------------------------------ |
+| `mongoose`                      | `^9.1.3`  | required peer                        |
+| `schemas-ts`                    | `^1.0.2`  | ESM resolver (Node ≥ 20.11)          |
+| `@pintahub/database-schemas`    | `^6.0.0`  | this package                         |
+
+`schemis` is **not** needed for TS services.
+
+## `tsconfig.json` baseline
+
+```json
+{
+    "compilerOptions": {
+        "target": "ES2022",
+        "module": "NodeNext",
+        "moduleResolution": "NodeNext",
+        "esModuleInterop": true,
+        "skipLibCheck": true,
+        "strict": true,
+        "outDir": "./dist",
+        "rootDir": "./src"
+    },
+    "include": ["src/**/*"]
+}
+```
+
+`module: "NodeNext"` is required for `schemas-ts` (it ships ESM-only) and is what the package's `import.meta.dirname` example relies on.
+
+## Bootstrap the store
+
+```ts
+// src/connections/database.ts
+import {createConnection, createStore} from 'schemas-ts'
+import schemasPath from '@pintahub/database-schemas'
+
+const uri = process.env.MONGODB_URI || 'mongodb://localhost:27017/dev'
+const connection = createConnection(uri)
+
+const store = createStore({connection, schemas: schemasPath})
+
+export default store
+```
+
+The package's default export is an **absolute string** pointing at `dist/schemas/`. `schemas-ts` loads each schema via dynamic `import()` and supports both `export default Schema` and `module.exports = Schema` (this package uses the latter via TypeScript's `export = Schema`).
+
+## Typed models
+
+`store.getModel<T>(name)` returns `Model<T>`. Use the interface re-exports from the `/types` subpath:
+
+```ts
+import store from './connections/database.js'
+import type {IStore, IProduct, IOrder} from '@pintahub/database-schemas/types'
+import type {Model} from 'mongoose'
+
+const Store: Model<IStore> = store.getModel<IStore>('Store')
+const Product: Model<IProduct> = store.getModel<IProduct>('Product')
+
+const found = await Store.findOne({subdomain: 'foo'}).lean()
+//    ^? IStore | null
+
+const product = await Product.findOne(
+    {_id: productId, store: storeId},
+).lean()
+```
+
+Every schema in `src/schemas/` has a matching interface in `src/interfaces/`, re-exported through `@pintahub/database-schemas/types`. The interface name is the file name prefixed with `I` — e.g. `Order.ts` → `IOrder`.
+
+> **Note** — the runtime export at `@pintahub/database-schemas/types` is empty (`export type` is erased by TypeScript). The subpath exists purely for type imports. Always use `import type {...}` to keep it tree-shake-safe.
+
+## Populate with explicit `model`
+
+`schemas-ts` does not register cross-schema refs globally either, so pass the populated model explicitly:
+
+```ts
+import type {ITransferJob, IProduct, IStore} from '@pintahub/database-schemas/types'
+
+const TransferJob = store.getModel<ITransferJob>('TransferJob')
+const Product = store.getModel<IProduct>('Product')
+const Store = store.getModel<IStore>('Store')
+
+const jobs = await TransferJob
+    .find({store: storeId})
+    .populate({path: 'product', model: Product, select: {title: 1, code: 1}})
+    .populate({path: 'destination_store', model: Store, select: {name: 1}})
+    .lean()
+```
+
+## ObjectId fields in the interfaces
+
+Foreign-key fields in `IXxx` interfaces are typed as `Types.ObjectId`:
+
+```ts
+import type {Types} from 'mongoose'
+import type {IOrder} from '@pintahub/database-schemas/types'
+
+const order: IOrder = await Order.findOne({...}).lean() as IOrder
+order.store         // Types.ObjectId
+order.store.toString()
+```
+
+When you `.populate()` a ref, cast the result to the populated shape — the base interface intentionally keeps the un-populated ObjectId type for accuracy.
+
+## Connection lifecycle
+
+```ts
+import store from './connections/database.js'
+
+const conn = store.getConnection()
+
+conn.once('open', () => {
+    // safe to start serving traffic
+})
+
+process.on('SIGTERM', async () => {
+    await conn.close()
+    process.exit(0)
+})
+```
+
+## Common pitfalls
+
+- **`ERR_REQUIRE_ESM`** — you set `module: "commonjs"` in `tsconfig.json` but `schemas-ts` is ESM-only. Switch to `NodeNext`, or stay on JS and use `schemis` instead (see [usage-js.md](./usage-js.md)).
+- **`Cannot find module '@pintahub/database-schemas/types'`** — your `moduleResolution` is `node` (legacy). Use `NodeNext` or `bundler` so subpath exports resolve.
+- **Type for a field is `any`** — that field is missing from the interface in `src/interfaces/`. Open a PR adding it; both the schema file and interface must move together.
+- **`Model<T>.findOne(...).lean()` returns `T & Document`** — that's normal Mongoose typing; cast or use `.lean<T>()` if you need a plain shape.
+- **Hot reload re-creates the connection on every change** — wrap the bootstrap in a module-level cache or use the dev-server's HMR hooks; `createConnection` is not idempotent.
+
+See [Contributing](./contributing.md) for adding/changing schemas and interfaces.

package/package.json

@@ -1,10 +1,27 @@
 {
   "name": "@pintahub/database-schemas",
-  "version": "5.8.0",
-  "description": "",
-  "main": "index.js",
+  "version": "6.0.1",
+  "description": "Pintahub MongoDB schemas (TypeScript). Compatible with both schemis (CJS) and schemas-ts (ESM) resolvers.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "docs"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./types": {
+      "types": "./dist/types.d.ts",
+      "default": "./dist/types.js"
+    }
+  },
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "prepublishOnly": "tsc"
   },
   "repository": {
     "type": "git",
@@ -15,10 +32,22 @@
   "license": "ISC",
   "homepage": "https://gitlab.com/pintahub/packages/database-schemas#readme",
   "peerDependencies": {
-    "mongoose": "^9.1.3",
-    "schemis": "^2.0.2"
+    "mongoose": "^9.1.3"
+  },
+  "peerDependenciesMeta": {
+    "schemis": {
+      "optional": true
+    },
+    "schemas-ts": {
+      "optional": true
+    }
   },
   "devDependencies": {
-    "mongoose": "^9.1.3"
+    "@types/node": "^20.0.0",
+    "mongoose": "^9.1.3",
+    "schemas-ts": "^1.1.1",
+    "schemis": "^2.0.2",
+    "tsx": "^4.22.3",
+    "typescript": "^5.4.0"
   }
 }

package/CLAUDE.md

@@ -1,34 +0,0 @@
-# CLAUDE.md — @pintahub/database-schemas
-
-Shared Mongoose schema package for PintaHub microservices. See [README.md](./README.md) for package overview, install, usage examples, full schema catalog, and conventions.
-
-This file contains only the rules Claude needs to edit safely. Do not duplicate README content here.
-
-## Editing rules
-
-- **CommonJS only.** This codebase uses `require` / `module.exports`. Do **not** convert to ES modules — overrides the global "prefer ES modules" preference.
-- **Export Schema, not Model.** Each file in `schemas/` exports a `new Schema({...})` instance. Consumers register models themselves through `schemis`.
-- **JSDoc every field.** Use `/** ... */` immediately above each field — this is the documentation source of truth (no separate docs site).
-- **Embedded sub-documents** declared in `schemas/types/`, `schemas/products/`, or co-located in `schemas/` (e.g. `MoneyObject`) must be created with `{_id: false}`.
-- **Multi-tenancy.** Domain schemas keep an indexed `store` ObjectId ref. When adding a new schema with tenant data, include `store: {type: Schema.Types.ObjectId, ref: 'Store', index: true}`.
-- **Timestamps.** Use explicit `created_at` / `updated_at` Date fields. Do **not** add Mongoose's `timestamps: true` option — it breaks consistency with the rest of the codebase.
-- **Indexes.**
-  - Default to `index: true` on the field for single-field indexes.
-  - Use `Schema.index({...})` at the bottom of the file for compound or text indexes.
-  - **Do not add a B-tree index for fields whose only purpose is Atlas Search** — Atlas Search uses its own Lucene index, and a redundant B-tree wastes write throughput.
-- **No schema-level pre/post hooks** unless explicitly requested. Compute logic happens at the consumer write-path so behavior is visible to service authors.
-- **Version bump on every schema change.** See README "Versioning". Update `package.json` in the same commit:
-  - new field / new schema / new index → minor
-  - rename / remove / type change → major
-  - JSDoc-only → patch
-
-## Project context
-
-- **Atlas Search migration in progress** for `storefront-api` product search (replacing the legacy `$text` index on Product). The legacy text index stays in place until the migration is complete.
-- **`Product.display_title`** (added 2026-04-17) is the precomputed `alternative_title || title` value used by Atlas Search and frontend display. Consumer services set it at write time — do not add a schema hook for it.
-
-## Common tasks
-
-- **Add a field to an existing schema:** edit the schema file, add JSDoc + field def, bump `package.json` minor, commit.
-- **Add a new schema:** create `schemas/<Name>.js` exporting `new Schema({...})`, follow conventions above, bump minor.
-- **Add an index:** prefer `index: true` on the field; use `Schema.index({...})` for compound/text indexes; never duplicate Atlas Search coverage.

package/index.js

@@ -1,3 +0,0 @@
-const path = require('path')
-
-module.exports = path.join(__dirname, 'schemas')

package/schemas/types/FooterSetting.js

@@ -1,15 +0,0 @@
-const {Schema} = require('mongoose')
-
-
-/** Embedded store footer settings */
-const FooterSetting = new Schema({
-    _id: false,
-
-    /** Footer display content */
-    text: {
-        type: String,
-        trim: true,
-    }
-})
-
-module.exports = FooterSetting

package/schemas/types/GoogleAnalytics.js

@@ -1,15 +0,0 @@
-const {Schema} = require('mongoose')
-
-
-/** Embedded Google Analytics settings */
-const GoogleAnalytics = new Schema({
-    _id: false,
-
-    /** GA4 Measurement ID, e.g. 'G-XXXXXXXXXX' */
-    measurement_id: {
-        type: String,
-        trim: true,
-    },
-})
-
-module.exports = GoogleAnalytics

package/schemas/types/TopBarSettings.js

@@ -1,15 +0,0 @@
-const {Schema} = require('mongoose')
-
-
-/** Embedded top bar announcement settings */
-const TopBarSettings = new Schema({
-    _id: false,
-
-    /** Announcement display text */
-    content: {
-        type: String,
-        trim: true,
-    },
-})
-
-module.exports = TopBarSettings