couchset 0.4.1 → 0.5.1

package/README.md

@@ -10,15 +10,17 @@
 
 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`.
 
-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).
+The additive client-owned primitives—typed definitions, explicit provisioning, transaction-bound models, CAS helpers, safe index plans, and Eventing—are summarized below. Their complete operational guide is [Next primitives](./docs/next-primitives.md).
 
 - [Install](#install)
 - [Legacy Default](#legacy-default)
 - [Modern API](#modern-api)
+- [Modern Client Primitives](#modern-client-primitives)
 - [Next primitives](./docs/next-primitives.md)
 - [Connection Lifecycle](#connection-lifecycle)
 - [Models](#models)
 - [Reads](#reads)
+- [Typed Joins and Read Consistency](#typed-joins-and-read-consistency)
 - [Document Modeling](./docs/document-modeling.md)
 - [Writes](#writes)
 - [Queries](#queries)
@@ -113,6 +115,88 @@ const page = await users.page<User>({
 await users.deleteById(created.id, {hard: true});
 ```
 
+## Modern Client Primitives
+
+`couchset/next` also offers a client-owned API for typed manifests, explicit administrative work, safe operational plans, and Eventing. These are deliberately separate from the singleton `Model` API above.
+
+### Declarative models
+
+```ts
+import {createCouchsetClient, defineModel} from 'couchset/next';
+
+const sessions = defineModel({name: 'Session', scope: 'auth', collection: 'sessions'});
+const db = createCouchsetClient({bucketName: 'app', models: [sessions]});
+const sessionModel = db.model(sessions); // registers and binds; no DDL
+```
+
+Read the [full client and model-definition guide](./docs/next-primitives.md#couchset-next-primitives).
+
+### Provisioning and dynamic models
+
+```ts
+await db.ensureCollections(); // creates only missing scopes and collections
+await db.ensureIndexes();     // create-only index DDL
+
+const reports = await db.registerModel(reportDefinition, {provision: {collections: true}});
+```
+
+Read about [provisioning and dynamic models](./docs/next-primitives.md#provisioning-and-dynamic-models).
+
+### Transactions and CAS
+
+```ts
+await db.transaction(async (tx) => {
+    await tx.model(sessions).insert({id: 'session::1', userId: 'user::1'});
+});
+
+const outcome = await sessionModel.consumeOnce('session::1', knownCas);
+```
+
+Read the [transaction and CAS safety notes](./docs/next-primitives.md#transactions-and-cas).
+
+### Safe index plans
+
+```ts
+const plan = await db.planIndexes(); // inspect missing, matching, and drifted indexes
+await db.applyIndexPlan(plan);        // creates safe replacements and waits for them
+```
+
+Read about [index drift and opt-in cleanup](./docs/next-primitives.md#index-drift).
+
+### Eventing functions
+
+```ts
+import {defineEventingFunction} from 'couchset/next';
+
+const auditOrders = defineEventingFunction({
+    name: 'audit_orders',
+    code: 'function OnUpdate(doc, meta) { log(meta.id); }',
+    sourceKeyspace: {bucket: 'app', scope: 'sales', collection: 'orders'},
+});
+
+const eventing = db.eventing({
+    namespace: 'billing',
+    metadataKeyspace: {bucket: 'app', scope: 'eventing', collection: 'billing_metadata'},
+    definitions: [auditOrders],
+});
+
+await eventing.apply();
+```
+
+Read the [Eventing lifecycle and safety guide](./docs/next-primitives.md#eventing-functions).
+
+### Test fixtures
+
+```ts
+import {createCouchsetTestFixture} from 'couchset/next';
+
+const {model, cleanup} = await createCouchsetTestFixture(db, {name: 'Invoice'});
+// use model in the test
+await cleanup();
+```
+
+Read about [isolated CouchSet test fixtures](./docs/next-primitives.md#tests).
+
 ## Connection Lifecycle
 
 Models can be declared before connecting. Model operations wait for the shared connection before binding to the Couchbase bucket and collection.
@@ -150,7 +234,15 @@ 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.
+The starters accept one PostgreSQL-style `DB_URL` in place of the four connection settings. It takes precedence over `COUCHBASE_URL`, `COUCHBASE_BUCKET`, `COUCHBASE_USERNAME`, and `COUCHBASE_PASSWORD`; explicit `startCouchbase({...})` options still take precedence over either environment form.
+
+```bash
+DB_URL=couchbase://user:password@localhost/bucket
+DB_URL=couchbase://user:password@localhost:11210/bucket
+DB_URL=couchbases://user:password@cb.example.com/bucket
+```
+
+Use `couchbases://` for TLS. Percent-encode reserved characters in usernames, passwords, and bucket names (for example, `p%40ss` for `p@ss`). `COUCHBASE_PROXY` remains available as a separate optional setting.
 
 ## Models
 
@@ -230,6 +322,89 @@ await users.onlyDeleted().findMany<User>();
 await users.withoutDefaultWhere().findMany<User>();
 ```
 
+## Typed Joins and Read Consistency
+
+Client-bound models infer root and related fields. Using the client-owned `db`
+above, join profiles to battles by arbitrary fields:
+
+```ts
+import {dateCodec, defineModel, joinField} from 'couchset/next';
+import {QueryScanConsistency} from 'couchbase';
+
+const battles = db.model(defineModel<{
+    createdByUserId: string;
+    startsAt: Date;
+}>({name: 'Battle', scope: 'app', collection: 'battles', codecs: {startsAt: dateCodec}}));
+
+const profiles = db.model(defineModel<{
+    ownerUserId: string;
+    displayName: string;
+    birthday: Date;
+}>({name: 'Profile', scope: 'app', collection: 'profiles', codecs: {birthday: dateCodec}}));
+
+const joined = await battles.page({
+    sourceAlias: 'battle',
+    include: [{
+        as: 'creator',
+        model: profiles,
+        type: 'leftJoin',
+        on: {
+            left: joinField('creator.ownerUserId'),
+            op: '$eq',
+            right: joinField('battle.createdByUserId'),
+        },
+    }],
+    limit: 20,
+    queryOptions: {scanConsistency: QueryScanConsistency.RequestPlus},
+});
+
+joined.items[0]?.startsAt;          // Date | undefined
+joined.items[0]?.creator?.birthday; // Date | undefined; related codec applied
+```
+
+Provision the collections and appropriate indexes explicitly before querying.
+`joinField()` denotes a field reference; an ordinary string is a bound value.
+Use `$and` / `$or` to combine predicates. Existing `key` / `keys` includes still
+use `ON KEYS`.
+
+Use NEST for arrays, and select just the fields needed:
+
+```ts
+const summaries = await battles.findMany({
+    select: ['startsAt'],
+    include: [{
+        as: 'creators',
+        model: profiles,
+        type: 'leftNest',
+        on: {left: joinField('creators.ownerUserId'), op: '$eq', right: joinField('doc.createdByUserId')},
+        select: ['displayName', 'birthday'],
+    }],
+});
+// {startsAt: Date; creators: {displayName: string; birthday: Date}[]}[]
+```
+
+LEFT JOIN may omit its related property; LEFT NEST returns `[]` when unmatched.
+JOIN preserves one row per match, including repeated root IDs. Choose an alias
+that does not overwrite a root field. NEST does not promise source-key ordering.
+
+For read-your-writes, pass tokens from successful SDK mutations:
+
+```ts
+import {MutationState, MutationToken} from 'couchbase';
+
+async function readAfterWrites(tokens: MutationToken[]) {
+    return battles.findMany({
+        queryOptions: {consistentWith: new MutationState(...tokens)},
+    });
+}
+// Call with SDK mutationResult.token values, not whole mutation results.
+```
+
+`request_plus` and `consistentWith` are alternatives; neither is a multi-document
+transaction. Defaults are unchanged when no consistency option is supplied.
+See [joined reads and consistency](./docs/joins-and-consistency.md) for predicates,
+projection limits, codecs, compatibility changes, and live validation results.
+
 ## Writes
 
 ```ts

package/dist/database.d.ts

@@ -3,6 +3,12 @@ export type CouchbaseStarterLogger = ((...args: any[]) => void) | false;
 export interface StartCouchbaseOptions extends Partial<CouchsetArgs> {
     logger?: CouchbaseStarterLogger;
 }
+/**
+ * Convert a PostgreSQL-style DB_URL into Couchbase SDK connection settings.
+ * The bucket lives in the URL path; it is not part of Couchbase's connection
+ * string, which contains only the scheme, host, optional port, and options.
+ */
+export declare const parseDatabaseUrl: (value: string) => Pick<CouchsetArgs, "bucketName" | "connectionString" | "password" | "username">;
 export declare const getConnectionOptions: (overrides?: Partial<CouchsetArgs>) => CouchsetArgs;
 export declare const connectionOptions: CouchsetArgs;
 export declare const startCouchbase: (options?: StartCouchbaseOptions) => Promise<boolean>;

package/dist/database.js

@@ -86,13 +86,61 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.startCouchbaseServerless = exports.startCouchbase = exports.connectionOptions = exports.getConnectionOptions = void 0;
+exports.startCouchbaseServerless = exports.startCouchbase = exports.connectionOptions = exports.getConnectionOptions = exports.parseDatabaseUrl = void 0;
 var connection_1 = __importDefault(require("./connection"));
 var envValue = function (key, fallback) {
     if (fallback === void 0) { fallback = ''; }
     var value = typeof process !== 'undefined' && process.env ? process.env[key] : undefined;
     return value === undefined ? fallback : value;
 };
+var databaseUrlError = function (reason) {
+    return new Error("DB_URL must use couchbase:// or couchbases://user:password@host/bucket: ".concat(reason));
+};
+var decodeDatabaseUrlComponent = function (value, label) {
+    try {
+        return decodeURIComponent(value);
+    }
+    catch (_error) {
+        throw databaseUrlError("".concat(label, " contains invalid percent-encoding"));
+    }
+};
+/**
+ * Convert a PostgreSQL-style DB_URL into Couchbase SDK connection settings.
+ * The bucket lives in the URL path; it is not part of Couchbase's connection
+ * string, which contains only the scheme, host, optional port, and options.
+ */
+var parseDatabaseUrl = function (value) {
+    var url;
+    try {
+        url = new URL(value);
+    }
+    catch (_error) {
+        throw databaseUrlError('the value is not a valid URL');
+    }
+    if (url.protocol !== 'couchbase:' && url.protocol !== 'couchbases:') {
+        throw databaseUrlError("unsupported protocol ".concat(url.protocol || '(missing)'));
+    }
+    if (!url.hostname) {
+        throw databaseUrlError('a host is required');
+    }
+    if (!url.username || !url.password) {
+        throw databaseUrlError('a username and password are required');
+    }
+    if (url.hash) {
+        throw databaseUrlError('fragments are not supported');
+    }
+    var bucketName = decodeDatabaseUrlComponent(url.pathname.replace(/^\//, ''), 'the bucket name');
+    if (!bucketName || bucketName.indexOf('/') !== -1) {
+        throw databaseUrlError('the path must contain exactly one bucket name');
+    }
+    return {
+        bucketName: bucketName,
+        connectionString: "".concat(url.protocol, "//").concat(url.host).concat(url.search),
+        password: decodeDatabaseUrlComponent(url.password, 'the password'),
+        username: decodeDatabaseUrlComponent(url.username, 'the username'),
+    };
+};
+exports.parseDatabaseUrl = parseDatabaseUrl;
 var maskPassword = function (password) {
     return password ? 'xxxxxx' : 'empty';
 };
@@ -104,6 +152,7 @@ var splitStartOptions = function (options) {
 var getConnectionOptions = function (overrides) {
     if (overrides === void 0) { overrides = {}; }
     var proxy = envValue('COUCHBASE_PROXY');
+    var databaseUrl = envValue('DB_URL');
     var options = {
         bucketName: envValue('COUCHBASE_BUCKET', 'dev'),
         connectionString: envValue('COUCHBASE_URL', 'couchbase://localhost'),
@@ -113,7 +162,7 @@ var getConnectionOptions = function (overrides) {
     if (proxy) {
         options.proxy = proxy;
     }
-    return __assign(__assign({}, options), overrides);
+    return __assign(__assign(__assign({}, options), (databaseUrl ? (0, exports.parseDatabaseUrl)(databaseUrl) : {})), overrides);
 };
 exports.getConnectionOptions = getConnectionOptions;
 exports.connectionOptions = (0, exports.getConnectionOptions)();

package/dist/database.js.map

@@ -1 +1 @@
-{"version":3,"file":"database.js","sourceRoot":"","sources":["../src/database.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA,4DAA+D;AAQ/D,IAAM,QAAQ,GAAG,UAAC,GAAW,EAAE,QAAa;IAAb,yBAAA,EAAA,aAAa;IACxC,IAAM,KAAK,GAAG,OAAO,OAAO,KAAK,WAAW,IAAI,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IAE3F,OAAO,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC;AAClD,CAAC,CAAC;AAEF,IAAM,YAAY,GAAG,UAAC,QAAgB;IAClC,OAAO,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC;AACzC,CAAC,CAAC;AAEF,IAAM,iBAAiB,GAAG,UAAC,OAAmC;IAAnC,wBAAA,EAAA,YAAmC;IACnD,IAAA,MAAM,GAA4B,OAAO,OAAnC,EAAK,mBAAmB,UAAI,OAAO,EAA1C,UAAgC,CAAD,CAAY;IAEjD,OAAO,EAAC,mBAAmB,qBAAA,EAAE,MAAM,QAAA,EAAC,CAAC;AACzC,CAAC,CAAC;AAEK,IAAM,oBAAoB,GAAG,UAAC,SAAqC;IAArC,0BAAA,EAAA,cAAqC;IACtE,IAAM,KAAK,GAAG,QAAQ,CAAC,iBAAiB,CAAC,CAAC;IAC1C,IAAM,OAAO,GAAiB;QAC1B,UAAU,EAAE,QAAQ,CAAC,kBAAkB,EAAE,KAAK,CAAC;QAC/C,gBAAgB,EAAE,QAAQ,CAAC,eAAe,EAAE,uBAAuB,CAAC;QACpE,QAAQ,EAAE,QAAQ,CAAC,oBAAoB,EAAE,MAAM,CAAC;QAChD,QAAQ,EAAE,QAAQ,CAAC,oBAAoB,EAAE,OAAO,CAAC;KACpD,CAAC;IAEF,IAAI,KAAK,EAAE,CAAC;QACR,OAAO,CAAC,KAAK,GAAG,KAAK,CAAC;IAC1B,CAAC;IAED,6BACO,OAAO,GACP,SAAS,EACd;AACN,CAAC,CAAC;AAjBW,QAAA,oBAAoB,wBAiB/B;AAEW,QAAA,iBAAiB,GAAiB,IAAA,4BAAoB,GAAE,CAAC;AAEtE,IAAM,wBAAwB,GAAG,UAAC,SAAqC;IAArC,0BAAA,EAAA,cAAqC;IACnE,IAAM,WAAW,GAAG,IAAA,4BAAoB,EAAC,SAAS,CAAC,CAAC;IAEpD,MAAM,CAAC,IAAI,CAAC,yBAAiB,CAAC,CAAC,OAAO,CAAC,UAAC,GAAG;QACvC,OAAQ,yBAAyB,CAAC,GAAG,CAAC,CAAC;IAC3C,CAAC,CAAC,CAAC;IACH,MAAM,CAAC,MAAM,CAAC,yBAAiB,EAAE,WAAW,CAAC,CAAC;IAE9C,OAAO,yBAAiB,CAAC;AAC7B,CAAC,CAAC;AAEF,IAAM,kBAAkB,GAAG,UACvB,OAAqB,EACrB,MAA0C,EAC1C,IAAY;IAEZ,IAAI,MAAM,KAAK,KAAK,EAAE,CAAC;QACnB,OAAO;IACX,CAAC;IAED,IAAM,GAAG,GAAG,MAAM,IAAI,OAAO,CAAC,GAAG,CAAC;IAElC,GAAG,CACC,WAAW,EACX,UAAU,EACV,IAAI,EACJ,IAAI,CAAC,SAAS,CAAC;QACX,MAAM,EAAE,OAAO,CAAC,UAAU;QAC1B,IAAI,EAAE,OAAO,CAAC,gBAAgB;QAC9B,QAAQ,EAAE,YAAY,CAAC,OAAO,CAAC,QAAQ,CAAC;QACxC,QAAQ,EAAE,OAAO,CAAC,QAAQ;KAC7B,CAAC,CACL,CAAC;AACN,CAAC,CAAC;AAEF,IAAM,oBAAoB,GAAG,UACzB,OAAqB,EACrB,MAA0C,EAC1C,IAAY;IAEZ,IAAI,MAAM,KAAK,KAAK,EAAE,CAAC;QACnB,OAAO;IACX,CAAC;IAED,IAAM,GAAG,GAAG,MAAM,IAAI,OAAO,CAAC,GAAG,CAAC;IAElC,GAAG,CACC,WAAW,EACX,SAAS,EACT,IAAI,EACJ,IAAI,CAAC,SAAS,CAAC,EAAC,MAAM,EAAE,OAAO,CAAC,UAAU,EAAE,IAAI,EAAE,OAAO,CAAC,gBAAgB,EAAC,CAAC,CAC/E,CAAC;AACN,CAAC,CAAC;AAEK,IAAM,cAAc,GAAG;;;;;yFAAO,OAAmC;;QAAnC,wBAAA,EAAA,YAAmC;;;;oBAC9D,KAAgC,iBAAiB,CAAC,OAAO,CAAC,EAAzD,mBAAmB,yBAAA,EAAE,MAAM,YAAA,CAA+B;oBAC3D,eAAe,GAAG,wBAAwB,CAAC,mBAAmB,CAAC,CAAC;oBAEtE,kBAAkB,CAAC,eAAe,EAAE,MAAM,EAAE,UAAU,CAAC,CAAC;oBACxD,qBAAM,oBAAmB,CAAC,QAAQ,CAAC,IAAI,CAAC,eAAe,CAAC,EAAA;;oBAAxD,SAAwD,CAAC;oBACzD,oBAAoB,CAAC,eAAe,EAAE,MAAM,EAAE,UAAU,CAAC,CAAC;oBAE1D,sBAAO,IAAI,EAAC;;;;CACf,CAAC;AATW,QAAA,cAAc,kBASzB;AAEK,IAAM,wBAAwB,GAAG;;;;;yFACpC,OAAmC;;QAAnC,wBAAA,EAAA,YAAmC;;;;oBAE7B,KAAgC,iBAAiB,CAAC,OAAO,CAAC,EAAzD,mBAAmB,yBAAA,EAAE,MAAM,YAAA,CAA+B;oBAC3D,eAAe,GAAG,wBAAwB,CAAC,mBAAmB,CAAC,CAAC;oBAEtE,kBAAkB,CAAC,eAAe,EAAE,MAAM,EAAE,YAAY,CAAC,CAAC;oBAC1D,qBAAM,oBAAmB,CAAC,QAAQ,CAAC,cAAc,CAAC,eAAe,CAAC,EAAA;;oBAAlE,SAAkE,CAAC;oBACnE,oBAAoB,CAAC,eAAe,EAAE,MAAM,EAAE,YAAY,CAAC,CAAC;oBAE5D,sBAAO,IAAI,EAAC;;;;CACf,CAAC;AAXW,QAAA,wBAAwB,4BAWnC","sourcesContent":["import CouchbaseConnection, {CouchsetArgs} from './connection';\n\nexport type CouchbaseStarterLogger = ((...args: any[]) => void) | false;\n\nexport interface StartCouchbaseOptions extends Partial<CouchsetArgs> {\n    logger?: CouchbaseStarterLogger;\n}\n\nconst envValue = (key: string, fallback = ''): string => {\n    const value = typeof process !== 'undefined' && process.env ? process.env[key] : undefined;\n\n    return value === undefined ? fallback : value;\n};\n\nconst maskPassword = (password: string): string => {\n    return password ? 'xxxxxx' : 'empty';\n};\n\nconst splitStartOptions = (options: StartCouchbaseOptions = {}) => {\n    const {logger, ...connectionOverrides} = options;\n\n    return {connectionOverrides, logger};\n};\n\nexport const getConnectionOptions = (overrides: Partial<CouchsetArgs> = {}): CouchsetArgs => {\n    const proxy = envValue('COUCHBASE_PROXY');\n    const options: CouchsetArgs = {\n        bucketName: envValue('COUCHBASE_BUCKET', 'dev'),\n        connectionString: envValue('COUCHBASE_URL', 'couchbase://localhost'),\n        password: envValue('COUCHBASE_PASSWORD', '1234'),\n        username: envValue('COUCHBASE_USERNAME', 'admin'),\n    };\n\n    if (proxy) {\n        options.proxy = proxy;\n    }\n\n    return {\n        ...options,\n        ...overrides,\n    };\n};\n\nexport const connectionOptions: CouchsetArgs = getConnectionOptions();\n\nconst refreshConnectionOptions = (overrides: Partial<CouchsetArgs> = {}): CouchsetArgs => {\n    const nextOptions = getConnectionOptions(overrides);\n\n    Object.keys(connectionOptions).forEach((key) => {\n        delete (connectionOptions as any)[key];\n    });\n    Object.assign(connectionOptions, nextOptions);\n\n    return connectionOptions;\n};\n\nconst logConnectionStart = (\n    options: CouchsetArgs,\n    logger: CouchbaseStarterLogger | undefined,\n    mode: string\n): void => {\n    if (logger === false) {\n        return;\n    }\n\n    const log = logger || console.log;\n\n    log(\n        'Couchbase',\n        'starting',\n        mode,\n        JSON.stringify({\n            bucket: options.bucketName,\n            host: options.connectionString,\n            password: maskPassword(options.password),\n            username: options.username,\n        })\n    );\n};\n\nconst logConnectionStarted = (\n    options: CouchsetArgs,\n    logger: CouchbaseStarterLogger | undefined,\n    mode: string\n): void => {\n    if (logger === false) {\n        return;\n    }\n\n    const log = logger || console.log;\n\n    log(\n        'Couchbase',\n        'started',\n        mode,\n        JSON.stringify({bucket: options.bucketName, host: options.connectionString})\n    );\n};\n\nexport const startCouchbase = async (options: StartCouchbaseOptions = {}): Promise<boolean> => {\n    const {connectionOverrides, logger} = splitStartOptions(options);\n    const resolvedOptions = refreshConnectionOptions(connectionOverrides);\n\n    logConnectionStart(resolvedOptions, logger, 'standard');\n    await CouchbaseConnection.Instance.init(resolvedOptions);\n    logConnectionStarted(resolvedOptions, logger, 'standard');\n\n    return true;\n};\n\nexport const startCouchbaseServerless = async (\n    options: StartCouchbaseOptions = {}\n): Promise<boolean> => {\n    const {connectionOverrides, logger} = splitStartOptions(options);\n    const resolvedOptions = refreshConnectionOptions(connectionOverrides);\n\n    logConnectionStart(resolvedOptions, logger, 'serverless');\n    await CouchbaseConnection.Instance.initServerless(resolvedOptions);\n    logConnectionStarted(resolvedOptions, logger, 'serverless');\n\n    return true;\n};\n"]}
+{"version":3,"file":"database.js","sourceRoot":"","sources":["../src/database.ts"],"names":[],"mappings":"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","sourcesContent":["import CouchbaseConnection, {CouchsetArgs} from './connection';\n\nexport type CouchbaseStarterLogger = ((...args: any[]) => void) | false;\n\nexport interface StartCouchbaseOptions extends Partial<CouchsetArgs> {\n    logger?: CouchbaseStarterLogger;\n}\n\nconst envValue = (key: string, fallback = ''): string => {\n    const value = typeof process !== 'undefined' && process.env ? process.env[key] : undefined;\n\n    return value === undefined ? fallback : value;\n};\n\nconst databaseUrlError = (reason: string): Error =>\n    new Error(`DB_URL must use couchbase:// or couchbases://user:password@host/bucket: ${reason}`);\n\nconst decodeDatabaseUrlComponent = (value: string, label: string): string => {\n    try {\n        return decodeURIComponent(value);\n    } catch (_error) {\n        throw databaseUrlError(`${label} contains invalid percent-encoding`);\n    }\n};\n\n/**\n * Convert a PostgreSQL-style DB_URL into Couchbase SDK connection settings.\n * The bucket lives in the URL path; it is not part of Couchbase's connection\n * string, which contains only the scheme, host, optional port, and options.\n */\nexport const parseDatabaseUrl = (\n    value: string\n): Pick<CouchsetArgs, 'bucketName' | 'connectionString' | 'password' | 'username'> => {\n    let url: URL;\n\n    try {\n        url = new URL(value);\n    } catch (_error) {\n        throw databaseUrlError('the value is not a valid URL');\n    }\n\n    if (url.protocol !== 'couchbase:' && url.protocol !== 'couchbases:') {\n        throw databaseUrlError(`unsupported protocol ${url.protocol || '(missing)'}`);\n    }\n    if (!url.hostname) {\n        throw databaseUrlError('a host is required');\n    }\n    if (!url.username || !url.password) {\n        throw databaseUrlError('a username and password are required');\n    }\n    if (url.hash) {\n        throw databaseUrlError('fragments are not supported');\n    }\n\n    const bucketName = decodeDatabaseUrlComponent(\n        url.pathname.replace(/^\\//, ''),\n        'the bucket name'\n    );\n    if (!bucketName || bucketName.indexOf('/') !== -1) {\n        throw databaseUrlError('the path must contain exactly one bucket name');\n    }\n\n    return {\n        bucketName,\n        connectionString: `${url.protocol}//${url.host}${url.search}`,\n        password: decodeDatabaseUrlComponent(url.password, 'the password'),\n        username: decodeDatabaseUrlComponent(url.username, 'the username'),\n    };\n};\n\nconst maskPassword = (password: string): string => {\n    return password ? 'xxxxxx' : 'empty';\n};\n\nconst splitStartOptions = (options: StartCouchbaseOptions = {}) => {\n    const {logger, ...connectionOverrides} = options;\n\n    return {connectionOverrides, logger};\n};\n\nexport const getConnectionOptions = (overrides: Partial<CouchsetArgs> = {}): CouchsetArgs => {\n    const proxy = envValue('COUCHBASE_PROXY');\n    const databaseUrl = envValue('DB_URL');\n    const options: CouchsetArgs = {\n        bucketName: envValue('COUCHBASE_BUCKET', 'dev'),\n        connectionString: envValue('COUCHBASE_URL', 'couchbase://localhost'),\n        password: envValue('COUCHBASE_PASSWORD', '1234'),\n        username: envValue('COUCHBASE_USERNAME', 'admin'),\n    };\n\n    if (proxy) {\n        options.proxy = proxy;\n    }\n\n    return {\n        ...options,\n        ...(databaseUrl ? parseDatabaseUrl(databaseUrl) : {}),\n        ...overrides,\n    };\n};\n\nexport const connectionOptions: CouchsetArgs = getConnectionOptions();\n\nconst refreshConnectionOptions = (overrides: Partial<CouchsetArgs> = {}): CouchsetArgs => {\n    const nextOptions = getConnectionOptions(overrides);\n\n    Object.keys(connectionOptions).forEach((key) => {\n        delete (connectionOptions as any)[key];\n    });\n    Object.assign(connectionOptions, nextOptions);\n\n    return connectionOptions;\n};\n\nconst logConnectionStart = (\n    options: CouchsetArgs,\n    logger: CouchbaseStarterLogger | undefined,\n    mode: string\n): void => {\n    if (logger === false) {\n        return;\n    }\n\n    const log = logger || console.log;\n\n    log(\n        'Couchbase',\n        'starting',\n        mode,\n        JSON.stringify({\n            bucket: options.bucketName,\n            host: options.connectionString,\n            password: maskPassword(options.password),\n            username: options.username,\n        })\n    );\n};\n\nconst logConnectionStarted = (\n    options: CouchsetArgs,\n    logger: CouchbaseStarterLogger | undefined,\n    mode: string\n): void => {\n    if (logger === false) {\n        return;\n    }\n\n    const log = logger || console.log;\n\n    log(\n        'Couchbase',\n        'started',\n        mode,\n        JSON.stringify({bucket: options.bucketName, host: options.connectionString})\n    );\n};\n\nexport const startCouchbase = async (options: StartCouchbaseOptions = {}): Promise<boolean> => {\n    const {connectionOverrides, logger} = splitStartOptions(options);\n    const resolvedOptions = refreshConnectionOptions(connectionOverrides);\n\n    logConnectionStart(resolvedOptions, logger, 'standard');\n    await CouchbaseConnection.Instance.init(resolvedOptions);\n    logConnectionStarted(resolvedOptions, logger, 'standard');\n\n    return true;\n};\n\nexport const startCouchbaseServerless = async (\n    options: StartCouchbaseOptions = {}\n): Promise<boolean> => {\n    const {connectionOverrides, logger} = splitStartOptions(options);\n    const resolvedOptions = refreshConnectionOptions(connectionOverrides);\n\n    logConnectionStart(resolvedOptions, logger, 'serverless');\n    await CouchbaseConnection.Instance.initServerless(resolvedOptions);\n    logConnectionStarted(resolvedOptions, logger, 'serverless');\n\n    return true;\n};\n"]}

package/dist/eventing.d.ts

@@ -0,0 +1,179 @@
+import type { EventingFunction, EventingFunctionManager, EventingFunctionSettings, EventingFunctionState } from 'couchbase';
+/** A Couchbase bucket/scope/collection used by an Eventing function. */
+export interface EventingKeyspace {
+    bucket: string;
+    scope?: string;
+    collection?: string;
+}
+/**
+ * A declarative Eventing handler. `name` is logical: CouchSet derives the
+ * physical Couchbase name from the Eventing namespace.
+ */
+export interface EventingDefinition {
+    name: string;
+    code: string;
+    sourceKeyspace: EventingKeyspace;
+    enforceSchema?: boolean;
+    bucketBindings?: EventingFunction['bucketBindings'];
+    urlBindings?: EventingFunction['urlBindings'];
+    constantBindings?: EventingFunction['constantBindings'];
+    settings?: Partial<EventingFunctionSettings>;
+}
+export type EventingFunctionDefinition = EventingDefinition;
+/**
+ * The metadata collection is used only by Couchbase Eventing for checkpoints
+ * and timers. CouchSet never opens it as an application collection or writes
+ * documents to it.
+ */
+export interface EventingOptions {
+    /** Required ownership boundary for physical Couchbase function names. */
+    namespace: string;
+    /** A dedicated collection reserved for Couchbase Eventing metadata. */
+    metadataKeyspace: EventingKeyspace;
+    /** Definitions registered when the control plane is constructed. */
+    definitions?: EventingDefinition[];
+    /** Alias for definitions, useful for manifest-shaped configuration. */
+    functions?: EventingDefinition[];
+    /** Explicit SDK manager injection, primarily for tests or owned clusters. */
+    manager?: EventingFunctionManagerLike;
+    /** Maximum time to wait for Couchbase Eventing lifecycle convergence. */
+    lifecycleTimeoutMs?: number;
+    /** Delay between lifecycle status checks. Defaults to 250ms. */
+    lifecyclePollIntervalMs?: number;
+}
+export interface EventingApplyOptions {
+    /**
+     * Permit source or metadata keyspace changes. Couchbase must undeploy first,
+     * which erases the function's timers and checkpoints.
+     */
+    allowRecreate?: boolean;
+}
+export type EventingOutcomeAction = 'created' | 'updated' | 'resumed' | 'unchanged' | 'pruned' | 'paused' | 'removed' | 'requires-recreate';
+export interface EventingOutcome {
+    action: EventingOutcomeAction;
+    /** Lifecycle operations performed for this function, in order. */
+    actions: EventingOutcomeAction[];
+    name: string;
+    physicalName: string;
+    /** Present whenever undeploying can erase Eventing timers/checkpoints. */
+    timerStateLost?: boolean;
+    message?: string;
+}
+/**
+ * Each status array contains the matching outcome, so callers can inspect a
+ * report directly without parsing text. An update can also be in `paused` and
+ * `resumed`, because that is the safe lifecycle used to perform the update.
+ */
+export interface EventingReport {
+    outcomes: EventingOutcome[];
+    created: EventingOutcome[];
+    updated: EventingOutcome[];
+    resumed: EventingOutcome[];
+    unchanged: EventingOutcome[];
+    pruned: EventingOutcome[];
+    paused: EventingOutcome[];
+    removed: EventingOutcome[];
+    requiresRecreate: EventingOutcome[];
+}
+/** The portion of SDK 4.7's EventingFunctionManager used by CouchSet. */
+export interface EventingFunctionManagerLike {
+    upsertFunction(functionDefinition: EventingFunction): Promise<void>;
+    dropFunction(name: string): Promise<void>;
+    getAllFunctions(): Promise<EventingFunction[]>;
+    deployFunction(name: string): Promise<void>;
+    undeployFunction(name: string): Promise<void>;
+    pauseFunction(name: string): Promise<void>;
+    resumeFunction(name: string): Promise<void>;
+    functionsStatus(): Promise<{
+        functions: EventingFunctionState[];
+    }>;
+}
+/** A minimal client shape that lets Eventing acquire the connected SDK cluster. */
+export interface EventingClient {
+    ready(): Promise<any>;
+    getConnection(): {
+        cluster: {
+            eventingFunctions?: () => EventingFunctionManager;
+        };
+    };
+}
+/**
+ * Declarative Eventing reconciler backed by the SDK 4.7 EventingFunctionManager.
+ * It only manages names starting with its namespace prefix.
+ */
+export declare class Eventing {
+    private readonly definitionsByName;
+    private readonly eventingMetadataKeyspace;
+    private readonly lifecyclePollIntervalMs;
+    private readonly lifecycleTimeoutMs;
+    private readonly prefix;
+    private readonly client?;
+    private readonly explicitManager?;
+    constructor(client: EventingClient | undefined, options: EventingOptions);
+    /** Logical namespace that owns this controller's physical functions. */
+    get namespace(): string;
+    /** A copy of registered, code-only declarations. This performs no I/O. */
+    definitions(): EventingDefinition[];
+    /** Converts a logical declaration name into its Couchbase function name. */
+    physicalName(name: string): string;
+    /** Registers or replaces an in-memory manifest declaration without I/O. */
+    register(definition: EventingDefinition): EventingDefinition;
+    /** Alias for register(), matching the declaration-oriented API vocabulary. */
+    define(definition: EventingDefinition): EventingDefinition;
+    apply(options?: EventingApplyOptions): Promise<EventingReport>;
+    apply(definition: EventingDefinition, options?: EventingApplyOptions): Promise<EventingReport>;
+    /** Temporarily disables one namespace-owned Eventing function. */
+    pause(name: string): Promise<EventingReport>;
+    /**
+     * Intentionally undeploys then deletes one namespace-owned function.
+     * Undeployment erases Couchbase Eventing timers and checkpoints.
+     */
+    remove(name: string): Promise<EventingReport>;
+    private reconcile;
+    private prune;
+    private matches;
+    private sdkDefinition;
+    private metadataKeyspace;
+    private manager;
+    private states;
+    /**
+     * Management requests acknowledge receipt, not necessarily completion. Do
+     * not issue the next incompatible Eventing operation until status confirms
+     * that Couchbase has converged.
+     */
+    private waitForLifecycle;
+    /**
+     * Couchbase Server may turn a paused function into an undeployed function
+     * when upsert persists new code/settings/bindings. Inspect that post-upsert
+     * state rather than assuming resume is legal; deploy is the compatible
+     * activation operation in that case.
+     */
+    private activateAfterUpsert;
+    /**
+     * A live function with no status row is unknown, not safely undeployed.
+     * Poll for a positive row; a known transitional row remains an immediate
+     * blocker so callers do not race an operator's in-progress lifecycle call.
+     */
+    private stableLifecycle;
+    /** Waits for a stable state caused by this controller's own upsert call. */
+    private waitForStableLifecycle;
+    private record;
+    private outcome;
+    private owns;
+    private logicalName;
+    private assertDefinition;
+    private assertLogicalName;
+    private assertStable;
+    private isDefinition;
+    private positiveNumber;
+    private nonNegativeNumber;
+}
+/**
+ * Construct an Eventing control plane from a CouchSet client. The client is
+ * used only to obtain the SDK EventingFunctionManager after `ready()`.
+ */
+export declare const createEventing: (client: EventingClient, options: EventingOptions) => Eventing;
+/** Construct an Eventing control plane around an application-owned SDK manager. */
+export declare const createEventingWithManager: (options: EventingOptions) => Eventing;
+/** A small helper that makes Eventing definitions read as manifest declarations. */
+export declare const defineEventingFunction: (definition: EventingDefinition) => EventingDefinition;