couchset 0.5.0 → 0.5.2

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":"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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/model/field-path.d.ts

@@ -0,0 +1,8 @@
+interface PathSegment {
+    name: string;
+    selectors: string[];
+}
+/** Parse data paths, not SQL expressions. Backticks delimit literal field names. */
+export declare const parseFieldPath: (path: string) => PathSegment[];
+export declare const renderFieldPath: (segments: readonly PathSegment[]) => string;
+export {};

package/dist/model/field-path.js

@@ -0,0 +1,70 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderFieldPath = exports.parseFieldPath = void 0;
+var keyspace_1 = require("./keyspace");
+/** Parse data paths, not SQL expressions. Backticks delimit literal field names. */
+var parseFieldPath = function (path) {
+    var invalid = function () {
+        throw new Error("Invalid field path: ".concat(JSON.stringify(path)));
+    };
+    if (typeof path !== 'string' || !path.length || /[\x00-\x1f\x7f]/.test(path))
+        invalid();
+    var segments = [];
+    var position = 0;
+    while (position < path.length) {
+        var name_1 = '';
+        if (path[position] === '`') {
+            position++;
+            var closed_1 = false;
+            while (position < path.length) {
+                var character = path[position++];
+                if (character !== '`')
+                    name_1 += character;
+                else if (path[position] === '`') {
+                    name_1 += '`';
+                    position++;
+                }
+                else {
+                    closed_1 = true;
+                    break;
+                }
+            }
+            if (!closed_1)
+                invalid();
+        }
+        else {
+            while (position < path.length && !'.[]'.includes(path[position])) {
+                name_1 += path[position++];
+            }
+        }
+        if (!name_1)
+            invalid();
+        var selectors = [];
+        while (path[position] === '[') {
+            var end = path.indexOf(']', position + 1);
+            if (end < 0)
+                invalid();
+            var selector = path.slice(position + 1, end);
+            if (selector !== '*' &&
+                (!/^(0|[1-9]\d*)$/.test(selector) || !Number.isSafeInteger(Number(selector))))
+                invalid();
+            selectors.push("[".concat(selector, "]"));
+            position = end + 1;
+        }
+        segments.push({ name: name_1, selectors: selectors });
+        if (position === path.length)
+            break;
+        if (path[position++] !== '.' || position === path.length)
+            invalid();
+    }
+    return segments;
+};
+exports.parseFieldPath = parseFieldPath;
+var renderFieldPath = function (segments) {
+    return segments.map(function (_a) {
+        var name = _a.name, selectors = _a.selectors;
+        return (0, keyspace_1.escapeIdentifier)(name) + selectors.join('');
+    }).join('.');
+};
+exports.renderFieldPath = renderFieldPath;
+//# sourceMappingURL=field-path.js.map

package/dist/model/field-path.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"field-path.js","sourceRoot":"","sources":["../../src/model/field-path.ts"],"names":[],"mappings":"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","sourcesContent":["import {escapeIdentifier} from './keyspace';\n\ninterface PathSegment {\n    name: string;\n    selectors: string[];\n}\n\n/** Parse data paths, not SQL expressions. Backticks delimit literal field names. */\nexport const parseFieldPath = (path: string): PathSegment[] => {\n    const invalid = (): never => {\n        throw new Error(`Invalid field path: ${JSON.stringify(path)}`);\n    };\n    if (typeof path !== 'string' || !path.length || /[\\x00-\\x1f\\x7f]/.test(path)) invalid();\n    const segments: PathSegment[] = [];\n    let position = 0;\n    while (position < path.length) {\n        let name = '';\n        if (path[position] === '`') {\n            position++;\n            let closed = false;\n            while (position < path.length) {\n                const character = path[position++];\n                if (character !== '`') name += character;\n                else if (path[position] === '`') {\n                    name += '`';\n                    position++;\n                } else {\n                    closed = true;\n                    break;\n                }\n            }\n            if (!closed) invalid();\n        } else {\n            while (position < path.length && !'.[]'.includes(path[position])) {\n                name += path[position++];\n            }\n        }\n        if (!name) invalid();\n        const selectors: string[] = [];\n        while (path[position] === '[') {\n            const end = path.indexOf(']', position + 1);\n            if (end < 0) invalid();\n            const selector = path.slice(position + 1, end);\n            if (\n                selector !== '*' &&\n                (!/^(0|[1-9]\\d*)$/.test(selector) || !Number.isSafeInteger(Number(selector)))\n            )\n                invalid();\n            selectors.push(`[${selector}]`);\n            position = end + 1;\n        }\n        segments.push({name, selectors});\n        if (position === path.length) break;\n        if (path[position++] !== '.' || position === path.length) invalid();\n    }\n    return segments;\n};\n\nexport const renderFieldPath = (segments: readonly PathSegment[]): string =>\n    segments.map(({name, selectors}) => escapeIdentifier(name) + selectors.join('')).join('.');\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 {};