couchset 0.2.7 → 0.4.0

package/CHANGELOG.md

@@ -0,0 +1,41 @@
+# Changelog
+
+## 0.3.0 - 2026-05-18
+
+### Compatibility
+
+- Kept the default `couchset` entrypoint on the legacy API so existing projects can upgrade without rewriting model imports.
+- Kept `couchset/legacy` as an explicit legacy alias.
+- Added `couchset/next` for the modern API.
+- Shared one Couchbase connection singleton across legacy and modern models, allowing both APIs to run side by side during gradual migrations.
+
+### Modern API
+
+- Added strict modern model helpers: `insert`, `upsert`, `getById`, `replaceById`, `patchById`, `deleteById`, `findMany`, `findOne`, `page`, `exists`, and `count`.
+- Removed old model method names from the modern model surface so the new API can evolve independently.
+- Added hydrated document helpers for reload/save/patch/delete workflows.
+- Added soft-delete/default-scope helpers, TTL helpers, validation/parse hooks, scoped collection support, include helpers, and declarative index helpers.
+- Added safe SQL++ query helpers with named/positional parameters: `queryRows`, `queryOne`, and `queryPage`.
+- Added safer keyspace helpers: `Model.bucket()` and `Model.from(alias?)`.
+
+### Connection Lifecycle
+
+- Added lazy model binding so models can be constructed before `couchset()` connects.
+- Added lifecycle helpers: `ready`, `ping`, `health`, `shutdown`, and `ensureIndexes`.
+- Added reconnect support that is enabled by default, with `COUCHSET_RECONNECT` and `COUCHSET_RECONNECT_INTERVAL_MS` environment controls.
+- Added retry/rebind behavior for reconnectable operation failures.
+
+### Starters
+
+- Added modern env-based starter helpers on `couchset/next`: `getConnectionOptions`, `connectionOptions`, `startCouchbase`, and `startCouchbaseServerless`.
+- Starter helpers read `COUCHBASE_URL`, `COUCHBASE_BUCKET`, `COUCHBASE_USERNAME`, `COUCHBASE_PASSWORD`, and `COUCHBASE_PROXY`.
+
+### Documentation
+
+- Updated the README for the legacy-default and modern-next import paths.
+- Added beta migration notes for running legacy and modern models together.
+
+### Maintenance
+
+- Cleared high and critical `npm audit` findings.
+- Updated the publish workflow to the two-job version bump and npm publish flow.

package/README.md

@@ -1,236 +1,376 @@
-
 <p align="center">
-  <h1 align="center"> CouchSet - Couchbase ORM & Automatic GraphQL API generator (Resolver/Queries)</h1>
+  <h1 align="center">CouchSet</h1>
 </p>
 
-
 <div align="center">
-
-<div style="display: flex;justify-content:center;">
-
-
-<img alt="NPM" src="https://img.shields.io/npm/dt/couchset.svg"></img>
-
- 
-
-</div>
-
-<img width="500px" src="./docs/couchset.png"></img>
+  <img alt="NPM" src="https://img.shields.io/npm/dt/couchset.svg"></img>
+  <br />
+  <img width="500px" src="./docs/couchset.png"></img>
 </div>
 
+CouchSet is a Couchbase model layer for TypeScript and Node.js. The default `couchset` entrypoint keeps the legacy API for safe upgrades; the modern API is available from `couchset/next`.
 
-CouchSet is a Couchbase ORM & Automatic GraphQL API code generator (Resolver/Queries) tool
+The additive client-owned primitives—typed definitions, explicit provisioning, transaction-bound models, CAS helpers, and safe index plans—are documented in [Next primitives](./docs/next-primitives.md).
 
 - [Install](#install)
+- [Legacy Default](#legacy-default)
+- [Modern API](#modern-api)
+- [Next primitives](./docs/next-primitives.md)
+- [Connection Lifecycle](#connection-lifecycle)
+- [Models](#models)
+- [Reads](#reads)
+- [Document Modeling](./docs/document-modeling.md)
+- [Writes](#writes)
+- [Queries](#queries)
+- [Gradual Migration](#gradual-migration)
+- [Migration Notes](./docs/beta-migration.md)
+- [Changelog](./CHANGELOG.md)
 - [License](#license)
 
-## 1. Install
+## Install
+
 ```bash
 npm i couchset --save
 ```
 
-## 2. Start couchset
+## Legacy Default
+
+Existing projects can keep importing from `couchset` and continue using the old model methods while gradually migrating.
+
 ```ts
-import { couchset } from 'couchset';
+import {couchset, Model} from 'couchset';
 
- const started = await couchset({
-    connectionString: 'couchbase://localhost',
-    username: 'admin',
-    password: '123456',
-    bucketName: 'stq'
- })
+await couchset({
+    connectionString: process.env.COUCHBASE_URL || 'couchbase://localhost',
+    username: process.env.COUCHBASE_USERNAME || 'admin',
+    password: process.env.COUCHBASE_PASSWORD || '1234',
+    bucketName: process.env.COUCHBASE_BUCKET || 'dev',
+});
+
+const users = new Model('User', {schema: {createdAt: 'date'}});
+
+const created = await users.create({
+    userId: 'ceddy',
+    email: 'ceddy@example.com',
+});
+
+const found = await users.findById(created.id);
+await users.updateById(created.id, {...found, email: 'new@example.com'});
+await users.delete(created.id);
 ```
 
-## 3. Create a Model and start using it
+## Modern API
+
+New code can opt into the modern API with `couchset/next`.
 
 ```ts
-import { Model } from 'couchset';
+import {couchset, Model} from 'couchset/next';
+
+type User = {
+    userId: string;
+    email?: string;
+};
+
+const users = new Model('User', {
+    schema: {
+        createdAt: 'date',
+        updatedAt: 'date',
+    },
+    indexes: [
+        {
+            name: 'idx_user_userId',
+            fields: ['userId'],
+        },
+    ],
+});
 
-const userModel = new Model('User');
+await couchset({
+    connectionString: process.env.COUCHBASE_URL || 'couchbase://localhost',
+    username: process.env.COUCHBASE_USERNAME || 'admin',
+    password: process.env.COUCHBASE_PASSWORD || '1234',
+    bucketName: process.env.COUCHBASE_BUCKET || 'dev',
+});
 
+await couchset.ready();
 
-// Create document
-const created = await userModel.create({
-    username: 'ceddy',
-    password: 'love couchbase',
+const created = await users.insert<User>({
+    userId: 'ceddy',
+    email: 'ceddy@example.com',
 });
 
-// Find document
-const foundData = await userModel.findById(created.id);
+const found = await users.getById<User>(created.id);
 
-// update document
-const updatedData = await userModel.updateById(created.id, { ...created, someValue: 'x' });
+const patched = await users.patchById<User>(created.id, {
+    $set: {email: 'new@example.com'},
+});
 
-// delete
-const deletedData = await userModel.delete(created.id);
+const page = await users.page<User>({
+    where: {userId: {$eq: 'ceddy'}},
+    limit: 25,
+    page: 0,
+});
 
+await users.deleteById(created.id, {hard: true});
 ```
 
-## 4. Pagination
+## Connection Lifecycle
+
+Models can be declared before connecting. Model operations wait for the shared connection before binding to the Couchbase bucket and collection.
 
-All models come with a method for automatic pagination 
 ```ts
-const paginationData = await userModel.pagination({
-    select: ["id", "email", "phone","fullname"],
-    where: { 
-        userId: { $eq: "ceddy" },
-        $or: [{ userId: { $eq: "ceddy" } }, { phone: 10 }],
-        },
-    limit: 100,
-    page: 0,
+import {couchset, health, ping, ready, shutdown} from 'couchset/next';
+
+await couchset({
+    connectionString: 'couchbase://localhost',
+    username: 'admin',
+    password: '1234',
+    bucketName: 'dev',
+    autoReconnect: true,
+    reconnectIntervalMs: 5000,
 });
+
+await ready();
+await ping();
+console.log(health());
+
+await shutdown();
 ```
 
-which translates to this query 
+Reconnect is enabled by default. Environment flags:
+
+- `COUCHSET_RECONNECT`: use `false`, `0`, or `no` to disable reconnect.
+- `COUCHSET_RECONNECT_INTERVAL_MS`: reconnect and health-check interval in milliseconds. Default is `5000`.
+
+The modern entrypoint also exports app starter helpers that read Couchbase credentials from env:
+
+```ts
+import {startCouchbase, startCouchbaseServerless} from 'couchset/next';
 
-```sql
-SELECT * FROM `stq` WHERE _type="User" AND userId="ceddy" AND (userId="ceddy" OR phone=10) ORDER BY createdAt DESC LIMIT 100 OFFSET 0
+await startCouchbase();
+await startCouchbaseServerless();
 ```
 
+The starters read `COUCHBASE_URL`, `COUCHBASE_BUCKET`, `COUCHBASE_USERNAME`, `COUCHBASE_PASSWORD`, and `COUCHBASE_PROXY`. You can pass any `CouchsetArgs` field as an override.
 
-Pagination results
+## Models
 
-```js
-[
-  {
-    id: '209d3143-09b7-4b3d-bf7d-f0ccd3f98922',
-    updatedAt: 2021-01-26T01:51:43.218Z,
-    createdAt: 2021-01-26T01:51:43.210Z,
-    _type: 'User',
-    userId: 'ceddy',
-    password: '...',
-    someValue: 'x'
-  },
-  {
-    id: '1392e4f6-ae1e-4e01-b7d5-103bdd0e843f',
-    updatedAt: 2021-01-26T01:51:29.591Z,
-    createdAt: 2021-01-26T01:51:29.583Z,
-    _type: 'User',
-    userId: 'ceddy',
-    password: '...',
-    someValue: 'x'
-  }
-]
+```ts
+const auditEvents = new Model('AuditEvent', {
+    scope: 'app',
+    collection: 'events',
+    softDelete: true,
+    defaultWhere: {tenantId: {$eq: 'tenant-1'}},
+    dateFields: ['profile.createdAt'],
+    validateCreate: (doc) => doc,
+    validateReplace: (doc) => doc,
+    parse: (doc) => doc,
+});
 ```
 
+Useful model helpers:
 
-## 5. Custom queries & Query builder
-Query builder is inspired from node-ottoman, for more examples, please see https://ottomanjs.com/guides/query-builder.html#query-builder
+```ts
+users.bucket(); // `dev`
+users.keyspace(); // `dev` or default:`dev`.`scope`.`collection`
+users.from('u'); // `dev` AS u
+```
+
+For large objects, keep list metadata and heavy payloads in separate models.
+See [Document Modeling](./docs/document-modeling.md) for the recommended read
+shape.
+
+## Reads
 
 ```ts
-import { Query } from 'couchset';
+await users.getById<User>('user::1');
+await users.findByIdWithMeta<User>('user::1');
+
+await users.findMany<User>({
+    select: ['id', 'userId', 'email'],
+    where: {userId: {$eq: 'ceddy'}},
+    orderBy: {createdAt: 'DESC'},
+    limit: 10,
+});
 
-const params = {
-  select: [
-    {
-      $count: {
-        $field: {
-          name: 'type',
-        },
-        as: 'odm',
-      },
-    },
-  ],
-  let: [
-    { key: 'amount_val', value: 10 },
-    { key: 'size_val', value: 20 },
-  ],
-  where: {
-    $or: [{ price: { $gt: 'amount_val', $isNotNull: true } }, { auto: { $gt: 10 } }, { amount: 10 }],
-    $and: [
-      { price2: { $gt: 1.99, $isNotNull: true } },
-      { $or: [{ price3: { $gt: 1.99, $isNotNull: true } }, { id: '20' }] },
-    ],
-    $any: {
-      $expr: [{ $in: { search_expr: 'search', target_expr: 'address' } }],
-      $satisfied: { address: '10' },
-    },
-    $in: { search_expr: 'search', target_expr: ['address'] },
-  },
-  groupBy: [{ expr: 'type', as: 'sch' }],
-  letting: [
-    { key: 'amount_v2', value: 10 },
-    { key: 'size_v2', value: 20 },
-  ],
-  having: { type: { $like: '%hotel%' } },
-  orderBy: { type: 'DESC' },
-  limit: 10,
-  offset: 1,
-  use: ['airlineR_8093', 'airlineR_8094'],
-};
+await users.findOne<User>({where: {email: {$eq: 'ceddy@example.com'}}});
+await users.exists({where: {userId: {$eq: 'ceddy'}}});
+await users.count({where: {userId: {$eq: 'ceddy'}}});
 
-const query = new Query(params, 'travel-sample').build();
-console.log(query);
+const result = await users.page<User>({
+    where: {userId: {$eq: 'ceddy'}},
+    limit: 10,
+    page: 0,
+});
 
+result.items;
+result.hasNext;
+result.pageInfo.nextPage;
 ```
 
-which translates to
+Hydrated documents:
+
+```ts
+const doc = await users.findDocById<User & {id: string}>('user::1');
 
-```sql
-SELECT COUNT(type) AS odm FROM travel-sample USE KEYS ["airlineR_8093","airlineR_8094"] LET amount_val=10,size_val=20 WHERE ((price>amount_val AND price IS NOT NULL) OR auto>10 OR amount=10) AND ((price2>1.99 AND price2 IS NOT NULL) AND ((price3>1.99 AND price3 IS NOT NULL) OR id="20")) AND ANY search IN address SATISFIES address="10" END AND search IN ["address"] GROUP BY type AS sch LETTING amount_v2=10,size_v2=20 HAVING type LIKE "%hotel%" ORDER BY type DESC LIMIT 10 OFFSET 1
+doc.email = 'updated@example.com';
+await doc.save();
+await doc.patch({$set: {verified: true}});
+await doc.reload();
+await doc.delete({hard: true});
 ```
 
+Soft delete scopes:
 
+```ts
+await users.softDeleteById<User>('user::1');
+await users.restoreById<User>('user::1');
+
+await users.withDeleted().findMany<User>();
+await users.onlyDeleted().findMany<User>();
+await users.withoutDefaultWhere().findMany<User>();
+```
 
-### Running custom query on cluster
+## Writes
 
 ```ts
-import { QueryCluster } from 'couchset';
+await users.insert<User>({id: 'user::1', userId: 'ceddy'});
+await users.upsert<User>({id: 'user::1', userId: 'ceddy'});
+await users.replaceById<User>('user::1', {userId: 'ceddy', email: 'new@example.com'});
+await users.patchById<User>('user::1', {
+    $set: {email: 'new@example.com'},
+    $inc: {loginCount: 1},
+    $unset: ['temporaryCode'],
+});
+await users.incrementById<User>('user::1', 'loginCount', 1);
+await users.deleteById('user::1', {hard: true});
+```
 
-const queryresults = await QueryCluster(queryBuilder);
-// queryresults = { rows: object[], meta: any}
+TTL helpers:
 
+```ts
+await users.insert<User>({id: 'user::1', userId: 'ceddy'}, {ttl: '2h'});
+await users.upsert<User>({id: 'user::2', userId: 'ceddy'}, {ttlSeconds: 300});
 ```
 
-## 6. Model Automation
+## Queries
 
-This is how we automate it to generate code with all methods,schema, queries 
+Modern query helpers pass SDK parameters correctly and throw on failures by default.
 
 ```ts
-const automaticUser = userModel.automate();
+const rows = await users.queryRows<User>(
+    `SELECT u.* FROM ${users.from('u')} WHERE u.userId=$userId LIMIT $limit`,
+    {userId: 'ceddy', limit: 10}
+);
+
+const first = await users.queryOne<User>(
+    `SELECT u.* FROM ${users.from('u')} WHERE u.email=$email LIMIT 1`,
+    {email: 'ceddy@example.com'}
+);
+
+const page = await users.queryPage<User>(
+    `SELECT u.* FROM ${users.from('u')} WHERE u.userId=$userId LIMIT $limit`,
+    {userId: 'ceddy', limit: 10}
+);
 ```
 
-After automating the model, `automaticUser` will come with Server-side Resolver functions, and client queries, mutations, subscriptions, like below
+Model read helpers also throw by default. Use `throwOnError: false` only when an empty fallback is intentional.
 
+```ts
+const rows = await users.findMany<User>({
+    where: {userId: {$eq: 'ceddy'}},
+    throwOnError: false,
+});
+```
+
+## Indexes
 
 ```ts
-// Get all automatic generated resolvers and queries/fragments,mutations,subscriptions
-const {
-  resolver: UserResolver, // Server resolver for building GraphQL 
-  modelKeys: UserSelectors, // for any custom queries or exporting
-  client, // client queries,mutations,subscriptions
-} = automaticUser;
+const users = new Model('User', {
+    indexes: [
+        {
+            name: 'idx_user_email',
+            fields: ['email'],
+            where: {deleted: {$isNotValued: true}},
+        },
+    ],
+});
 
+await users.ensureIndexes();
+await couchset.ensureIndexes();
 ```
 
-## 7. Write to filesystem
-TODO
+## Includes
 
+```ts
+const posts = new Model('Post');
+
+const rows = await posts.findMany({
+    where: {published: {$eq: true}},
+    include: [
+        {
+            as: 'author',
+            model: users,
+            key: 'authorId',
+            type: 'leftJoin',
+        },
+    ],
+});
+```
 
+## Time Series
 
+```ts
+import {TimeSeriesModel} from 'couchset/next';
 
-<br/>
-<br/>
-<br/>
+const metrics = new TimeSeriesModel('Metric', {
+    keyField: 'deviceId',
+    timeField: 'timestamp',
+    values: [{field: 'temperature'}],
+    interval: '1m',
+});
 
-#### Contributors needed 
-- Create automatic pagination ✅
-- Create Schema and validation/population ✅
-- Create static methods for models like `save`, `update`, `findMany` e.t.c ✅
-- Automated indexes (only couchbase enterprise) ✅
-- Geospatial queries ✅
-- FTS queries ✅
+await metrics.appendChunk('device-1', [
+    {deviceId: 'device-1', timestamp: Date.now(), temperature: 21.5},
+]);
+```
 
+## Gradual Migration
 
+Use `couchset` for old code and `couchset/next` for new code. Both model APIs share the same connection singleton, reconnect loop, and health state, so you can migrate one model or file at a time without opening a second Couchbase cluster connection.
 
+```ts
+import {couchset, Model} from 'couchset';
+import {Model as NextModel} from 'couchset/next';
 
-<div align="center">
-<img height="300px" src="./docs/couch.png"></img>
-</div>
+await couchset(args);
 
-<p align="center">
-  <h1 align="center"> Algo Inc </h1>
-</p>
+const legacyUsers = new Model('User');
+const nextUsers = new NextModel('User');
+```
+
+`couchset/legacy` remains available as an explicit alias for the default legacy API.
+
+Modern replacements:
+
+| Old method | Modern method |
+| --- | --- |
+| `create()` | `insert()` or `upsert()` |
+| `findById()` | `getById()` |
+| `updateById()` / `save()` | `replaceById()` or `patchById()` |
+| `delete()` | `deleteById()` |
+| `pagination()` | `findMany()` or `page()` |
+| `customQuery()` | `queryRows()`, `queryOne()`, or `queryPage()` |
+
+## Local Tests
+
+```bash
+npm run build
+npm test
+npm run test:serverless
+```
+
+Set `COUCHBASE_URL`, `COUCHBASE_BUCKET`, `COUCHBASE_USERNAME`, and `COUCHBASE_PASSWORD` to point the integration tests at a local Couchbase instance.
+
+## License
 
-## License	
-Couchset is [MIT licensed](./LICENSE).
+CouchSet is [MIT licensed](./LICENSE).

package/dist/connection/connection.d.ts

@@ -0,0 +1,68 @@
+import type { Bucket, Cluster, Collection } from 'couchbase';
+import { ConnectionHealth, ConnectionState, CouchsetArgs } from './types';
+/**
+ * CouchbaseConnection class
+ * Only one CouchbaseConnection can exist that's why it's a singleton
+ */
+export declare class CouchbaseConnection implements CouchsetArgs {
+    private static _instance;
+    bucket: Bucket;
+    cluster: Cluster;
+    private connectionPromise?;
+    private connectionSettings?;
+    private reconnectPromise?;
+    private reconnectReject?;
+    private reconnectTimer?;
+    private healthTimer?;
+    private connectionState;
+    private autoReconnectEnabled;
+    private reconnectDelayMs;
+    private manuallyClosed;
+    private lastConnectionError?;
+    connectionString: string;
+    bucketName: string;
+    username: string;
+    password: string;
+    static get Instance(): CouchbaseConnection;
+    private constructor();
+    private configureReconnect;
+    private normalizeArgs;
+    private sameSettings;
+    private assignSettings;
+    private settingsError;
+    private connectionOptions;
+    private clearReconnectTimer;
+    private clearHealthTimer;
+    private scheduleTimer;
+    private rawPing;
+    private openCluster;
+    private scheduleHealthCheck;
+    private connectWithSettings;
+    private startReconnect;
+    /**
+     * start
+     */
+    init: (args: CouchsetArgs) => Promise<CouchbaseConnection>;
+    /**
+     * start serverless start
+     */
+    initServerless: (args: CouchsetArgs) => Promise<CouchbaseConnection>;
+    /**
+     * getCollection
+     */
+    getCollection: (scopeName?: string, collectionName?: string) => Collection;
+    getCluster: () => Cluster;
+    getBucket: () => string;
+    isConnected: () => boolean;
+    ready: () => Promise<CouchbaseConnection>;
+    ping: () => Promise<any>;
+    state: () => ConnectionState;
+    health: () => ConnectionHealth;
+    shouldReconnect: (error: unknown) => boolean;
+    markDisconnected: (error?: unknown) => void;
+    /**
+     * shutdown cluster
+     */
+    shutdown: () => Promise<void>;
+}
+export default CouchbaseConnection;