couchset 0.2.7 → 0.4.0

package/dist/model/index.d.ts

@@ -1,7 +1,36 @@
-import type { Collection, GetOptions, RemoveOptions, ReplaceOptions, UpsertOptions } from 'couchbase';
-import { CustomQueryPagination } from '../search';
+import type { Collection, Cluster, GetOptions, MutateInOptions, RemoveOptions, ReplaceOptions } from 'couchbase';
 import { SchemaTypes } from '../utils';
-import CouchbaseConnection from '../connection';
+import type { ModelPageResult, ModelReadArgs } from './read-helpers';
+import type { QueryPageOptions, QueryPageResult, QueryParameters, SafeQueryOptions } from './safe-query';
+import type { FindByIdWithMetaResult, InsertWriteOptions, PatchByIdArgs, UpsertWriteOptions } from './write-helpers';
+import { Hydrated } from './hydrated-document';
+import { EnsureIndexOptions, ModelIndexDefinition } from './indexes';
+import type { ParseHook, ValidationHook } from './validation';
+/** A small connection surface used by client-bound models. */
+export interface ModelConnection {
+    bucket?: any;
+    bucketName?: string;
+    cluster: Cluster;
+    getBucket(): string;
+    getCollection(scopeName?: string, collectionName?: string): Collection;
+    isConnected(): boolean;
+    ready(): Promise<any>;
+    shouldReconnect(error: any): boolean;
+    markDisconnected(error: any): void;
+}
+/** Converts a field between the application's value and Couchbase JSON. */
+export interface FieldCodec<T = any, TDatabase = any> {
+    toDatabase(value: T): TDatabase;
+    fromDatabase(value: TDatabase): T;
+}
+export type { ModelPageResult, ModelReadArgs } from './read-helpers';
+export type { QueryLogger, QueryPageOptions, QueryPageResult, QueryParameters, SafeQueryOptions, } from './safe-query';
+export type { FindByIdWithMetaResult, PatchByIdArgs } from './write-helpers';
+export type { Hydrated } from './hydrated-document';
+export type { IncludeDefinition, IncludeType } from './include';
+export type { EnsureIndexOptions, ModelIndexDefinition } from './indexes';
+export type { TtlOptions } from './ttl';
+export type { ParseHook, ValidationHook } from './validation';
 export interface AutoModelFields {
     id: string;
     createdAt: Date;
@@ -13,91 +42,202 @@ export interface AutoModelFields {
 export interface UpdateOptions extends ReplaceOptions {
     silent?: boolean;
 }
+export interface DeleteByIdOptions extends RemoveOptions {
+    hard?: boolean;
+}
 export interface ModalOptions {
     scope?: string;
+    collection?: string;
     schema?: Record<string, SchemaTypes>;
-    graphqlType?: any;
+    softDelete?: boolean;
+    defaultWhere?: any;
+    validateCreate?: ValidationHook;
+    validateReplace?: ValidationHook;
+    parse?: ParseHook;
+    dateFields?: string[];
+    /**
+     * Explicit field transforms. A field cannot also be a dateFields/schema date
+     * transform, since that makes the parse order ambiguous.
+     */
+    codecs?: Record<string, FieldCodec<any, any>>;
+    indexes?: ModelIndexDefinition[];
 }
+export type ConsumeOnceResult = {
+    status: 'consumed';
+} | {
+    status: 'missing';
+} | {
+    status: 'conflict';
+};
 export declare class Model {
+    private static registeredModels;
     collection: Collection;
     collectionName: string;
     scope: string;
+    private scopeName?;
+    private collectionTargetName?;
+    private defaultWhere?;
+    private defaultWhereMode;
+    private softDelete;
+    private validateCreateHook?;
+    private validateReplaceHook?;
+    private parseHook?;
+    private dateFields?;
+    private codecs;
+    private readonly connection?;
+    private indexes;
     schema: Record<string, SchemaTypes>;
-    graphqlType: any;
-    constructor(name: string, options?: ModalOptions);
+    constructor(name: string, options?: ModalOptions, connection?: ModelConnection);
     /**
-     * Set setGraphqlType
-     * setGraphqlType
+     * Ensure indexes for every constructed model with index declarations.
      */
-    setGraphqlType(gqlType: any): Model;
+    static ensureIndexes(options?: EnsureIndexOptions): Promise<string[]>;
     /**
      * Refresh and get default collection from CouchbaseConnection
      * Because CouchbaseConnection is a singleton, sometimes it might be undefined depending when model was created
      * So we have to call it from all model methods
      * to avoid error `Cannot read property 'defaultCollection' of null`
      */
-    fresh(): void;
+    private fresh;
+    private prepare;
+    private withConnection;
     /** Get this collection
      * getCollection
      */
-    getBucketName(): string;
+    private getBucketName;
     /** Get this collection
      * getCollection
      */
-    couchbaseConnection(): CouchbaseConnection;
+    private couchbaseConnection;
     /** Get this collection
      * getCollection
      */
     getCollection(): Collection;
+    private collectionTarget;
+    private queryResultKey;
+    private readContext;
+    private readArgs;
+    private writeContext;
+    private cloneWithDefaultWhereMode;
+    /**
+     * Return the active bucket as a SQL++ keyspace identifier.
+     */
+    bucket(): string;
+    /**
+     * Return this model's SQL++ keyspace target.
+     */
+    keyspace(): string;
+    /**
+     * Return a SQL++ FROM target for this model's current bucket.
+     */
+    from(alias?: string): string;
     /**
-     * create
+     * Return CREATE INDEX statements for this model without executing them.
      */
-    create<T>(data: T, options?: UpsertOptions): Promise<T & AutoModelFields>;
+    indexStatements(options?: EnsureIndexOptions): string[];
     /**
-     * findById
+     * Create this model's declared indexes if Couchbase does not already have them.
      */
-    findById(id: string, options?: GetOptions): Promise<any & AutoModelFields>;
+    ensureIndexes(options?: EnsureIndexOptions): Promise<string[]>;
     /**
-     * update
+     * Run a SQL++ query and return rows directly.
      */
-    updateById<T>(id: string, data: T, opt?: UpdateOptions): Promise<T>;
+    queryRows<T>(query: string, params?: QueryParameters, options?: SafeQueryOptions): Promise<T[]>;
     /**
-     * save
+     * Run a SQL++ query and return the first row or null.
      */
-    save<T>(data: T & {
+    queryOne<T>(query: string, params?: QueryParameters, options?: SafeQueryOptions): Promise<T | null>;
+    /**
+     * Run a SQL++ query using limit + 1 pagination.
+     */
+    queryPage<T>(query: string, params?: QueryParameters, options?: QueryPageOptions): Promise<QueryPageResult<T>>;
+    /**
+     * Find many model-scoped documents.
+     */
+    findMany<T>(args?: ModelReadArgs): Promise<T[]>;
+    /**
+     * Find the first matching model-scoped document.
+     */
+    findOne<T>(args?: ModelReadArgs): Promise<T | null>;
+    /**
+     * Check whether at least one model-scoped document matches.
+     */
+    exists(args?: ModelReadArgs): Promise<boolean>;
+    /**
+     * Count model-scoped documents.
+     */
+    count(args?: ModelReadArgs): Promise<number>;
+    /**
+     * Fetch a limit + 1 page of model-scoped documents.
+     */
+    page<T>(args?: ModelReadArgs): Promise<ModelPageResult<T>>;
+    withDeleted(): Model;
+    onlyDeleted(): Model;
+    withoutDefaultWhere(): Model;
+    /**
+     * Insert a new document and fail if the id already exists.
+     */
+    insert<T>(data: T, options?: InsertWriteOptions): Promise<T & AutoModelFields>;
+    /** @internal Prepare a transaction insert without issuing a normal SDK write. */
+    prepareInsert<T>(data: T): Promise<T & AutoModelFields>;
+    /**
+     * Explicit insert-or-replace write.
+     */
+    upsert<T>(data: T, options?: UpsertWriteOptions): Promise<T & AutoModelFields>;
+    getById<T>(id: string, options?: GetOptions): Promise<T & AutoModelFields>;
+    findDocById<T extends {
+        id: string;
+    }>(id: string, options?: GetOptions): Promise<Hydrated<T>>;
+    /**
+     * Find a document with SDK metadata.
+     */
+    findByIdWithMeta<T>(id: string, options?: GetOptions): Promise<FindByIdWithMetaResult<T>>;
+    /** Ergonomic alias for findByIdWithMeta, intended for CAS workflows. */
+    getWithCas<T>(id: string, options?: GetOptions): Promise<FindByIdWithMetaResult<T>>;
+    /**
+     * Explicit full-document replace.
+     */
+    replaceById<T>(id: string, data: T, options?: UpdateOptions): Promise<T & AutoModelFields>;
+    /** @internal Prepare a transaction replace without issuing a normal SDK write. */
+    prepareReplace<T>(id: string, data: T, options?: UpdateOptions): Promise<T & AutoModelFields>;
+    /**
+     * Replace only when the supplied CAS still describes the current document.
+     * CouchSet deliberately performs one SDK operation and never re-reads/retries
+     * with a new CAS, because doing so would defeat the caller's concurrency check.
+     */
+    replaceIfCas<T>(id: string, data: T, cas: any, options?: UpdateOptions): Promise<T & AutoModelFields>;
+    /**
+     * Remove a one-time document with exactly the CAS supplied by the caller.
+     * Missing and CAS-mismatch cases are normal outcomes; transport and ambiguous
+     * failures are rethrown so callers never mistake an unknown commit for success.
+     */
+    consumeOnce(id: string, cas: any): Promise<ConsumeOnceResult>;
+    /**
+     * Partial document mutation using common patch operators.
+     */
+    patchById<T>(id: string, patch: PatchByIdArgs, options?: MutateInOptions): Promise<T & AutoModelFields>;
+    /**
+     * Couchbase subdocument mutation escape hatch.
+     */
+    mutateById(id: string, specs: any[], options?: MutateInOptions): Promise<any>;
+    /**
+     * Atomic numeric field increment.
+     */
+    incrementById<T>(id: string, field: string, delta: number, options?: MutateInOptions): Promise<T & AutoModelFields>;
+    softDeleteById<T>(id: string, options?: MutateInOptions): Promise<T & AutoModelFields>;
+    restoreById<T>(id: string, options?: MutateInOptions): Promise<T & AutoModelFields>;
+    deleteById<T>(id: string, options?: DeleteByIdOptions): Promise<boolean | (T & AutoModelFields)>;
+    findDocOne<T extends {
+        id: string;
+    }>(args?: ModelReadArgs): Promise<Hydrated<T> | null>;
+    hydrate<T extends {
         id: string;
-    }, opt?: UpdateOptions): Promise<T>;
-    delete(id: string, options?: RemoveOptions): Promise<boolean>;
-    /**
-     * Pagination
-     *
-        select = ['id', 'createdAt']
-        where = {
-         where: { owner: { $eq: "stoqey" }, _type: { $eq: "Trade" } },
-        },
-        page = 0,
-        limit = 10,
-        orderBy = { createdAt: "DESC" },
-    * @param args PaginationArgs
-    */
-    pagination({ select, where, orderBy, limit, page, customQuery, }: {
-        select?: any[] | string;
-        where?: any;
-        orderBy?: any;
-        limit?: number;
-        page?: number;
-        customQuery?: any;
-    }): Promise<any[]>;
-    /**
-     * Run a custom query with model parsing
-     * @param { select, query }
-     * @returns
-     */
-    customQuery<T>({ params, limit, query, }: {
-        params: any;
-        limit: number;
-        query: string;
-    }): Promise<[T[], CustomQueryPagination]>;
+    }>(data: T & AutoModelFields): Hydrated<T>;
     parse<T>(data: T): T;
+    /** @internal Used by the typed client before a document reaches the SDK. */
+    serialize<T>(data: T): T;
+    /** @internal Used by patch helpers and transaction-bound models. */
+    serializeField(path: string, value: any): any;
+    private deserialize;
 }
 export default Model;