couchset 0.5.0 → 0.5.1

package/dist/next.types.js

@@ -1,6 +1,41 @@
 "use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __generator = (this && this.__generator) || function (thisArg, body) {
+    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g = Object.create((typeof Iterator === "function" ? Iterator : Object).prototype);
+    return g.next = verb(0), g["throw"] = verb(1), g["return"] = verb(2), typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
+    function verb(n) { return function (v) { return step([n, v]); }; }
+    function step(op) {
+        if (f) throw new TypeError("Generator is already executing.");
+        while (g && (g = 0, op[0] && (_ = 0)), _) try {
+            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
+            if (y = 0, t) op = [op[0] & 2, t.value];
+            switch (op[0]) {
+                case 0: case 1: t = op; break;
+                case 4: _.label++; return { value: op[1], done: false };
+                case 5: _.label++; y = op[1]; op = [0]; continue;
+                case 7: op = _.ops.pop(); _.trys.pop(); continue;
+                default:
+                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) { _ = 0; continue; }
+                    if (op[0] === 3 && (!t || (op[1] > t[0] && op[1] < t[3]))) { _.label = op[1]; break; }
+                    if (op[0] === 6 && _.label < t[1]) { _.label = t[1]; t = op; break; }
+                    if (t && _.label < t[2]) { _.label = t[2]; _.ops.push(op); break; }
+                    if (t[2]) _.ops.pop();
+                    _.trys.pop(); continue;
+            }
+            op = body.call(thisArg, _);
+        } catch (e) { op = [6, e]; y = 0; } finally { f = t = 0; }
+        if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
+    }
+};
 Object.defineProperty(exports, "__esModule", { value: true });
-/* eslint-disable @typescript-eslint/ban-ts-comment -- this file verifies compiler errors. */
 var next_1 = require("./next");
 var booleanCodec = {
     fromDatabase: function (value) { return value === 'true'; },
@@ -35,4 +70,117 @@ var booleanCodec = {
     ],
     name: 'InvalidTypedSession',
 });
+// Model read inference is based on the bound model, literal aliases, kinds and projections.
+var client = (0, next_1.createCouchsetClient)();
+var sessions = client.model((0, next_1.defineModel)({ name: 'ReadSession', codecs: { expiresAt: next_1.dateCodec } }));
+var profiles = client.model((0, next_1.defineModel)({
+    name: 'ReadProfile',
+    codecs: { birthday: next_1.dateCodec },
+}));
+function inferredReads() {
+    return __awaiter(this, void 0, void 0, function () {
+        var rows, expiry, birthday, friends, selected, selectedDate, raw, keyJoined, name, keyedNest, people, scoped, stillDate;
+        var _a;
+        return __generator(this, function (_b) {
+            switch (_b.label) {
+                case 0: return [4 /*yield*/, sessions.findMany({
+                        include: [
+                            {
+                                as: 'creator',
+                                model: profiles,
+                                type: 'leftJoin',
+                                on: { left: (0, next_1.joinField)('creator.id'), op: '$eq', right: (0, next_1.joinField)('doc.userId') },
+                            },
+                            {
+                                as: 'friends',
+                                model: profiles,
+                                type: 'leftNest',
+                                on: { left: (0, next_1.joinField)('friends.id'), op: '$eq', right: 'literal.id' },
+                                select: ['name'],
+                            },
+                        ],
+                    })];
+                case 1:
+                    rows = _b.sent();
+                    expiry = rows[0].expiresAt;
+                    birthday = (_a = rows[0].creator) === null || _a === void 0 ? void 0 : _a.birthday;
+                    friends = rows[0].friends;
+                    // @ts-expect-error JOIN is an object, not a relation array.
+                    rows[0].creator.map(function () { return 1; });
+                    // @ts-expect-error Related projection excludes birthday.
+                    rows[0].friends[0].birthday;
+                    // @ts-expect-error Related fields come from its model.
+                    rows[0].creator.nonexistent;
+                    return [4 /*yield*/, sessions.findOne({ select: ['expiresAt'] })];
+                case 2:
+                    selected = _b.sent();
+                    selectedDate = selected.expiresAt;
+                    // @ts-expect-error Unselected root field must not be claimed.
+                    selected.userId;
+                    // @ts-expect-error Cannot assert an unrelated result by supplying a row generic.
+                    sessions.findMany();
+                    // @ts-expect-error Include aliases must not overwrite known root fields.
+                    sessions.findMany({ include: [{ as: 'userId', model: profiles, key: 'userId' }] });
+                    return [4 /*yield*/, sessions.findMany({ select: 'RAW COUNT(1)' })];
+                case 3:
+                    raw = _b.sent();
+                    // @ts-expect-error Arbitrary SQL++ projections have unknown shape.
+                    raw[0].expiresAt;
+                    return [4 /*yield*/, sessions.findMany({
+                            include: [{ as: 'profile', model: profiles, key: 'userId' }],
+                        })];
+                case 4:
+                    keyJoined = _b.sent();
+                    name = keyJoined[0].profile.name;
+                    return [4 /*yield*/, sessions.page({
+                            include: [{ as: 'people', model: profiles, keys: 'userId' }],
+                        })];
+                case 5:
+                    keyedNest = _b.sent();
+                    people = keyedNest.items[0].people;
+                    return [4 /*yield*/, sessions.withDeleted().findOne()];
+                case 6:
+                    scoped = _b.sent();
+                    stillDate = scoped.expiresAt;
+                    return [2 /*return*/, { expiry: expiry, birthday: birthday, friends: friends, selectedDate: selectedDate, name: name, people: people, stillDate: stillDate }];
+            }
+        });
+    });
+}
+function conservativeInputs(args, optional) {
+    return __awaiter(this, void 0, void 0, function () {
+        var dynamic, optionalRows, optionalKey, literalRows, leftKey, innerRows, innerKey;
+        return __generator(this, function (_a) {
+            switch (_a.label) {
+                case 0: return [4 /*yield*/, sessions.findMany(args)];
+                case 1:
+                    dynamic = _a.sent();
+                    // @ts-expect-error Broad read args can contain arbitrary projections.
+                    dynamic[0].expiresAt;
+                    return [4 /*yield*/, sessions.findMany({
+                            include: [{ as: 'profile', model: profiles, key: 'userId', optional: optional }],
+                        })];
+                case 2:
+                    optionalRows = _a.sent();
+                    optionalKey = true;
+                    return [4 /*yield*/, sessions.findMany({
+                            include: [{ as: 'profile', model: profiles, type: 'leftJoin', key: 'userId' }],
+                        })];
+                case 3:
+                    literalRows = _a.sent();
+                    leftKey = true;
+                    return [4 /*yield*/, sessions.findMany({
+                            include: [{ as: 'profile', model: profiles, type: 'join', key: 'userId' }],
+                        })];
+                case 4:
+                    innerRows = _a.sent();
+                    innerKey = false;
+                    return [2 /*return*/, { optionalKey: optionalKey, leftKey: leftKey, innerKey: innerKey }];
+            }
+        });
+    });
+}
+// Keep compile-only cases referenced without executing reads.
+void inferredReads;
+void conservativeInputs;
 //# sourceMappingURL=next.types.js.map

package/dist/next.types.js.map

@@ -1 +1 @@
-{"version":3,"file":"next.types.js","sourceRoot":"","sources":["../src/next.types.ts"],"names":[],"mappings":";;AAAA,6FAA6F;AAC7F,+BAA0D;AAO1D,IAAM,YAAY,GAAgC;IAC9C,YAAY,EAAE,UAAC,KAAK,IAAK,OAAA,KAAK,KAAK,MAAM,EAAhB,CAAgB;IACzC,UAAU,EAAE,UAAC,KAAK,IAAK,OAAA,MAAM,CAAC,KAAK,CAAC,EAAb,CAAa;CACvC,CAAC;AAEF,IAAA,kBAAW,EAAe;IACtB,MAAM,EAAE,EAAC,SAAS,EAAE,gBAAS,EAAC;IAC9B,OAAO,EAAE,CAAC,EAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,EAAE,IAAI,EAAE,wBAAwB,EAAC,CAAC;IAC/D,IAAI,EAAE,cAAc;CACvB,CAAC,CAAC;AAEH,IAAA,kBAAW,EAAe;IACtB,MAAM,EAAE;QACJ,wEAAwE;QACxE,OAAO,EAAE,gBAAS;KACrB;IACD,IAAI,EAAE,iBAAiB;CAC1B,CAAC,CAAC;AAEH,IAAA,kBAAW,EAAe;IACtB,MAAM,EAAE;QACJ,mEAAmE;QACnE,SAAS,EAAE,YAAY;KAC1B;IACD,IAAI,EAAE,mBAAmB;CAC5B,CAAC,CAAC;AAEH,IAAA,kBAAW,EAAe;IACtB,OAAO,EAAE;QACL;YACI,gFAAgF;YAChF,MAAM,EAAE,CAAC,SAAS,CAAC;YACnB,IAAI,EAAE,mBAAmB;SAC5B;KACJ;IACD,IAAI,EAAE,qBAAqB;CAC9B,CAAC,CAAC","sourcesContent":["/* eslint-disable @typescript-eslint/ban-ts-comment -- this file verifies compiler errors. */\nimport {dateCodec, defineModel, FieldCodec} from './next';\n\ninterface TypedSession {\n    expiresAt: Date;\n    userId: string;\n}\n\nconst booleanCodec: FieldCodec<boolean, string> = {\n    fromDatabase: (value) => value === 'true',\n    toDatabase: (value) => String(value),\n};\n\ndefineModel<TypedSession>({\n    codecs: {expiresAt: dateCodec},\n    indexes: [{fields: ['userId'], name: 'idx_typed_session_user'}],\n    name: 'TypedSession',\n});\n\ndefineModel<TypedSession>({\n    codecs: {\n        // @ts-expect-error Codec keys must exist on the declared document type.\n        missing: dateCodec,\n    },\n    name: 'InvalidCodecKey',\n});\n\ndefineModel<TypedSession>({\n    codecs: {\n        // @ts-expect-error Codec input must match the declared field type.\n        expiresAt: booleanCodec,\n    },\n    name: 'InvalidCodecValue',\n});\n\ndefineModel<TypedSession>({\n    indexes: [\n        {\n            // @ts-expect-error Declared index fields are checked against the document type.\n            fields: ['missing'],\n            name: 'idx_invalid_field',\n        },\n    ],\n    name: 'InvalidTypedSession',\n});\n"]}
+{"version":3,"file":"next.types.js","sourceRoot":"","sources":["../src/next.types.ts"],"names":[],"mappings":"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","sourcesContent":["/* eslint-disable @typescript-eslint/ban-ts-comment -- this file verifies compiler errors. */\nimport type {AutoModelFields, ModelReadArgs} from './model';\nimport {createCouchsetClient, dateCodec, defineModel, FieldCodec, joinField} from './next';\n\ninterface TypedSession {\n    expiresAt: Date;\n    userId: string;\n}\n\nconst booleanCodec: FieldCodec<boolean, string> = {\n    fromDatabase: (value) => value === 'true',\n    toDatabase: (value) => String(value),\n};\n\ndefineModel<TypedSession>({\n    codecs: {expiresAt: dateCodec},\n    indexes: [{fields: ['userId'], name: 'idx_typed_session_user'}],\n    name: 'TypedSession',\n});\n\ndefineModel<TypedSession>({\n    codecs: {\n        // @ts-expect-error Codec keys must exist on the declared document type.\n        missing: dateCodec,\n    },\n    name: 'InvalidCodecKey',\n});\n\ndefineModel<TypedSession>({\n    codecs: {\n        // @ts-expect-error Codec input must match the declared field type.\n        expiresAt: booleanCodec,\n    },\n    name: 'InvalidCodecValue',\n});\n\ndefineModel<TypedSession>({\n    indexes: [\n        {\n            // @ts-expect-error Declared index fields are checked against the document type.\n            fields: ['missing'],\n            name: 'idx_invalid_field',\n        },\n    ],\n    name: 'InvalidTypedSession',\n});\n\n// Model read inference is based on the bound model, literal aliases, kinds and projections.\nconst client = createCouchsetClient();\nconst sessions = client.model(\n    defineModel<TypedSession>({name: 'ReadSession', codecs: {expiresAt: dateCodec}})\n);\nconst profiles = client.model(\n    defineModel<{name: string; birthday: Date}>({\n        name: 'ReadProfile',\n        codecs: {birthday: dateCodec},\n    })\n);\nasync function inferredReads() {\n    const rows = await sessions.findMany({\n        include: [\n            {\n                as: 'creator',\n                model: profiles,\n                type: 'leftJoin',\n                on: {left: joinField('creator.id'), op: '$eq', right: joinField('doc.userId')},\n            },\n            {\n                as: 'friends',\n                model: profiles,\n                type: 'leftNest',\n                on: {left: joinField('friends.id'), op: '$eq', right: 'literal.id'},\n                select: ['name'],\n            },\n        ],\n    });\n    const expiry: Date = rows[0].expiresAt;\n    const birthday: Date | undefined = rows[0].creator?.birthday;\n    const friends: Array<{name: string}> = rows[0].friends;\n    // @ts-expect-error JOIN is an object, not a relation array.\n    rows[0].creator.map(() => 1);\n    // @ts-expect-error Related projection excludes birthday.\n    rows[0].friends[0].birthday;\n    // @ts-expect-error Related fields come from its model.\n    rows[0].creator.nonexistent;\n    const selected = await sessions.findOne({select: ['expiresAt']});\n    const selectedDate: Date = selected.expiresAt;\n    // @ts-expect-error Unselected root field must not be claimed.\n    selected.userId;\n    // @ts-expect-error Cannot assert an unrelated result by supplying a row generic.\n    sessions.findMany<{madeUp: string}>();\n    // @ts-expect-error Include aliases must not overwrite known root fields.\n    sessions.findMany({include: [{as: 'userId', model: profiles, key: 'userId'}]});\n    const raw = await sessions.findMany({select: 'RAW COUNT(1)'});\n    // @ts-expect-error Arbitrary SQL++ projections have unknown shape.\n    raw[0].expiresAt;\n    const keyJoined = await sessions.findMany({\n        include: [{as: 'profile', model: profiles, key: 'userId'}],\n    });\n    const name: string = keyJoined[0].profile.name;\n    const keyedNest = await sessions.page({\n        include: [{as: 'people', model: profiles, keys: 'userId'}],\n    });\n    const people: Array<{name: string; birthday: Date} & AutoModelFields> =\n        keyedNest.items[0].people;\n    const scoped = await sessions.withDeleted().findOne();\n    const stillDate: Date = scoped.expiresAt;\n    return {expiry, birthday, friends, selectedDate, name, people, stillDate};\n}\n\nasync function conservativeInputs(args: ModelReadArgs, optional: boolean) {\n    const dynamic = await sessions.findMany(args);\n    // @ts-expect-error Broad read args can contain arbitrary projections.\n    dynamic[0].expiresAt;\n    const optionalRows = await sessions.findMany({\n        include: [{as: 'profile', model: profiles, key: 'userId', optional}],\n    });\n    type OptionalKey = {} extends Pick<(typeof optionalRows)[number], 'profile'> ? true : false;\n    const optionalKey: OptionalKey = true;\n    const literalRows = await sessions.findMany({\n        include: [{as: 'profile', model: profiles, type: 'leftJoin', key: 'userId'}],\n    });\n    type LeftKey = {} extends Pick<(typeof literalRows)[number], 'profile'> ? true : false;\n    const leftKey: LeftKey = true;\n    const innerRows = await sessions.findMany({\n        include: [{as: 'profile', model: profiles, type: 'join', key: 'userId'}],\n    });\n    type InnerKey = {} extends Pick<(typeof innerRows)[number], 'profile'> ? true : false;\n    const innerKey: InnerKey = false;\n    return {optionalKey, leftKey, innerKey};\n}\n\n// Keep compile-only cases referenced without executing reads.\nvoid inferredReads;\nvoid conservativeInputs;\n"]}

package/dist/pagination/pagination.js

@@ -41,6 +41,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Pagination = void 0;
 var connection_1 = __importDefault(require("../connection"));
+var safe_query_1 = require("../model/safe-query");
 var safe_pagination_1 = require("./safe-pagination");
 /**
  * Common pagination
@@ -59,11 +60,12 @@ var Pagination = function (args) { return __awaiter(void 0, void 0, void 0, func
             case 0:
                 _a = args.bucketName, bucketName = _a === void 0 ? '_default' : _a, _b = args.resultKey, resultKey = _b === void 0 ? bucketName : _b;
                 cluster = connection_1.default.Instance.cluster;
+                (0, safe_query_1.validateReadConsistency)(args.queryOptions);
                 _d.label = 1;
             case 1:
                 _d.trys.push([1, 3, , 4]);
                 _c = (0, safe_pagination_1.buildPaginationQuery)(args), query = _c.query, parameters = _c.parameters, selectAll_1 = _c.selectAll;
-                return [4 /*yield*/, cluster.query(query, { parameters: parameters })];
+                return [4 /*yield*/, cluster.query(query, (0, safe_query_1.queryOptionsWithParameters)(parameters, args.queryOptions))];
             case 2:
                 rows = (_d.sent()).rows;
                 completedRows = rows.map(function (r) {

package/dist/pagination/pagination.js.map

@@ -1 +1 @@
-{"version":3,"file":"pagination.js","sourceRoot":"","sources":["../../src/pagination/pagination.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA,6DAAgD;AAEhD,qDAAuD;AAGvD;;;;;;;;;GASG;AACI,IAAM,UAAU,GAAG,UAAO,IAAoB;;;;;gBAC1C,KAAmD,IAAI,WAAhC,EAAvB,UAAU,mBAAG,UAAU,KAAA,EAAE,KAA0B,IAAI,UAAR,EAAtB,SAAS,mBAAG,UAAU,KAAA,CAAS;gBAEzD,OAAO,GAAG,oBAAmB,CAAC,QAAQ,CAAC,OAAO,CAAC;;;;gBAG3C,KAAiC,IAAA,sCAAoB,EAAC,IAAI,CAAC,EAA1D,KAAK,WAAA,EAAE,UAAU,gBAAA,EAAE,0BAAS,CAA+B;gBAEnD,qBAAM,OAAO,CAAC,KAAK,CAAC,KAAK,EAAE,EAAC,UAAU,YAAA,EAAC,CAAC,EAAA;;gBAAhD,IAAI,GAAI,CAAA,SAAwC,CAAA,KAA5C;gBAEL,aAAa,GAAG,IAAI,CAAC,GAAG,CAAC,UAAC,CAAM;oBAClC,OAAO,WAAS,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;gBACxC,CAAC,CAAC,CAAC;gBAEH,sBAAO,aAAa,EAAC;;;gBAErB,IAAI,IAAI,CAAC,YAAY,KAAK,KAAK,EAAE,CAAC;oBAC9B,sBAAO,EAAE,EAAC;gBACd,CAAC;gBAED,MAAM,OAAK,CAAC;;;;KAEnB,CAAC;AAtBW,QAAA,UAAU,cAsBrB","sourcesContent":["import CouchbaseConnection from '../connection';\n\nimport {buildPaginationQuery} from './safe-pagination';\nimport {PaginationArgs} from './types';\n\n/**\n * Common pagination\n *  where = {\n      where: { owner: { $eq: \"stoqey\" }, _type: { $eq: \"Trade\" } },\n    },\n    page = 0,\n    limit = 10,\n    orderBy = { createdAt: \"DESC\" },\n * @param args PaginationArgs\n */\nexport const Pagination = async (args: PaginationArgs): Promise<any[]> => {\n    const {bucketName = '_default', resultKey = bucketName} = args;\n\n    const cluster = CouchbaseConnection.Instance.cluster;\n\n    try {\n        const {query, parameters, selectAll} = buildPaginationQuery(args);\n\n        const {rows} = await cluster.query(query, {parameters});\n\n        const completedRows = rows.map((r: any) => {\n            return selectAll ? r[resultKey] : r;\n        });\n\n        return completedRows;\n    } catch (error) {\n        if (args.throwOnError === false) {\n            return [];\n        }\n\n        throw error;\n    }\n};\n"]}
+{"version":3,"file":"pagination.js","sourceRoot":"","sources":["../../src/pagination/pagination.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA,6DAAgD;AAChD,kDAAwF;AAExF,qDAAuD;AAGvD;;;;;;;;;GASG;AACI,IAAM,UAAU,GAAG,UAAO,IAAoB;;;;;gBAC1C,KAAmD,IAAI,WAAhC,EAAvB,UAAU,mBAAG,UAAU,KAAA,EAAE,KAA0B,IAAI,UAAR,EAAtB,SAAS,mBAAG,UAAU,KAAA,CAAS;gBAEzD,OAAO,GAAG,oBAAmB,CAAC,QAAQ,CAAC,OAAO,CAAC;gBAErD,IAAA,oCAAuB,EAAC,IAAI,CAAC,YAAY,CAAC,CAAC;;;;gBAEjC,KAAiC,IAAA,sCAAoB,EAAC,IAAI,CAAC,EAA1D,KAAK,WAAA,EAAE,UAAU,gBAAA,EAAE,0BAAS,CAA+B;gBAEnD,qBAAM,OAAO,CAAC,KAAK,CAC9B,KAAK,EACL,IAAA,uCAA0B,EAAC,UAAU,EAAE,IAAI,CAAC,YAAY,CAAC,CAC5D,EAAA;;gBAHM,IAAI,GAAI,CAAA,SAGd,CAAA,KAHU;gBAKL,aAAa,GAAG,IAAI,CAAC,GAAG,CAAC,UAAC,CAAM;oBAClC,OAAO,WAAS,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;gBACxC,CAAC,CAAC,CAAC;gBAEH,sBAAO,aAAa,EAAC;;;gBAErB,IAAI,IAAI,CAAC,YAAY,KAAK,KAAK,EAAE,CAAC;oBAC9B,sBAAO,EAAE,EAAC;gBACd,CAAC;gBAED,MAAM,OAAK,CAAC;;;;KAEnB,CAAC;AA1BW,QAAA,UAAU,cA0BrB","sourcesContent":["import CouchbaseConnection from '../connection';\nimport {queryOptionsWithParameters, validateReadConsistency} from '../model/safe-query';\n\nimport {buildPaginationQuery} from './safe-pagination';\nimport {PaginationArgs} from './types';\n\n/**\n * Common pagination\n *  where = {\n      where: { owner: { $eq: \"stoqey\" }, _type: { $eq: \"Trade\" } },\n    },\n    page = 0,\n    limit = 10,\n    orderBy = { createdAt: \"DESC\" },\n * @param args PaginationArgs\n */\nexport const Pagination = async (args: PaginationArgs): Promise<any[]> => {\n    const {bucketName = '_default', resultKey = bucketName} = args;\n\n    const cluster = CouchbaseConnection.Instance.cluster;\n\n    validateReadConsistency(args.queryOptions);\n    try {\n        const {query, parameters, selectAll} = buildPaginationQuery(args);\n\n        const {rows} = await cluster.query(\n            query,\n            queryOptionsWithParameters(parameters, args.queryOptions)\n        );\n\n        const completedRows = rows.map((r: any) => {\n            return selectAll ? r[resultKey] : r;\n        });\n\n        return completedRows;\n    } catch (error) {\n        if (args.throwOnError === false) {\n            return [];\n        }\n\n        throw error;\n    }\n};\n"]}

package/dist/pagination/types.d.ts

@@ -1,3 +1,4 @@
+import type { SafeQueryOptions } from '../model/safe-query';
 export interface PaginationArgs {
     bucketName: string;
     resultKey?: string;
@@ -8,4 +9,5 @@ export interface PaginationArgs {
     offset?: number;
     orderBy?: any;
     throwOnError?: boolean;
+    queryOptions?: SafeQueryOptions;
 }

package/dist/pagination/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/pagination/types.ts"],"names":[],"mappings":"","sourcesContent":["export interface PaginationArgs {\n    bucketName: string;\n    resultKey?: string;\n    select?: any[] | string;\n    where: any;\n    page?: number;\n    limit?: number;\n    offset?: number;\n    orderBy?: any;\n    throwOnError?: boolean;\n}\n"]}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/pagination/types.ts"],"names":[],"mappings":"","sourcesContent":["import type {SafeQueryOptions} from '../model/safe-query';\n\nexport interface PaginationArgs {\n    bucketName: string;\n    resultKey?: string;\n    select?: any[] | string;\n    where: any;\n    page?: number;\n    limit?: number;\n    offset?: number;\n    orderBy?: any;\n    throwOnError?: boolean;\n    queryOptions?: SafeQueryOptions;\n}\n"]}

package/dist/search/customQuery.d.ts

@@ -1,3 +1,4 @@
+import { SafeQueryOptions } from '../model/safe-query';
 export type CustomQueryParameters = {
     [key: string]: any;
 } | any[];
@@ -9,6 +10,7 @@ export interface CustomQueryArgs {
     debug?: boolean;
     logger?: CustomQueryLogger;
     throwOnError?: boolean;
+    queryOptions?: SafeQueryOptions;
 }
 export interface CustomQueryPagination {
     hasNext: boolean;

package/dist/search/customQuery.js

@@ -41,6 +41,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CustomQuery = void 0;
 var connection_1 = __importDefault(require("../connection"));
+var safe_query_1 = require("../model/safe-query");
 /**
  * Common pagination
  *  query,
@@ -55,7 +56,9 @@ var CustomQuery = function (args) { return __awaiter(void 0, void 0, void 0, fun
             case 0:
                 query = args.query, limit = args.limit, params = args.params, _a = args.debug, debug = _a === void 0 ? false : _a, logger = args.logger, _b = args.throwOnError, throwOnError = _b === void 0 ? true : _b;
                 cluster = connection_1.default.Instance.cluster;
-                queryOptions = params === undefined ? undefined : { parameters: params };
+                queryOptions = args.queryOptions || params !== undefined
+                    ? (0, safe_query_1.queryOptionsWithParameters)(params, args.queryOptions)
+                    : undefined;
                 _d.label = 1;
             case 1:
                 _d.trys.push([1, 3, , 4]);

package/dist/search/customQuery.js.map

@@ -1 +1 @@
-{"version":3,"file":"customQuery.js","sourceRoot":"","sources":["../../src/search/customQuery.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA,6DAAgD;AAmBhD;;;;;;GAMG;AACI,IAAM,WAAW,GAAG,UACvB,IAAqB;;;;;gBAEd,KAAK,GAA+D,IAAI,MAAnE,EAAE,KAAK,GAAwD,IAAI,MAA5D,EAAE,MAAM,GAAgD,IAAI,OAApD,EAAE,KAA8C,IAAI,MAArC,EAAb,KAAK,mBAAG,KAAK,KAAA,EAAE,MAAM,GAAyB,IAAI,OAA7B,EAAE,KAAuB,IAAI,aAAR,EAAnB,YAAY,mBAAG,IAAI,KAAA,CAAS;gBAE1E,OAAO,GAAG,oBAAmB,CAAC,QAAQ,CAAC,OAAO,CAAC;gBAC/C,YAAY,GAAG,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,EAAC,UAAU,EAAE,MAAM,EAAC,CAAC;;;;gBAGzE,IAAI,KAAK,IAAI,MAAM,EAAE,CAAC;oBAClB,MAAM,CAAC,sBAAsB,EAAE,EAAC,KAAK,OAAA,EAAE,OAAO,EAAE,YAAY,EAAC,CAAC,CAAC;gBACnE,CAAC;gBAEmB,qBAAM,OAAO,CAAC,KAAK,CAAI,KAAK,EAAE,YAAY,CAAC,EAAA;;gBAAxD,KAAa,CAAA,SAA2C,CAAA,KAA/C,EAAT,IAAI,mBAAG,EAAE,KAAA;gBAEV,UAAU,GAAG,IAAI,CAAC,MAAM,CAAC;gBAEzB,OAAO,GAAG,UAAU,IAAI,KAAK,CAAC;gBAEpC,sBAAO,CAAC,IAAI,EAAE,EAAC,MAAM,QAAA,EAAE,OAAO,SAAA,EAAC,CAAC,EAAC;;;gBAEjC,IAAI,YAAY,EAAE,CAAC;oBACf,MAAM,OAAK,CAAC;gBAChB,CAAC;gBAED,sBAAO,CAAC,EAAE,EAAE,EAAC,MAAM,QAAA,EAAE,OAAO,EAAE,KAAK,EAAC,CAAC,EAAC;;;;KAE7C,CAAC;AA3BW,QAAA,WAAW,eA2BtB","sourcesContent":["import CouchbaseConnection from '../connection';\n\nexport type CustomQueryParameters = {[key: string]: any} | any[];\nexport type CustomQueryLogger = (message: string, details?: any) => void;\n\nexport interface CustomQueryArgs {\n    query: string;\n    limit: number;\n    params?: CustomQueryParameters;\n    debug?: boolean;\n    logger?: CustomQueryLogger;\n    throwOnError?: boolean;\n}\n\nexport interface CustomQueryPagination {\n    hasNext: boolean;\n    params?: CustomQueryParameters;\n}\n\n/**\n * Common pagination\n *  query,\n    bucketName = \"\",\n    select = [\"id\", \"owner\"] || \"*\"\n * @param args PaginationArgs\n */\nexport const CustomQuery = async <T>(\n    args: CustomQueryArgs\n): Promise<[T[], CustomQueryPagination]> => {\n    const {query, limit, params, debug = false, logger, throwOnError = true} = args;\n\n    const cluster = CouchbaseConnection.Instance.cluster;\n    const queryOptions = params === undefined ? undefined : {parameters: params};\n\n    try {\n        if (debug && logger) {\n            logger('couchset customQuery', {query, options: queryOptions});\n        }\n\n        const {rows = []} = await cluster.query<T>(query, queryOptions);\n\n        const totalItems = rows.length;\n\n        const hasNext = totalItems >= limit;\n\n        return [rows, {params, hasNext}];\n    } catch (error) {\n        if (throwOnError) {\n            throw error;\n        }\n\n        return [[], {params, hasNext: false}];\n    }\n};\n"]}
+{"version":3,"file":"customQuery.js","sourceRoot":"","sources":["../../src/search/customQuery.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA,6DAAgD;AAChD,kDAAiF;AAoBjF;;;;;;GAMG;AACI,IAAM,WAAW,GAAG,UACvB,IAAqB;;;;;gBAEd,KAAK,GAA+D,IAAI,MAAnE,EAAE,KAAK,GAAwD,IAAI,MAA5D,EAAE,MAAM,GAAgD,IAAI,OAApD,EAAE,KAA8C,IAAI,MAArC,EAAb,KAAK,mBAAG,KAAK,KAAA,EAAE,MAAM,GAAyB,IAAI,OAA7B,EAAE,KAAuB,IAAI,aAAR,EAAnB,YAAY,mBAAG,IAAI,KAAA,CAAS;gBAE1E,OAAO,GAAG,oBAAmB,CAAC,QAAQ,CAAC,OAAO,CAAC;gBAC/C,YAAY,GACd,IAAI,CAAC,YAAY,IAAI,MAAM,KAAK,SAAS;oBACrC,CAAC,CAAC,IAAA,uCAA0B,EAAC,MAAM,EAAE,IAAI,CAAC,YAAY,CAAC;oBACvD,CAAC,CAAC,SAAS,CAAC;;;;gBAGhB,IAAI,KAAK,IAAI,MAAM,EAAE,CAAC;oBAClB,MAAM,CAAC,sBAAsB,EAAE,EAAC,KAAK,OAAA,EAAE,OAAO,EAAE,YAAY,EAAC,CAAC,CAAC;gBACnE,CAAC;gBAEmB,qBAAM,OAAO,CAAC,KAAK,CAAI,KAAK,EAAE,YAAY,CAAC,EAAA;;gBAAxD,KAAa,CAAA,SAA2C,CAAA,KAA/C,EAAT,IAAI,mBAAG,EAAE,KAAA;gBAEV,UAAU,GAAG,IAAI,CAAC,MAAM,CAAC;gBAEzB,OAAO,GAAG,UAAU,IAAI,KAAK,CAAC;gBAEpC,sBAAO,CAAC,IAAI,EAAE,EAAC,MAAM,QAAA,EAAE,OAAO,SAAA,EAAC,CAAC,EAAC;;;gBAEjC,IAAI,YAAY,EAAE,CAAC;oBACf,MAAM,OAAK,CAAC;gBAChB,CAAC;gBAED,sBAAO,CAAC,EAAE,EAAE,EAAC,MAAM,QAAA,EAAE,OAAO,EAAE,KAAK,EAAC,CAAC,EAAC;;;;KAE7C,CAAC;AA9BW,QAAA,WAAW,eA8BtB","sourcesContent":["import CouchbaseConnection from '../connection';\nimport {queryOptionsWithParameters, SafeQueryOptions} from '../model/safe-query';\n\nexport type CustomQueryParameters = {[key: string]: any} | any[];\nexport type CustomQueryLogger = (message: string, details?: any) => void;\n\nexport interface CustomQueryArgs {\n    query: string;\n    limit: number;\n    params?: CustomQueryParameters;\n    debug?: boolean;\n    logger?: CustomQueryLogger;\n    throwOnError?: boolean;\n    queryOptions?: SafeQueryOptions;\n}\n\nexport interface CustomQueryPagination {\n    hasNext: boolean;\n    params?: CustomQueryParameters;\n}\n\n/**\n * Common pagination\n *  query,\n    bucketName = \"\",\n    select = [\"id\", \"owner\"] || \"*\"\n * @param args PaginationArgs\n */\nexport const CustomQuery = async <T>(\n    args: CustomQueryArgs\n): Promise<[T[], CustomQueryPagination]> => {\n    const {query, limit, params, debug = false, logger, throwOnError = true} = args;\n\n    const cluster = CouchbaseConnection.Instance.cluster;\n    const queryOptions =\n        args.queryOptions || params !== undefined\n            ? queryOptionsWithParameters(params, args.queryOptions)\n            : undefined;\n\n    try {\n        if (debug && logger) {\n            logger('couchset customQuery', {query, options: queryOptions});\n        }\n\n        const {rows = []} = await cluster.query<T>(query, queryOptions);\n\n        const totalItems = rows.length;\n\n        const hasNext = totalItems >= limit;\n\n        return [rows, {params, hasNext}];\n    } catch (error) {\n        if (throwOnError) {\n            throw error;\n        }\n\n        return [[], {params, hasNext: false}];\n    }\n};\n"]}

package/docs/beta-migration.md

@@ -78,7 +78,7 @@ await startCouchbase();
 await startCouchbaseServerless();
 ```
 
-The starters read `COUCHBASE_URL`, `COUCHBASE_BUCKET`, `COUCHBASE_USERNAME`, `COUCHBASE_PASSWORD`, and `COUCHBASE_PROXY`, and accept `CouchsetArgs` overrides.
+The starters can instead read one `DB_URL` such as `couchbase://user:password@localhost/bucket` (or `couchbases://` for TLS). It takes precedence over `COUCHBASE_URL`, `COUCHBASE_BUCKET`, `COUCHBASE_USERNAME`, and `COUCHBASE_PASSWORD`; `COUCHBASE_PROXY` and explicit `CouchsetArgs` overrides remain supported.
 
 ## Query Behavior
 

package/docs/document-modeling.md

@@ -99,7 +99,7 @@ CouchSet includes can join related documents by key, but large payload joins
 should be reserved for focused detail reads or small result sets.
 
 ```ts
-const report = await reports.findOne<ReportSummary & {payload: ReportPayload}>({
+const report = await reports.findOne({
     where: {id: {$eq: reportId}},
     include: [
         {
@@ -112,6 +112,10 @@ const report = await reports.findOne<ReportSummary & {payload: ReportPayload}>({
 });
 ```
 
+For client-bound models, the related type is inferred and `payload` may be absent
+or null for an unmatched optional join. See [joined reads](joins-and-consistency.md)
+for ANSI predicates, projection codecs, and alias requirements.
+
 For list pages, keep the companion model out of the query and rely on summary
 fields instead.
 

package/docs/joins-and-consistency.md

@@ -0,0 +1,228 @@
+# Joined reads and query consistency
+
+The 0.5.0 source already supported `JOIN`, `LEFT JOIN`, `NEST`, and `LEFT NEST`
+with `ON KEYS`. This extends that include API with structured ANSI `ON`, related
+model decoding, inferred client-model reads, and SDK query options. Raw
+`queryRows`, `queryOne`, and `queryPage` already accepted SDK options; they now
+share consistency validation with the other supported SQL++ reads.
+
+## ANSI predicates
+
+```ts
+import {createCouchsetClient, defineModel, dateCodec, joinField} from 'couchset/next';
+import {QueryScanConsistency} from 'couchbase';
+
+const db = createCouchsetClient({bucketName: 'app' /* connection settings */});
+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 result = 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},
+});
+// LEFT JOIN ... profiles AS creator
+// ON creator.ownerUserId = battle.createdByUserId
+result.items[0]?.creator?.birthday; // Date | undefined
+```
+
+A `joinField('alias.path')` is a field reference; an ordinary string on the
+right is always a bound value, even when it contains a dot. Aliases must refer
+to the root (default `doc`), the current include, or an earlier include. Field
+paths use dots as separators and quote every identifier segment. Alias strings
+are quoted, including reserved words. A literal dot inside a field name is not
+supported by the structured field-reference syntax.
+
+Comparisons support `$eq`, `$neq`, `$gt`, `$gte`, `$lt`, and `$lte`. Nest nonempty
+`$and` and `$or` arrays to combine predicates:
+
+```ts
+on: {$and: [
+    {left: joinField('creator.ownerUserId'), op: '$eq', right: joinField('battle.createdByUserId')},
+    {$or: [
+        {left: joinField('creator.displayName'), op: '$eq', right: 'A. Person'},
+        {left: joinField('creator.displayName'), op: '$eq', right: 'B. Person'},
+    ]},
+]}
+```
+
+`type` accepts `join`, `leftJoin`, `nest`, or `leftNest`. `optional: true` turns
+an inner kind into its left kind. Exactly one of `key`, `keys`, `on`, or `onRaw`
+is required. `key`/`keys` remain source-document paths used with `ON KEYS`:
+
+```ts
+include: [{as: 'creator', model: profiles, key: 'createdByUserId', optional: true}]
+```
+
+Without an explicit type, `keys` means NEST and `key` means JOIN. An explicit
+`type: 'join'` with `keys` now means JOIN, producing one row per matched key.
+ANSI and lookup (`ON KEYS`) clauses cannot be mixed in one query. Unsupported
+kinds, unknown aliases, empty groups, conflicting modes, duplicate aliases,
+and keyspace expressions are rejected. Model keyspaces and quoted or simple
+dotted keyspace identifiers are accepted.
+
+For advanced predicates, `onRaw: {sql: 'META(`creator`).id = ?', values: [id]}`
+is an explicit trusted-SQL escape hatch. Every `?` is replaced, left to right,
+by a generated SDK parameter; do not put `?` inside SQL literals or comments.
+Only use application-owned SQL in `sql`. Use `queryRows` for arbitrary
+projections, UNNEST, subqueries, or other SQL++ beyond the structured API.
+
+The related model supplies its keyspace, declared result type, and codecs.
+It does not automatically apply that model's `_type`, default filters, or
+soft-delete policy. Add required related predicates to `on` (especially when
+several document types share one keyspace), or use explicit SQL for key-based
+reads that need additional predicates. Definitions describe expected data;
+read inference is not runtime schema validation or referential integrity.
+
+Couchbase requires suitable indexes for ANSI joins. CouchSet does not create
+them implicitly. See the official [JOIN reference](https://docs.couchbase.com/server/current/n1ql/n1ql-language-reference/join.html)
+for supported chaining and indexing requirements.
+
+## Result shapes, projections, and codecs
+
+Client-bound models infer reads from their definition. Literal include aliases
+and bound related models determine the relation types; no row generic is
+needed. In a separately stored options object, use `as const` to retain literal
+aliases/kinds/selections. Broad or raw selections return `unknown`; dynamic
+include arrays expose unknown relation values. Widened field arrays return
+partial field selections; only tuples of definite individual literal keys
+guarantee each selected field. Union-valued tuple entries also produce partial
+selections. Union or dynamic alias names do not guarantee any particular alias.
+Optional include settings retain their possible runtime defaults in the result type. Untyped keyspace targets have
+unknown document fields. TypeScript 5 or newer is required for literal inference.
+
+| Include kind | Relation value per returned row |
+| --- | --- |
+| JOIN | One related document object |
+| LEFT JOIN | Related object, explicit `null`, or an absent property (`undefined` when accessed) |
+| NEST | Array of matching related documents |
+| LEFT NEST | Array; unmatched absent/null array values normalize to `[]` |
+
+Inner clauses remove unmatched source rows on the server. CouchSet does not
+invent those rows. JOIN cardinality is preserved, including repeated root IDs.
+`page()` takes `limit + 1` result rows, not distinct root documents. NEST arrays
+are decoded in the order received: neither source-key ordering nor any other
+nested ordering is promised. Stable pagination needs an appropriate explicit
+`orderBy`; it does not provide a snapshot across requests. See Couchbase's
+[NEST reference](https://docs.couchbase.com/server/current/n1ql/n1ql-language-reference/nest.html).
+
+Supported joined projections are `'*'` (the default) or arrays of distinct
+top-level root fields, plus an optional `select` array on each include:
+
+```ts
+const rows = 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'],
+    }],
+});
+// rows: {startsAt: Date; creators: {displayName: string; birthday: Date}[]}[]
+```
+
+Projections happen in SQL++, before rows reach the client. Present selected
+fields run the model's codecs, schema date transforms, and `dateFields`.
+Full-document parse hooks run only for full documents; projected documents
+skip these hooks because omitted fields may be required by application code.
+This applies independently to root and related documents. Full root decoding
+is preserved. Raw/computed non-joined projections are returned unchanged and
+do not run model codecs. Use an explicit decoder after `queryRows` for renamed
+fields or computed expressions. Nested/dotted joined selections are not supported.
+
+Root and relation columns are kept separate internally and combined after
+decoding. An include alias must not overwrite a root field or another alias;
+known root conflicts are type errors, and actual returned-field conflicts are
+runtime errors. Choose `creator` alongside a source `creatorId`, not `creator`
+as both the source key field and the populated result. Internal alias
+`__cs_root` and prototype-related include aliases are reserved.
+
+## Read consistency
+
+Set SDK options through `queryOptions` on `findMany`, `findOne`, `page`, `count`,
+`exists`, standalone `Pagination`, and `CustomQuery`. They are forwarded on each
+query, including joined reads. For `queryRows`, `queryOne`, and `queryPage`, use
+the existing third options argument. Defaults remain unchanged: no consistency
+mode is added by CouchSet. `count` and `exists` support root reads only and reject
+includes; use an explicit aggregate `queryRows` query to count joined rows.
+
+```ts
+import {MutationState, QueryScanConsistency} from 'couchbase';
+
+await battles.findMany({
+    queryOptions: {scanConsistency: QueryScanConsistency.RequestPlus},
+});
+
+// Capture the SDK mutation result from a successful KV operation.
+const mutation = await profiles.getCollection().upsert(profileId, storedProfile);
+if (!mutation.token) throw new Error('Mutation token unavailable');
+const state = new MutationState(mutation.token);
+await battles.findMany({queryOptions: {consistentWith: state}});
+await battles.queryRows('SELECT RAW 1', {}, {consistentWith: state});
+```
+
+`request_plus` waits for indexes to catch up to mutations preceding the query.
+`consistentWith` requests read-your-writes for the supplied SDK mutation state.
+Neither option is a multi-document transaction or a stable snapshot across
+multiple reads. KV reads and transaction-attempt queries keep their SDK-specific
+APIs. See [SDK consistency options](https://docs.couchbase.com/nodejs-sdk/current/howtos/n1ql-queries-with-sdk.html).
+
+`scanConsistency` and `consistentWith` cannot be combined, including an explicit
+`not_bounded` mode. Unsupported scan modes and raw consistency overrides are
+rejected before querying, even with `throwOnError: false`. SDK failures still
+follow the existing fallback policy. SDK parameters remain separate from SQL.
+
+## Compatibility and validation
+
+- Existing `ON KEYS` inputs remain available. Explicit JOIN with `keys` now honors
+  JOIN cardinality; omit the type or use NEST to retain the previous array shape.
+- Client-bound `TypedModel` reads replace caller row generics with inference.
+  `new Model()` retains its existing generic read API for compatibility. For
+  arbitrary SQL++ result assertions, use the explicitly typed `queryRows<T>` API.
+- Includes no longer overwrite root fields. Change colliding aliases. The SDK
+  row envelope has changed internally; public flat root-plus-relations results
+  remain, and mocked query responses must use the new separate columns.
+- Arbitrary joined selections now fail explicitly; move them to `queryRows`.
+  Partial projections skip full-document hooks; raw projections skip decoding.
+- Aggregate helpers reject includes they previously ignored. Conflicting
+  consistency options now fail early instead of relying on SDK behavior.
+
+Run `npm run test:unit` for deterministic mocked SQL/binding, decoding, shape,
+cardinality, and option-forwarding tests. Run `npm run test:types` for a build
+and strict public-declaration inference fixtures. These tests do not execute a
+Couchbase server, prove an index plan, or measure freshness under concurrency.
+
+
+### Local server validation
+
+On 2026-09-05, 20 live probes passed against the configured local Couchbase
+Query 8.0.3 server. The probes used a fresh isolated scope, synthetic documents,
+and dedicated primary/lookup indexes; that scope and all its contents were
+removed afterward. They exercised all ANSI and ON KEYS join kinds, duplicate
+JOIN rows, compound predicates and binding, missing LEFT JOIN relations, empty
+LEFT NEST arrays, root/related date codecs and projections, raw ON, pagination,
+alias rejection, immediate `request_plus` reads, and normal/joined reads using
+real SDK mutation tokens via `consistentWith`.
+
+The first run exposed an example error: `MutationState` takes `mutation.token`,
+not the whole mutation result. The example is corrected and covered by a strict
+type fixture; the corrected live run passed all 20 probes. These observations
+validate this local server and synthetic workload; they do not establish a
+concurrent multi-document snapshot, a production index plan, or compatibility
+with every supported server version.

package/docs/next-primitives.md

@@ -24,6 +24,10 @@ const db = createCouchsetClient({
 
 `defineModel()` only describes metadata; `db.model(sessions)` only binds and registers the model. Neither operation creates Couchbase resources. Legacy `new Model()` remains supported and continues to use the existing singleton.
 
+See [joined reads and consistency](joins-and-consistency.md) for inferred `findMany`,
+`findOne`, and `page` results, structured ANSI predicates, relation codecs,
+projections, and SDK read consistency options.
+
 ## Provisioning and dynamic models
 
 Run administrative DDL explicitly, with credentials that have `Manage Scopes` and query-index permissions:

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "couchset",
-    "version": "0.5.0",
+    "version": "0.5.1",
     "description": "Couchbase ORM",
     "private": false,
     "main": "dist/legacy/index.js",
@@ -60,6 +60,7 @@
         "lint": "tslint \"src/**/*.ts\" --project tsconfig.json",
         "build": "rimraf dist && ./node_modules/.bin/tsc --skipLibCheck",
         "test": "npm run test:unit && npm run test:integration",
+        "test:types": "npm run build && node scripts/check-read-types.js",
         "test:unit": "mocha \"src/**/*.test.ts\" --ignore src/index.test.ts --ignore src/index.serverless.test.ts --exit",
         "test:integration": "mocha src/index.test.ts --exit",
         "test:serverless": "mocha src/index.serverless.test.ts --exit",