couchset 0.5.0 → 0.5.1

package/README.md

@@ -20,6 +20,7 @@ The additive client-owned primitives—typed definitions, explicit provisioning,
 - [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)
@@ -233,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
 
@@ -313,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":"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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 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":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;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,gBAAgB,GAAG,UAAC,MAAc;IACpC,OAAA,IAAI,KAAK,CAAC,kFAA2E,MAAM,CAAE,CAAC;AAA9F,CAA8F,CAAC;AAEnG,IAAM,0BAA0B,GAAG,UAAC,KAAa,EAAE,KAAa;IAC5D,IAAI,CAAC;QACD,OAAO,kBAAkB,CAAC,KAAK,CAAC,CAAC;IACrC,CAAC;IAAC,OAAO,MAAM,EAAE,CAAC;QACd,MAAM,gBAAgB,CAAC,UAAG,KAAK,uCAAoC,CAAC,CAAC;IACzE,CAAC;AACL,CAAC,CAAC;AAEF;;;;GAIG;AACI,IAAM,gBAAgB,GAAG,UAC5B,KAAa;IAEb,IAAI,GAAQ,CAAC;IAEb,IAAI,CAAC;QACD,GAAG,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC;IACzB,CAAC;IAAC,OAAO,MAAM,EAAE,CAAC;QACd,MAAM,gBAAgB,CAAC,8BAA8B,CAAC,CAAC;IAC3D,CAAC;IAED,IAAI,GAAG,CAAC,QAAQ,KAAK,YAAY,IAAI,GAAG,CAAC,QAAQ,KAAK,aAAa,EAAE,CAAC;QAClE,MAAM,gBAAgB,CAAC,+BAAwB,GAAG,CAAC,QAAQ,IAAI,WAAW,CAAE,CAAC,CAAC;IAClF,CAAC;IACD,IAAI,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC;QAChB,MAAM,gBAAgB,CAAC,oBAAoB,CAAC,CAAC;IACjD,CAAC;IACD,IAAI,CAAC,GAAG,CAAC,QAAQ,IAAI,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC;QACjC,MAAM,gBAAgB,CAAC,sCAAsC,CAAC,CAAC;IACnE,CAAC;IACD,IAAI,GAAG,CAAC,IAAI,EAAE,CAAC;QACX,MAAM,gBAAgB,CAAC,6BAA6B,CAAC,CAAC;IAC1D,CAAC;IAED,IAAM,UAAU,GAAG,0BAA0B,CACzC,GAAG,CAAC,QAAQ,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,EAC/B,iBAAiB,CACpB,CAAC;IACF,IAAI,CAAC,UAAU,IAAI,UAAU,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC;QAChD,MAAM,gBAAgB,CAAC,+CAA+C,CAAC,CAAC;IAC5E,CAAC;IAED,OAAO;QACH,UAAU,YAAA;QACV,gBAAgB,EAAE,UAAG,GAAG,CAAC,QAAQ,eAAK,GAAG,CAAC,IAAI,SAAG,GAAG,CAAC,MAAM,CAAE;QAC7D,QAAQ,EAAE,0BAA0B,CAAC,GAAG,CAAC,QAAQ,EAAE,cAAc,CAAC;QAClE,QAAQ,EAAE,0BAA0B,CAAC,GAAG,CAAC,QAAQ,EAAE,cAAc,CAAC;KACrE,CAAC;AACN,CAAC,CAAC;AAtCW,QAAA,gBAAgB,oBAsC3B;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,WAAW,GAAG,QAAQ,CAAC,QAAQ,CAAC,CAAC;IACvC,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,sCACO,OAAO,GACP,CAAC,WAAW,CAAC,CAAC,CAAC,IAAA,wBAAgB,EAAC,WAAW,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,GAClD,SAAS,EACd;AACN,CAAC,CAAC;AAnBW,QAAA,oBAAoB,wBAmB/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 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/model/include.d.ts

@@ -2,22 +2,47 @@ import { LogicalWhereExpr, SortType } from '../query/interface/query.types';
 export type IncludeType = 'join' | 'leftJoin' | 'nest' | 'leftNest';
 export interface IncludeDefinition {
     as: string;
+    /** ANSI predicate; mutually exclusive with key/keys. */
+    on?: JoinPredicate;
+    /** Explicit trusted SQL++ escape hatch. Values still use positional placeholders. */
+    onRaw?: {
+        sql: string;
+        values?: readonly unknown[];
+    };
+    /** Top-level fields retained from the related document. */
+    select?: readonly string[];
     key?: string;
     keys?: string;
     keyspace?: string;
     model?: string | {
         keyspace: () => string;
+        parse?: <T>(data: T) => T;
+        parseProjection?: <T>(data: T) => T;
     };
     type?: IncludeType;
     optional?: boolean;
 }
+/** A field operand is explicit; bare strings are always parameter values. */
+export interface JoinField {
+    readonly $field: string;
+}
+export type JoinPredicate = {
+    $and: readonly JoinPredicate[];
+} | {
+    $or: readonly JoinPredicate[];
+} | {
+    left: JoinField;
+    op: '$eq' | '$neq' | '$gt' | '$gte' | '$lt' | '$lte';
+    right: unknown;
+};
+export declare const joinField: (path: string) => JoinField;
 export interface IncludedSelectionQueryArgs {
     keyspace: string;
     collectionName: string;
-    select?: any[] | string;
+    select?: readonly any[] | string;
     where?: LogicalWhereExpr;
     orderBy?: Record<string, SortType>;
-    include?: IncludeDefinition[];
+    include?: readonly IncludeDefinition[];
     limit?: number;
     page?: number;
     offset?: number;
@@ -29,5 +54,13 @@ export interface IncludedSelectionQuery {
     selectAll: boolean;
     resultKey?: string;
 }
-export declare const buildIncludeClauses: (keyspace: string, include?: IncludeDefinition[], sourceAlias?: string) => string;
+declare class IncludeParameterStore {
+    parameters: Record<string, any>;
+    private index;
+    add(value: any): string;
+    set(key: string, value: any): string;
+}
+export declare const includeOperator: (include: IncludeDefinition) => string;
+export declare const buildIncludeClauses: (keyspace: string, include?: readonly IncludeDefinition[], sourceAlias?: string, store?: IncludeParameterStore) => string;
 export declare const buildIncludedSelectionQuery: (args: IncludedSelectionQueryArgs) => IncludedSelectionQuery;
+export {};

package/dist/model/include.js

@@ -25,10 +25,16 @@ var __spreadArray = (this && this.__spreadArray) || function (to, from, pack) {
     return to.concat(ar || Array.prototype.slice.call(from));
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.buildIncludedSelectionQuery = exports.buildIncludeClauses = void 0;
-var helpers_1 = require("../query/helpers");
-var utils_1 = require("../query/utils");
+exports.buildIncludedSelectionQuery = exports.buildIncludeClauses = exports.includeOperator = exports.joinField = void 0;
 var keyspace_1 = require("./keyspace");
+var joinField = function (path) { return ({ $field: path }); };
+exports.joinField = joinField;
+var identifier = function (name) {
+    if (!name || name.indexOf('\0') !== -1)
+        throw new Error('Empty or invalid identifier');
+    return (0, keyspace_1.escapeIdentifier)(name);
+};
+var fieldPath = function (path) { return path.split('.').map(identifier).join('.'); };
 var comparisonOperators = {
     $eq: '=',
     $neq: '!=',
@@ -74,26 +80,30 @@ var IncludeParameterStore = /** @class */ (function () {
     };
     return IncludeParameterStore;
 }());
-var safeAlias = function (alias) {
-    return /^[A-Za-z_][A-Za-z0-9_]*$/.test(alias) ? alias : (0, keyspace_1.escapeIdentifier)(alias);
+var safeAlias = identifier;
+var safeKeyspace = function (target) {
+    // Accept existing model.keyspace() output and simple dotted identifiers, never expressions.
+    var token = '(?:`(?:[^`]|``)+`|[A-Za-z_][A-Za-z0-9_-]*)';
+    if (!new RegExp("^(?:default:)?".concat(token, "(?:\\.").concat(token, "){0,2}$")).test(target))
+        throw new Error('Invalid include keyspace; use a model or identifier path');
+    return target.replace(/[A-Za-z_][A-Za-z0-9_-]*|`(?:[^`]|``)+`/g, function (part, offset) {
+        return target.slice(offset + part.length, offset + part.length + 1) === ':' || part.startsWith('`')
+            ? part
+            : identifier(part);
+    });
 };
 var keyspaceFromInclude = function (include, defaultKeyspace) {
-    if (include.keyspace) {
-        return include.keyspace;
-    }
-    if (typeof include.model === 'string') {
-        return include.model;
-    }
-    if (include.model) {
-        return include.model.keyspace();
-    }
-    return defaultKeyspace;
+    var _a;
+    var target = include.keyspace ||
+        (typeof include.model === 'string' ? include.model : (_a = include.model) === null || _a === void 0 ? void 0 : _a.keyspace()) ||
+        defaultKeyspace;
+    return safeKeyspace(target);
 };
 var sourceField = function (field, sourceAlias) {
-    if (field.indexOf("".concat(sourceAlias, ".")) === 0) {
-        return field;
-    }
-    return "".concat(sourceAlias, ".").concat((0, utils_1.escapeReservedWords)(field));
+    var prefix = "".concat(sourceAlias, ".");
+    return field.indexOf(prefix) === 0
+        ? fieldPath(field)
+        : "".concat(identifier(sourceAlias), ".").concat(fieldPath(field));
 };
 var includeOperator = function (include) {
     if (include.type === 'leftNest') {
@@ -105,22 +115,92 @@ var includeOperator = function (include) {
     if (include.type === 'leftJoin') {
         return 'LEFT JOIN';
     }
+    if (include.type === 'join') {
+        return include.optional ? 'LEFT JOIN' : 'JOIN';
+    }
     if (include.keys) {
         return include.optional ? 'LEFT NEST' : 'NEST';
     }
     return include.optional ? 'LEFT JOIN' : 'JOIN';
 };
-var buildIncludeClauses = function (keyspace, include, sourceAlias) {
+exports.includeOperator = includeOperator;
+var predicateExpr = function (predicate, store, aliases) {
+    if (!predicate || typeof predicate !== 'object')
+        throw new Error('Invalid ON predicate');
+    var keys = Object.keys(predicate);
+    if (keys.length === 1 && (keys[0] === '$and' || keys[0] === '$or')) {
+        var children = predicate[keys[0]];
+        if (!Array.isArray(children) || !children.length)
+            throw new Error('ON logical groups must be nonempty');
+        return "(".concat(children
+            .map(function (child) { return predicateExpr(child, store, aliases); })
+            .join(keys[0] === '$and' ? ' AND ' : ' OR '), ")");
+    }
+    var comparison = predicate;
+    if (keys.length !== 3 ||
+        !keys.includes('left') ||
+        !keys.includes('right') ||
+        !keys.includes('op') ||
+        !Object.prototype.hasOwnProperty.call(comparisonOperators, comparison.op))
+        throw new Error('Unsupported ON comparison');
+    var reference = function (value) {
+        if (!value || typeof value.$field !== 'string' || Object.keys(value).length !== 1)
+            throw new Error('Expected explicit joinField reference');
+        var parts = value.$field.split('.');
+        if (parts.length < 2 || !aliases.has(parts[0]))
+            throw new Error("Unknown ON alias: ".concat(parts[0]));
+        return fieldPath(value.$field);
+    };
+    var right = comparison.right;
+    return "".concat(reference(comparison.left), " ").concat(comparisonOperators[comparison.op], " ").concat(right && typeof right === 'object' && Object.prototype.hasOwnProperty.call(right, '$field')
+        ? reference(right)
+        : store.add(right));
+};
+var buildIncludeClauses = function (keyspace, include, sourceAlias, store) {
     if (include === void 0) { include = []; }
     if (sourceAlias === void 0) { sourceAlias = 'doc'; }
+    if (store === void 0) { store = new IncludeParameterStore(); }
+    var aliases = new Set([sourceAlias]);
+    var reservedAliases = new Set(['__cs_root', '__proto__', 'constructor', 'prototype']);
+    var modes = new Set(include.map(function (item) { return (item.on || item.onRaw ? 'ansi' : 'keys'); }));
+    // Couchbase does not permit mixing lookup and ANSI joins in the same FROM clause.
+    if (modes.size > 1)
+        throw new Error('Cannot mix ANSI ON and ON KEYS includes');
     return include
         .map(function (item) {
-        var key = item.key || item.keys;
-        if (!key) {
-            throw new Error("include ".concat(item.as, " requires key or keys"));
+        if (aliases.has(item.as) || reservedAliases.has(item.as))
+            throw new Error("Duplicate or reserved include alias: ".concat(item.as));
+        aliases.add(item.as);
+        if (item.type && !['join', 'leftJoin', 'nest', 'leftNest'].includes(item.type))
+            throw new Error('Unsupported include type');
+        if ([
+            item.key !== undefined,
+            item.keys !== undefined,
+            item.on !== undefined,
+            item.onRaw !== undefined,
+        ].filter(Boolean).length !== 1) {
+            throw new Error("include ".concat(item.as, " requires exactly one of key, keys, on, onRaw"));
+        }
+        var condition;
+        if (item.on)
+            condition = "ON ".concat(predicateExpr(item.on, store, aliases));
+        else if (item.onRaw) {
+            var values_1 = item.onRaw.values || [];
+            var index_1 = 0;
+            if (!item.onRaw.sql.trim())
+                throw new Error('onRaw requires SQL');
+            var sql = item.onRaw.sql.replace(/\?/g, function () {
+                if (index_1 >= values_1.length)
+                    throw new Error('onRaw placeholder/value mismatch');
+                return store.add(values_1[index_1++]);
+            });
+            if (index_1 !== values_1.length)
+                throw new Error('onRaw placeholder/value mismatch');
+            condition = "ON (".concat(sql, ")");
         }
-        var alias = safeAlias(item.as);
-        return "".concat(includeOperator(item), " ").concat(keyspaceFromInclude(item, keyspace), " AS ").concat(alias, " ON KEYS ").concat(sourceField(key, sourceAlias));
+        else
+            condition = "ON KEYS ".concat(sourceField((item.key || item.keys), sourceAlias));
+        return "".concat((0, exports.includeOperator)(item), " ").concat(keyspaceFromInclude(item, keyspace), " AS ").concat(safeAlias(item.as), " ").concat(condition);
     })
         .join(' ');
 };
@@ -201,46 +281,71 @@ var buildWhereExpr = function (expr, store, sourceAlias) {
 var buildOrderByExpr = function (orderBy, sourceAlias) {
     return orderBy
         ? " ORDER BY ".concat(Object.keys(orderBy)
-            .map(function (field) { return "".concat(sourceField(field, sourceAlias), " ").concat(orderBy[field]); })
+            .map(function (field) {
+            if (!['ASC', 'DESC'].includes(orderBy[field]))
+                throw new Error('Unsupported order direction');
+            return "".concat(sourceField(field, sourceAlias), " ").concat(orderBy[field]);
+        })
             .join(','))
         : '';
 };
+var selectedObject = function (alias, fields) {
+    if (!fields)
+        return identifier(alias);
+    if (!fields.length || new Set(fields).size !== fields.length)
+        throw new Error('Projection must contain distinct fields');
+    return "{".concat(fields
+        .map(function (field) {
+        if (field.includes('.'))
+            throw new Error('Include projections support top-level fields only');
+        return "".concat(JSON.stringify(field), ": ").concat(identifier(alias), ".").concat(identifier(field));
+    })
+        .join(', '), "}");
+};
 var buildSelectExpr = function (select, include, sourceAlias) {
-    if (!select || select === '*') {
-        var aliases = include.map(function (item) { return safeAlias(item.as); });
-        var mergeObject = aliases.map(function (alias) { return "".concat(JSON.stringify(alias), ": ").concat(alias); }).join(',');
+    var all = !select || select === '*';
+    var structured = Array.isArray(select) &&
+        select.every(function (field) { return typeof field === 'string' && !field.includes('.'); });
+    var root = all
+        ? identifier(sourceAlias)
+        : structured
+            ? selectedObject(sourceAlias, select)
+            : undefined;
+    var relations = include.map(function (item) {
+        var alias = identifier(item.as);
+        if (!item.select)
+            return "".concat(alias, " AS ").concat(alias);
+        var object = selectedObject('__cs_item', item.select);
+        var expression = (0, exports.includeOperator)(item).includes('NEST')
+            ? "ARRAY ".concat(object, " FOR ").concat(identifier('__cs_item'), " IN ").concat(alias, " END")
+            : "CASE WHEN ".concat(alias, " IS MISSING THEN MISSING WHEN ").concat(alias, " IS NULL THEN NULL ELSE ").concat(selectedObject(item.as, item.select), " END");
+        return "".concat(expression, " AS ").concat(alias);
+    });
+    if (structured &&
+        select.some(function (field) { return include.some(function (item) { return item.as === field; }); }))
+        throw new Error('Include alias conflicts with projected root field');
+    if (root)
         return {
-            expr: "OBJECT_CONCAT(".concat(sourceAlias, ", {").concat(mergeObject, "}) AS ").concat(sourceAlias),
-            selectAll: true,
-            resultKey: sourceAlias,
+            expr: __spreadArray(["".concat(root, " AS __cs_root")], __read(relations), false).join(', '),
+            selectAll: all,
+            resultKey: '__cs_root',
         };
-    }
-    var includeSelect = include.map(function (item) {
-        var alias = safeAlias(item.as);
-        return "".concat(alias, " AS ").concat(alias);
-    });
-    if (typeof select === 'string') {
-        return { expr: __spreadArray([select], __read(includeSelect), false).join(','), selectAll: false };
-    }
-    var modelSelect = select.map(function (item) {
-        return typeof item === 'string'
-            ? sourceField(item, sourceAlias)
-            : (0, helpers_1.buildSelectArrayExpr)([item]);
-    });
-    return { expr: __spreadArray(__spreadArray([], __read(modelSelect), false), __read(includeSelect), false).join(','), selectAll: false };
+    throw new Error('Includes support only * or top-level field-array projections; use queryRows for arbitrary SQL++ projections');
 };
 var buildIncludedSelectionQuery = function (args) {
-    var sourceAlias = safeAlias(args.sourceAlias || 'doc');
+    var sourceAlias = args.sourceAlias || 'doc';
+    if (sourceAlias === '__cs_root')
+        throw new Error('Reserved source alias');
     var include = args.include || [];
     var store = new IncludeParameterStore();
     var limit = typeof args.limit === 'number' ? args.limit : 10;
     var page = typeof args.page === 'number' ? args.page : 0;
     var offset = typeof args.offset === 'number' ? args.offset : page * limit;
     var _a = buildSelectExpr(args.select, include, sourceAlias), expr = _a.expr, selectAll = _a.selectAll, resultKey = _a.resultKey;
-    var joins = (0, exports.buildIncludeClauses)(args.keyspace, include, sourceAlias);
+    var joins = (0, exports.buildIncludeClauses)(args.keyspace, include, sourceAlias, store);
     var limitExpr = " LIMIT ".concat(store.set('cs_limit', limit), " OFFSET ").concat(store.set('cs_offset', offset));
     return {
-        query: "SELECT ".concat(expr, " FROM ").concat(args.keyspace, " AS ").concat(sourceAlias, " ").concat(joins).concat(buildWhereExpr(args.where, store, sourceAlias)).concat(buildOrderByExpr(args.orderBy, sourceAlias)).concat(limitExpr),
+        query: "SELECT ".concat(expr, " FROM ").concat(args.keyspace, " AS ").concat(identifier(sourceAlias), " ").concat(joins).concat(buildWhereExpr(args.where, store, sourceAlias)).concat(buildOrderByExpr(args.orderBy, sourceAlias)).concat(limitExpr),
         parameters: store.parameters,
         resultKey: resultKey,
         selectAll: selectAll,