@pintahub/database-schemas 6.0.0 → 6.0.1

package/docs/contributing.md

@@ -0,0 +1,278 @@
+# Contributing — schemas, interfaces, and releases
+
+This is the editing guide for anyone adding fields, schemas, or indexes to `@pintahub/database-schemas`. Read [CLAUDE.md](../CLAUDE.md) for the short-form rules; this doc expands on the *why* and walks the common workflows.
+
+## Repo layout
+
+```
+src/
+├── index.ts                # public CJS entry — exports the path to dist/schemas
+├── types.ts                # public type re-exports — consumed via /types subpath
+├── interfaces/             # pure TypeScript types, no runtime
+│   ├── Order.ts            # export interface IOrder { … }
+│   ├── …
+│   ├── types/              # interfaces for embedded sub-schemas
+│   └── products/           # product-specific interface helpers
+└── schemas/                # Mongoose Schema runtime
+    ├── Order.ts            # export = new Schema({…})
+    ├── …
+    ├── types/              # embedded sub-schemas (BrandSettings, …)
+    └── products/           # product-specific embedded schemas
+
+dist/                       # compiled output (gitignored, but shipped to npm)
+scripts/
+├── convert.js              # one-off v5 → v6 converter, historical
+├── snapshot.js             # parity check against the legacy schemas/ folder
+└── smoke-schemas-ts.mts    # loads dist/ through schemas-ts to verify the bridge
+```
+
+## Editing rules (must-follow)
+
+These come from [CLAUDE.md](../CLAUDE.md). Repeated here so contributors see them in one place.
+
+- **CommonJS at runtime.** Each schema file uses `export = SchemaInstance`. TypeScript compiles this to `module.exports = SchemaInstance`, which is what both `schemis` (via `require`) and `schemas-ts` (via dynamic `import()` with `.default || .module.exports`) expect.
+- **Export Schema, not Model.** Never call `mongoose.model(...)` in this package. Consumers register models via their resolver.
+- **JSDoc every field.** A `/** ... */` block immediately above each field is the documentation source of truth. There is no separate docs site.
+- **Embedded sub-documents use `{_id: false}`.** Anything in `schemas/types/`, `schemas/products/`, or any inline embedded schema in `schemas/` must declare `_id: false`. Sub-docs are pure value objects; auto-generated `_id`s create churn on parent updates.
+- **Multi-tenant `store` ref.** Domain schemas keep an indexed `store: {type: Schema.Types.ObjectId, ref: 'Store', index: true}`. New tenant-scoped schemas must include it.
+- **Explicit timestamps.** Use `created_at` and `updated_at` as `Date` fields. **Do not** add Mongoose's `timestamps: true` option — historical writes in the codebase set these fields manually, and `timestamps: true` would silently overwrite them.
+- **No schema-level pre/post hooks** unless explicitly requested. Compute logic happens at the consumer write path so it's visible to service authors.
+
+## Index policy
+
+- Single-field index → put `index: true` on the field def.
+- Compound, text, partial, or TTL index → use `Schema.index({...}, {...})` at the **bottom** of the file.
+- Compound indexes should put the highest-selectivity field first (typically `store`).
+- **Do not add a B-tree index for fields whose only purpose is Atlas Search.** Atlas Search builds its own Lucene index; a duplicate B-tree just wastes write throughput.
+- Drop indexes that are superseded by a new compound index in the same PR. `git log` makes the intent clear.
+
+## Adding a field to an existing schema
+
+1. Open `src/schemas/<Name>.ts`. Add the field def with a `/** … */` block above it.
+2. Open `src/interfaces/<Name>.ts`. Add the matching field to the interface. Default to optional (`field?: T`) unless the field is required at insert time.
+3. If the field is a sub-document, reuse an existing embedded schema from `schemas/types/` or `schemas/products/` if one fits; otherwise add a new one (see below).
+4. Bump `package.json` — **minor** for any new field.
+5. Commit. The build runs in CI on tag publish, but locally you can run `yarn build` to sanity-check.
+
+Example diff:
+
+```ts
+// src/schemas/Store.ts
+/** Time the store was first set up (separate from created_at, which can be backdated for imports) */
+onboarded_at: {
+    type: Date,
+},
+```
+
+```ts
+// src/interfaces/Store.ts
+export interface IStore {
+    // …
+    onboarded_at?: Date
+}
+```
+
+## Adding a new schema
+
+1. Create `src/schemas/<Name>.ts`:
+
+   ```ts
+   import {Schema} from 'mongoose'
+
+   /** Top-of-file JSDoc describing the collection */
+   const MySchema = new Schema(<Record<string, any>>{
+       /** @ref Store */
+       store: {
+           type: Schema.Types.ObjectId,
+           ref: 'Store',
+           index: true,
+       },
+
+       /** Display name */
+       name: {
+           type: String,
+           trim: true,
+       },
+
+       /** Created timestamp — set by the service at write time */
+       created_at: {
+           type: Date,
+           default: Date.now,
+       },
+       updated_at: Date,
+   })
+
+   MySchema.index({store: 1, created_at: -1})
+
+   export = MySchema
+   ```
+
+   Notes:
+   - `<Record<string, any>>` on the schema definition silences Mongoose's strict shape-inference; the public type comes from the interface file.
+   - `export = MySchema` (not `export default`) — this compiles to `module.exports = MySchema`, which is what both resolvers expect.
+
+2. Create `src/interfaces/<Name>.ts`:
+
+   ```ts
+   import type {Types} from 'mongoose'
+
+   export interface IMy {
+       store: Types.ObjectId
+       name?: string
+       created_at?: Date
+       updated_at?: Date
+   }
+   ```
+
+   - The `store` ref is `Types.ObjectId` and **not** optional, because multi-tenant queries always require it.
+   - Other fields default to optional.
+
+3. Re-export the interface from `src/types.ts` (keep the file alphabetically sorted):
+
+   ```ts
+   export type {IMy} from './interfaces/My'
+   ```
+
+4. Bump `package.json` — **minor** for a new schema.
+
+5. Run `yarn build` and verify `dist/schemas/<Name>.js` exists and compiles.
+
+## Adding an embedded type
+
+Embedded types live in `src/schemas/types/` (generic) or `src/schemas/products/` (product-specific). They are reused across multiple parent schemas.
+
+```ts
+// src/schemas/types/Coordinates.ts
+import {Schema} from 'mongoose'
+
+/** Embedded geo coordinates */
+const Coordinates = new Schema(<Record<string, any>>{
+    _id: false,
+
+    /** Latitude, decimal degrees, WGS84 */
+    lat: {
+        type: Number,
+    },
+
+    /** Longitude, decimal degrees, WGS84 */
+    lng: {
+        type: Number,
+    },
+})
+
+export = Coordinates
+```
+
+```ts
+// src/interfaces/types/Coordinates.ts
+export interface ICoordinates {
+    lat?: number
+    lng?: number
+}
+```
+
+Re-export from `src/types.ts`. Use the embedded schema in parent schemas via `import = require('...')`:
+
+```ts
+// src/schemas/Store.ts
+import Coordinates = require('./types/Coordinates')
+
+const Store = new Schema(<Record<string, any>>{
+    // …
+    location: {
+        type: Coordinates,
+    },
+})
+```
+
+And on the interface side, reference the embedded type:
+
+```ts
+import type {ICoordinates} from './types/Coordinates'
+
+export interface IStore {
+    location?: ICoordinates
+}
+```
+
+## Versioning
+
+Semver, no exceptions:
+
+| Change                                                       | Bump  |
+| ------------------------------------------------------------ | ----- |
+| New field, new schema, new index (backward compatible)       | minor |
+| JSDoc/comment-only changes                                   | patch |
+| Renaming a field, removing a field/schema, changing a type   | major |
+| Removing/changing an existing index (writes behave differently) | major |
+| Build/format change (e.g. v6.0.0 TS rewrite)                 | major |
+
+Bump in the **same commit** as the change. If you forget, the publish will still go through but consumers won't know they need to update.
+
+## Build & verification
+
+```bash
+yarn install
+yarn build                          # tsc → dist/
+yarn dev                            # tsc --watch during development
+node scripts/snapshot.js            # diffs dist/schemas/ vs legacy schemas/ (when present)
+node --import tsx scripts/smoke-schemas-ts.mts
+                                    # loads dist/ through schemas-ts to verify the bridge works
+```
+
+The smoke script is the most useful check before publishing — it catches the case where a `export =` was accidentally changed to `export default`, which breaks `schemis`'s `require()` consumer.
+
+## Publishing
+
+The npm tarball is `dist/` only (see `"files": ["dist"]` in `package.json`). Make sure:
+
+1. `yarn build` produced a clean `dist/`.
+2. `package.json` version is bumped.
+3. Commit, tag, push. CI publishes on tag.
+
+Do **not** edit `dist/` directly. It is gitignored and regenerated on every build.
+
+## House style for JSDoc
+
+Field-level JSDoc is the doc site. Conventions:
+
+- Lead with what the field stores, not its type — the type is right there in the def.
+- For enums, list every legal value:
+
+  ```ts
+  /**
+   * Order status:
+   * - pending: awaiting payment
+   * - paid: payment captured
+   * - cancelled: cancelled by buyer or merchant
+   */
+  status: {
+      type: String,
+      enum: ['pending', 'paid', 'cancelled'],
+  },
+  ```
+
+- For ObjectId refs, use `@ref ModelName`:
+
+  ```ts
+  /** @ref Store */
+  store: {
+      type: Schema.Types.ObjectId,
+      ref: 'Store',
+      index: true,
+  },
+  ```
+
+- For TTL or partial indexes, document the rationale at the `Schema.index` call:
+
+  ```ts
+  // 60-day TTL — ShortLog entries are only interesting for the recent past.
+  ShortLog.index({created_at: 1}, {expireAfterSeconds: 60 * 24 * 60 * 60})
+  ```
+
+## Useful references
+
+- [usage-js.md](./usage-js.md) — consumer guide for CJS services
+- [usage-ts.md](./usage-ts.md) — consumer guide for TS services
+- [migration.md](./migration.md) — v5 → v6 upgrade walkthrough
+- [CLAUDE.md](../CLAUDE.md) — short-form rules (the one Claude reads)

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,11 +1,12 @@
 {
   "name": "@pintahub/database-schemas",
-  "version": "6.0.0",
+  "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"
+    "dist",
+    "docs"
   ],
   "exports": {
     ".": {