@decaf-ts/for-couchdb 0.13.0 → 0.14.1

package/lib/types/query/Paginator.d.mts

@@ -26,6 +26,8 @@ import { Constructor } from "@decaf-ts/decoration";
  * const page2 = await paginator.page(2);
  */
 export declare class CouchDBPaginator<M extends Model> extends Paginator<M, M[], MangoQuery> {
+    protected _bookmarks: Map<number, string>;
+    protected _knownLastPage?: number;
     /**
      * @description Creates a new CouchDBPaginator instance
      * @summary Initializes a paginator for CouchDB query results
@@ -35,6 +37,7 @@ export declare class CouchDBPaginator<M extends Model> extends Paginator<M, M[],
      * @param {Constructor<M>} clazz - The model constructor
      */
     constructor(adapter: CouchDBAdapter<any, any, any>, query: MangoQuery, size: number, clazz: Constructor<M>);
+    private isValidBookmark;
     /**
      * @description Prepares a query for pagination
      * @summary Modifies the raw query to include pagination parameters

package/lib/types/query/Statement.d.cts

@@ -1,8 +1,9 @@
-import { Adapter, AdapterFlags, Condition, ContextOf, SelectSelector, Statement, UnsupportedError, ViewKind } from "@decaf-ts/core";
+import { Adapter, Condition, ContextOf, SelectSelector, Statement, UnsupportedError, ViewKind } from "@decaf-ts/core";
 import { MangoQuery, MangoSelector, ViewResponse } from "../types.d.cts";
 import { Model } from "@decaf-ts/decorator-validation";
 import { CouchDBViewMetadata } from "../views/types.d.cts";
 import { CouchDBAdapter } from "../adapter.d.cts";
+import { CouchDBFlags } from "../types.d.cts";
 type CouchDBViewDescriptor = {
     ddoc: string;
     view: string;
@@ -42,7 +43,7 @@ type CouchDBAggregateInfo = {
 export declare class CouchDBStatement<M extends Model, A extends Adapter<any, any, MangoQuery, any>, R> extends Statement<M, A, R, MangoQuery> {
     protected manualAggregation?: CouchDBAggregateInfo;
     protected attributeTypeCache: Map<string, string | undefined>;
-    constructor(adapter: A, overrides?: Partial<AdapterFlags>);
+    constructor(adapter: A, overrides?: Partial<CouchDBFlags>);
     /**
      * @description Builds a CouchDB Mango query from the statement
      * @summary Converts the statement's conditions, selectors, and options into a CouchDB Mango query

package/lib/types/query/Statement.d.mts

@@ -1,8 +1,9 @@
-import { Adapter, AdapterFlags, Condition, ContextOf, SelectSelector, Statement, UnsupportedError, ViewKind } from "@decaf-ts/core";
+import { Adapter, Condition, ContextOf, SelectSelector, Statement, UnsupportedError, ViewKind } from "@decaf-ts/core";
 import { MangoQuery, MangoSelector, ViewResponse } from "../types.d.mts";
 import { Model } from "@decaf-ts/decorator-validation";
 import { CouchDBViewMetadata } from "../views/types.d.mts";
 import { CouchDBAdapter } from "../adapter.d.mts";
+import { CouchDBFlags } from "../types.d.mts";
 type CouchDBViewDescriptor = {
     ddoc: string;
     view: string;
@@ -42,7 +43,7 @@ type CouchDBAggregateInfo = {
 export declare class CouchDBStatement<M extends Model, A extends Adapter<any, any, MangoQuery, any>, R> extends Statement<M, A, R, MangoQuery> {
     protected manualAggregation?: CouchDBAggregateInfo;
     protected attributeTypeCache: Map<string, string | undefined>;
-    constructor(adapter: A, overrides?: Partial<AdapterFlags>);
+    constructor(adapter: A, overrides?: Partial<CouchDBFlags>);
     /**
      * @description Builds a CouchDB Mango query from the statement
      * @summary Converts the statement's conditions, selectors, and options into a CouchDB Mango query

package/lib/types/query/index.d.cts

@@ -2,3 +2,4 @@ export * from "./constants.d.cts";
 export * from "./Paginator.d.cts";
 export * from "./Statement.d.cts";
 export * from "./translate.d.cts";
+export * from "./planner.d.cts";

package/lib/types/query/index.d.mts

@@ -2,3 +2,4 @@ export * from "./constants.d.mts";
 export * from "./Paginator.d.mts";
 export * from "./Statement.d.mts";
 export * from "./translate.d.mts";
+export * from "./planner.d.mts";

package/lib/types/query/planner.d.cts

@@ -0,0 +1,64 @@
+import { OrderDirection } from "@decaf-ts/core";
+import { Constructor } from "@decaf-ts/decoration";
+import { MangoQuery, MangoSelector, SortOrder } from "../types.d.cts";
+export type MangoIndexCandidate = {
+    name: string;
+    ddoc: string;
+    fields: string[];
+    direction?: OrderDirection;
+    source: "table" | "defaultQuery" | "index";
+};
+export type MangoIndexResolution = {
+    candidate: MangoIndexCandidate;
+    use_index: string | [string, string];
+};
+export type MangoPlannerLog = {
+    debug?: (message: string) => void;
+    warn?: (message: string) => void;
+};
+export type RequiredMangoIndexShape = {
+    tableName: string;
+    modelName: string;
+    equalityFields: string[];
+    rangeFields: string[];
+    sortFields: string[];
+    sortDirection?: OrderDirection;
+    requiredFields: string[];
+};
+export type ReversedIndexDeclaration = {
+    attribute: string;
+    compositions: string[];
+    directions: OrderDirection[];
+    name: string;
+    ddoc: string;
+    fields: Array<string | Record<string, OrderDirection>>;
+    decorator: string;
+};
+export declare function normalizeSortField(entry: SortOrder): {
+    field: string;
+    direction?: OrderDirection;
+} | undefined;
+export declare function getSortFields(query: MangoQuery): string[];
+export declare function getSortDirection(query: MangoQuery): OrderDirection | undefined;
+export declare function getEqualitySelectorFields(selector?: MangoSelector): Set<string>;
+export declare function getRangeSelectorFields(selector?: MangoSelector): Set<string>;
+export declare function buildGeneratedIndexCandidates(clazz: Constructor): MangoIndexCandidate[];
+export declare function findGeneratedIndexCandidateByName(clazz: Constructor, expectedName: string): MangoIndexCandidate | undefined;
+export declare function resolveGeneratedIndexForQuery(clazz: Constructor, query: MangoQuery, options?: {
+    preserveDefaultQuery?: boolean;
+    requireSortCoverage?: boolean;
+}): MangoIndexResolution | undefined;
+export declare function getRequiredMangoIndexShape(clazz: Constructor, query: MangoQuery): RequiredMangoIndexShape;
+export declare function reverseRequiredShapeToIndexDeclaration(clazz: Constructor, query: MangoQuery): ReversedIndexDeclaration;
+export declare function attachGeneratedUseIndex(clazz: Constructor | undefined, query: MangoQuery, log?: MangoPlannerLog, options?: {
+    preserveDefaultQuery?: boolean;
+    requireSortCoverage?: boolean;
+    requireIndex?: boolean;
+    forceNamedIndexes?: boolean;
+}): void;
+export declare function requireGeneratedUseIndex(clazz: Constructor, query: MangoQuery, log?: MangoPlannerLog, options?: {
+    requireSortCoverage?: boolean;
+}): void;
+export declare function warnScanProneMangoOperators(selector: unknown, log?: MangoPlannerLog, path?: string): void;
+export declare function ensureDeterministicSort(query: MangoQuery, tieBreaker: string, direction?: OrderDirection): void;
+export declare function enableMangoExecutionStats(query: MangoQuery): void;

package/lib/types/query/planner.d.mts

@@ -0,0 +1,64 @@
+import { OrderDirection } from "@decaf-ts/core";
+import { Constructor } from "@decaf-ts/decoration";
+import { MangoQuery, MangoSelector, SortOrder } from "../types.d.mts";
+export type MangoIndexCandidate = {
+    name: string;
+    ddoc: string;
+    fields: string[];
+    direction?: OrderDirection;
+    source: "table" | "defaultQuery" | "index";
+};
+export type MangoIndexResolution = {
+    candidate: MangoIndexCandidate;
+    use_index: string | [string, string];
+};
+export type MangoPlannerLog = {
+    debug?: (message: string) => void;
+    warn?: (message: string) => void;
+};
+export type RequiredMangoIndexShape = {
+    tableName: string;
+    modelName: string;
+    equalityFields: string[];
+    rangeFields: string[];
+    sortFields: string[];
+    sortDirection?: OrderDirection;
+    requiredFields: string[];
+};
+export type ReversedIndexDeclaration = {
+    attribute: string;
+    compositions: string[];
+    directions: OrderDirection[];
+    name: string;
+    ddoc: string;
+    fields: Array<string | Record<string, OrderDirection>>;
+    decorator: string;
+};
+export declare function normalizeSortField(entry: SortOrder): {
+    field: string;
+    direction?: OrderDirection;
+} | undefined;
+export declare function getSortFields(query: MangoQuery): string[];
+export declare function getSortDirection(query: MangoQuery): OrderDirection | undefined;
+export declare function getEqualitySelectorFields(selector?: MangoSelector): Set<string>;
+export declare function getRangeSelectorFields(selector?: MangoSelector): Set<string>;
+export declare function buildGeneratedIndexCandidates(clazz: Constructor): MangoIndexCandidate[];
+export declare function findGeneratedIndexCandidateByName(clazz: Constructor, expectedName: string): MangoIndexCandidate | undefined;
+export declare function resolveGeneratedIndexForQuery(clazz: Constructor, query: MangoQuery, options?: {
+    preserveDefaultQuery?: boolean;
+    requireSortCoverage?: boolean;
+}): MangoIndexResolution | undefined;
+export declare function getRequiredMangoIndexShape(clazz: Constructor, query: MangoQuery): RequiredMangoIndexShape;
+export declare function reverseRequiredShapeToIndexDeclaration(clazz: Constructor, query: MangoQuery): ReversedIndexDeclaration;
+export declare function attachGeneratedUseIndex(clazz: Constructor | undefined, query: MangoQuery, log?: MangoPlannerLog, options?: {
+    preserveDefaultQuery?: boolean;
+    requireSortCoverage?: boolean;
+    requireIndex?: boolean;
+    forceNamedIndexes?: boolean;
+}): void;
+export declare function requireGeneratedUseIndex(clazz: Constructor, query: MangoQuery, log?: MangoPlannerLog, options?: {
+    requireSortCoverage?: boolean;
+}): void;
+export declare function warnScanProneMangoOperators(selector: unknown, log?: MangoPlannerLog, path?: string): void;
+export declare function ensureDeterministicSort(query: MangoQuery, tieBreaker: string, direction?: OrderDirection): void;
+export declare function enableMangoExecutionStats(query: MangoQuery): void;

package/lib/types/types.d.cts

@@ -1,3 +1,4 @@
+import { AdapterFlags } from "@decaf-ts/core";
 /**
  * @description Response from a CouchDB Mango query
  * @summary Contains the matching documents and additional metadata about the query execution
@@ -164,3 +165,10 @@ export interface ViewResponse<D = any> {
     offset?: number;
     rows: ViewRow<D>[];
 }
+export interface CouchDBFlags extends Partial<AdapterFlags> {
+    /**
+     * When true, non-default Mango queries try to attach a generated named index.
+     * Default-query index selection remains unchanged.
+     */
+    forceNamedIndexes?: boolean;
+}

package/lib/types/types.d.mts

@@ -1,3 +1,4 @@
+import { AdapterFlags } from "@decaf-ts/core";
 /**
  * @description Response from a CouchDB Mango query
  * @summary Contains the matching documents and additional metadata about the query execution
@@ -164,3 +165,10 @@ export interface ViewResponse<D = any> {
     offset?: number;
     rows: ViewRow<D>[];
 }
+export interface CouchDBFlags extends Partial<AdapterFlags> {
+    /**
+     * When true, non-default Mango queries try to attach a generated named index.
+     * Default-query index selection remains unchanged.
+     */
+    forceNamedIndexes?: boolean;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decaf-ts/for-couchdb",
-  "version": "0.13.0",
+  "version": "0.14.1",
   "description": "decaf-ts couchdb wrappers",
   "type": "module",
   "exports": {
@@ -45,6 +45,7 @@
     "publish-docs": "docker run -it --rm --user $(id -u):$(id -g) -v \"$(pwd)/workdocs/confluence:/content\" -e ATLASSIAN_API_TOKEN=$(cat .confluence-token) ghcr.io/markdown-confluence/publish:latest",
     "docker:login": "echo $(cat .token) | docker login ghcr.io -u decaf --password-stdin",
     "docker:build": "npm run docker:build-booter && npm run docker:build-couchdb",
+    "docker:pull": "npm run docker:login && docker pull ghcr.io/decaf-ts/couchdb:latest && docker pull ghcr.io/decaf-ts/couchdb-booter:latest",
     "docker:build-booter": "docker build -t ghcr.io/decaf-ts/couchdb-booter:$(cat package.json | jq -r '.version') -t ghcr.io/decaf-ts/couchdb-booter:latest -f ./docker/Dockerfile-booter ./docker",
     "docker:build-couchdb": "docker build -t ghcr.io/decaf-ts/couchdb:$(cat package.json | jq -r '.version') -t ghcr.io/decaf-ts/couchdb:latest -f ./docker/Dockerfile-couchdb ./docker",
     "docker:publish": "npm run docker:publish-booter && npm run docker:publish-couchdb",

package/lib/cjs/errors.cjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"errors.js","sourceRoot":"","sources":["errors.js"],"names":[],"mappings":";;;AAAA,2DAAoD;AACpD;;;;;;;;;;;;;;;;GAgBG;AACH,MAAa,UAAW,SAAQ,yBAAS;IACrC,YAAY,GAAG;QACX,KAAK,CAAC,UAAU,CAAC,IAAI,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC;IACrC,CAAC;CACJ;AAJD,gCAIC;AACD,kCAAkC"}

package/lib/esm/errors.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAEpD;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,OAAO,UAAW,SAAQ,SAAS;IACvC,YAAY,GAAmB;QAC7B,KAAK,CAAC,UAAU,CAAC,IAAI,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC;IACnC,CAAC;CACF"}