couchset 0.2.7 → 0.3.0

package/docs/beta-migration.md

@@ -0,0 +1,175 @@
+# CouchSet Beta Migration
+
+The beta release keeps the main `couchset` import on the legacy implementation so existing projects can upgrade safely. The modern implementation is available from `couchset/next`.
+
+```ts
+import {Model as LegacyModel} from 'couchset';
+import {Model as NextModel} from 'couchset/next';
+
+const legacyUsers = new LegacyModel('User');
+const nextUsers = new NextModel('User');
+```
+
+Use `couchset` when an application depends on old pagination or custom query behavior. New work should use `couchset/next`.
+
+Modern and legacy models share the same connection singleton. Initialize CouchSet once and use both model APIs side by side while migrating.
+
+```ts
+import {couchset, Model} from 'couchset';
+import {Model as NextModel} from 'couchset/next';
+
+await couchset(args);
+
+const legacyUsers = new Model('User');
+const nextUsers = new NextModel('User');
+```
+
+## Connection Lifecycle
+
+Models can be constructed before the Couchbase connection is ready. Model methods wait for the shared connection before touching the bucket or collection.
+
+```ts
+import {couchset, Model, ready, health, ping, shutdown} from 'couchset/next';
+
+const users = 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 ready();
+await ping();
+console.log(health());
+
+await couchset.ready();
+
+const user = await users.insert({userId: 'ceddy'});
+
+await shutdown();
+```
+
+Reconnect is enabled by default. It can be controlled with connection args or environment variables.
+
+```ts
+await couchset({
+    connectionString: 'couchbase://localhost',
+    username: 'admin',
+    password: '1234',
+    bucketName: 'dev',
+    autoReconnect: true,
+    reconnectIntervalMs: 5000,
+});
+```
+
+Environment flags:
+
+- `COUCHSET_RECONNECT`: defaults to enabled. Use `false`, `0`, or `no` to disable.
+- `COUCHSET_RECONNECT_INTERVAL_MS`: reconnect and health-check interval in milliseconds. Defaults to `5000`.
+
+`couchset/next` also exports env-based starter helpers:
+
+```ts
+import {startCouchbase, startCouchbaseServerless} from 'couchset/next';
+
+await startCouchbase();
+await startCouchbaseServerless();
+```
+
+The starters read `COUCHBASE_URL`, `COUCHBASE_BUCKET`, `COUCHBASE_USERNAME`, `COUCHBASE_PASSWORD`, and `COUCHBASE_PROXY`, and accept `CouchsetArgs` overrides.
+
+## Query Behavior
+
+Modern query helpers throw by default. This makes production failures visible and keeps silent fallbacks explicit.
+
+```ts
+const rows = await users.findMany({
+    where: {userId: {$eq: 'ceddy'}},
+});
+
+const page = await users.page({
+    where: {userId: {$eq: 'ceddy'}},
+    limit: 25,
+    page: 0,
+});
+
+const customRows = await users.queryRows(
+    `SELECT * FROM ${users.bucket()} WHERE userId=$userId LIMIT $limit`,
+    {userId: 'ceddy', limit: 25}
+);
+```
+
+If a caller intentionally wants the old empty-result fallback, pass `throwOnError: false`.
+
+```ts
+const rows = await users.findMany({
+    where: {userId: {$eq: 'ceddy'}},
+    limit: 25,
+    page: 0,
+    throwOnError: false,
+});
+```
+
+## Safer SQL++ Helpers
+
+Use the model keyspace helpers instead of hardcoding bucket names.
+
+```ts
+users.bucket(); // `dev`
+users.from('u'); // `dev` AS u
+```
+
+For scoped collections, `from()` includes the full keyspace.
+
+```ts
+const audit = new Model('AuditEvent', {
+    scope: 'app',
+    collection: 'events',
+});
+
+audit.from('event'); // `dev`.`app`.`events` AS event
+```
+
+## New Model APIs
+
+The modern path includes safer read, write, document, TTL, include, index, and time series helpers.
+
+```ts
+await users.insert({id: 'user::1', userId: 'ceddy'});
+await users.patchById('user::1', {$set: {email: 'ceddy@example.com'}});
+await users.softDeleteById('user::1');
+await users.restoreById('user::1');
+
+const exists = await users.exists({where: {userId: {$eq: 'ceddy'}}});
+const count = await users.count({where: {userId: {$eq: 'ceddy'}}});
+```
+
+## Removed Modern Model Aliases
+
+The old method names belong to the default `couchset` entrypoint and the explicit `couchset/legacy` alias.
+
+| 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()` |
+
+Index declarations can live on the model and be created at app boot.
+
+```ts
+const users = new Model('User', {
+    indexes: [
+        {
+            name: 'idx_user_userId',
+            fields: ['userId'],
+        },
+    ],
+});
+
+await couchset.ensureIndexes();
+```

package/legacy/index.js

@@ -0,0 +1 @@
+module.exports = require('../dist/legacy');

package/legacy/package.json

@@ -0,0 +1,4 @@
+{
+    "main": "../dist/legacy/index.js",
+    "types": "../dist/legacy/index.d.ts"
+}

package/next/index.js

@@ -0,0 +1 @@
+module.exports = require('../dist');

package/next/package.json

@@ -0,0 +1,4 @@
+{
+    "main": "../dist/index.js",
+    "types": "../dist/index.d.ts"
+}

package/package.json

@@ -1,13 +1,15 @@
 {
     "name": "couchset",
-    "version": "0.2.7",
+    "version": "0.3.0",
     "description": "Couchbase ORM",
     "private": false,
-    "main": "dist/index.js",
-    "types": "dist/index.d.ts",
+    "main": "dist/legacy/index.js",
+    "types": "dist/legacy/index.d.ts",
     "files": [
         "docs/",
         "dist/",
+        "legacy/",
+        "next/",
         "register/",
         "LICENSE"
     ],
@@ -16,7 +18,6 @@
         "build": "rimraf dist && ./node_modules/.bin/tsc --skipLibCheck",
         "test": "mocha src/index.test.ts --exit",
         "test:serverless": "mocha src/index.serverless.test.ts --exit",
-        "test:auto": "mocha src/automation.test.ts --exit",
         "prepublishOnly": "npm run build",
         "eslint": "eslint ./src --fix --ext=ts"
     },
@@ -65,7 +66,7 @@
         "@types/dotenv": "^6.1.1",
         "@types/express": "^4.17.13",
         "@types/lodash": "^4.17.10",
-        "@types/mocha": "^8.2.0",
+        "@types/mocha": "^10.0.10",
         "@types/node": "^10.0.3",
         "@types/source-map-support": "^0.4.0",
         "@types/uuid": "^8.3.0",
@@ -83,7 +84,7 @@
         "eslint-plugin-typescript": "^0.14.0",
         "husky": "^4.2.5",
         "lint-staged": "^10.1.7",
-        "mocha": "^9.2.0",
+        "mocha": "^11.3.0",
         "prettier": "^2.0.5",
         "reflect-metadata": "^0.1.13",
         "rimraf": "^2.5.4",
@@ -94,10 +95,14 @@
         "typescript": "^5.6.3"
     },
     "dependencies": {
-        "couchbase": "^4.4.2",
+        "couchbase": "^4.7.0",
         "couchbase-serverless": "^0.0.4",
         "debug": "^4.3.1",
-        "lodash": "^4.17.21",
+        "lodash": "^4.18.1",
         "uuid": "^8.3.2"
+    },
+    "overrides": {
+        "serialize-javascript": "^7.0.5",
+        "js-yaml": "^4.1.1"
     }
 }

package/dist/connection.d.ts

@@ -1,42 +0,0 @@
-import type { Collection, Cluster, Bucket } from 'couchbase';
-export interface CouchsetArgs {
-    connectionString: string;
-    bucketName: string;
-    username: string;
-    password: string;
-    proxy?: string;
-}
-/**
- * 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;
-    connectionString: string;
-    bucketName: string;
-    username: string;
-    password: string;
-    static get Instance(): CouchbaseConnection;
-    private constructor();
-    /**
-     * start
-     */
-    init: (args: CouchsetArgs) => Promise<CouchbaseConnection>;
-    /**
-     * start serverless start
-     */
-    initServerless: (args: CouchsetArgs) => CouchbaseConnection;
-    /**
-     * getCollection
-     */
-    getCollection: () => Collection;
-    getCluster: () => Cluster;
-    getBucket: () => string;
-    /**
-     * shutdown cluster
-     */
-    shutdown: () => Promise<void>;
-}
-export default CouchbaseConnection;

package/dist/connection.js

@@ -1,156 +0,0 @@
-"use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
-var __importStar = (this && this.__importStar) || function (mod) {
-    if (mod && mod.__esModule) return mod;
-    var result = {};
-    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
-    __setModuleDefault(result, mod);
-    return result;
-};
-var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
-    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
-    return new (P || (P = Promise))(function (resolve, reject) {
-        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
-        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
-        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
-        step((generator = generator.apply(thisArg, _arguments || [])).next());
-    });
-};
-var __generator = (this && this.__generator) || function (thisArg, body) {
-    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g = Object.create((typeof Iterator === "function" ? Iterator : Object).prototype);
-    return g.next = verb(0), g["throw"] = verb(1), g["return"] = verb(2), typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
-    function verb(n) { return function (v) { return step([n, v]); }; }
-    function step(op) {
-        if (f) throw new TypeError("Generator is already executing.");
-        while (g && (g = 0, op[0] && (_ = 0)), _) try {
-            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
-            if (y = 0, t) op = [op[0] & 2, t.value];
-            switch (op[0]) {
-                case 0: case 1: t = op; break;
-                case 4: _.label++; return { value: op[1], done: false };
-                case 5: _.label++; y = op[1]; op = [0]; continue;
-                case 7: op = _.ops.pop(); _.trys.pop(); continue;
-                default:
-                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) { _ = 0; continue; }
-                    if (op[0] === 3 && (!t || (op[1] > t[0] && op[1] < t[3]))) { _.label = op[1]; break; }
-                    if (op[0] === 6 && _.label < t[1]) { _.label = t[1]; t = op; break; }
-                    if (t && _.label < t[2]) { _.label = t[2]; _.ops.push(op); break; }
-                    if (t[2]) _.ops.pop();
-                    _.trys.pop(); continue;
-            }
-            op = body.call(thisArg, _);
-        } catch (e) { op = [6, e]; y = 0; } finally { f = t = 0; }
-        if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
-    }
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.CouchbaseConnection = void 0;
-var couchbase = __importStar(require("couchbase"));
-/**
- * CouchbaseConnection class
- * Only one CouchbaseConnection can exist that's why it's a singleton
- */
-var CouchbaseConnection = /** @class */ (function () {
-    function CouchbaseConnection() {
-        var _this = this;
-        this.bucket = null;
-        this.cluster = null;
-        // Args
-        this.connectionString = null;
-        this.bucketName = null;
-        this.username = null;
-        this.password = null;
-        /**
-         * start
-         */
-        this.init = function (args) { return __awaiter(_this, void 0, void 0, function () {
-            var connectionString, password, username, _a, bucketName, cluster;
-            return __generator(this, function (_b) {
-                switch (_b.label) {
-                    case 0:
-                        connectionString = args.connectionString, password = args.password, username = args.username, _a = args.bucketName, bucketName = _a === void 0 ? 'default' : _a;
-                        this.connectionString = connectionString;
-                        this.bucketName = bucketName;
-                        this.username = username;
-                        this.password = password;
-                        return [4 /*yield*/, couchbase.connect(connectionString, {
-                                username: username,
-                                password: password,
-                            })];
-                    case 1:
-                        cluster = _b.sent();
-                        this.cluster = cluster;
-                        this.bucket = this.cluster.bucket(bucketName);
-                        return [2 /*return*/, this];
-                }
-            });
-        }); };
-        /**
-         * start serverless start
-         */
-        this.initServerless = function (args) {
-            var connectionString = args.connectionString, password = args.password, username = args.username, _a = args.bucketName, bucketName = _a === void 0 ? 'default' : _a;
-            _this.connectionString = connectionString;
-            _this.bucketName = bucketName;
-            _this.username = username;
-            _this.password = password;
-            var connectionOpt = {
-                username: username,
-                password: password,
-            };
-            if (args.proxy) {
-                connectionOpt['proxy'] = args.proxy;
-            }
-            var cluster = new couchbase.Cluster(connectionString, connectionOpt);
-            _this.cluster = cluster;
-            _this.bucket = _this.cluster.bucket(bucketName);
-            return _this;
-        };
-        /**
-         * getCollection
-         */
-        this.getCollection = function () {
-            return _this.bucket.defaultCollection();
-        };
-        this.getCluster = function () {
-            return _this.cluster;
-        };
-        this.getBucket = function () {
-            return _this.bucketName;
-        };
-        /**
-         * shutdown cluster
-         */
-        this.shutdown = function () { return __awaiter(_this, void 0, void 0, function () {
-            return __generator(this, function (_a) {
-                return [2 /*return*/, this.cluster.close()];
-            });
-        }); };
-    }
-    Object.defineProperty(CouchbaseConnection, "Instance", {
-        get: function () {
-            return this._instance || (this._instance = new this());
-        },
-        enumerable: false,
-        configurable: true
-    });
-    return CouchbaseConnection;
-}());
-exports.CouchbaseConnection = CouchbaseConnection;
-exports.default = CouchbaseConnection;
-//# sourceMappingURL=connection.js.map

package/dist/connection.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"connection.js","sourceRoot":"","sources":["../src/connection.ts"],"names":[],"mappings":"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","sourcesContent":["import type {Collection, Cluster, Bucket} from 'couchbase';\nimport * as couchbase from 'couchbase';\n\nexport interface CouchsetArgs {\n    connectionString: string;\n    bucketName: string;\n    username: string;\n    password: string;\n    proxy?: string;\n}\n\n/**\n * CouchbaseConnection class\n * Only one CouchbaseConnection can exist that's why it's a singleton\n */\nexport class CouchbaseConnection implements CouchsetArgs {\n    private static _instance: CouchbaseConnection;\n\n    bucket: Bucket = null;\n    cluster: Cluster = null;\n\n    // Args\n    connectionString: string = null;\n    bucketName: string = null;\n    username: string = null;\n    password: string = null;\n\n    public static get Instance(): CouchbaseConnection {\n        return this._instance || (this._instance = new this());\n    }\n\n    private constructor() {}\n\n    /**\n     * start\n     */\n    public init = async (args: CouchsetArgs): Promise<CouchbaseConnection> => {\n        const {connectionString, password, username, bucketName = 'default'} = args;\n\n        this.connectionString = connectionString;\n        this.bucketName = bucketName;\n        this.username = username;\n        this.password = password;\n\n        const cluster = await couchbase.connect(connectionString, {\n            username,\n            password,\n        });\n\n        this.cluster = cluster as any;\n        this.bucket = this.cluster.bucket(bucketName);\n\n        return this;\n    };\n\n    /**\n     * start serverless start\n     */\n    public initServerless = (args: CouchsetArgs): CouchbaseConnection => {\n        const {connectionString, password, username, bucketName = 'default'} = args;\n\n        this.connectionString = connectionString;\n        this.bucketName = bucketName;\n        this.username = username;\n        this.password = password;\n\n        const connectionOpt = {\n            username,\n            password,\n        };\n\n        if (args.proxy) {\n            connectionOpt['proxy'] = args.proxy;\n        }\n\n        const cluster = new couchbase.Cluster(connectionString, connectionOpt);\n\n        this.cluster = cluster as any;\n        this.bucket = this.cluster.bucket(bucketName);\n\n        return this;\n    };\n\n    /**\n     * getCollection\n     */\n    public getCollection = (): Collection => {\n        return this.bucket.defaultCollection();\n    };\n\n    public getCluster = (): Cluster => {\n        return this.cluster;\n    };\n\n    public getBucket = (): string => {\n        return this.bucketName;\n    };\n\n    /**\n     * shutdown cluster\n     */\n    public shutdown = async (): Promise<void> => {\n        return this.cluster.close();\n    };\n}\n\nexport default CouchbaseConnection;\n"]}