@decaf-ts/for-pouch 0.2.7 → 0.2.9

package/lib/constants.cjs

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PouchFlavour = void 0;
+exports.DefaultLocalStoragePath = exports.PouchFlavour = void 0;
 /**
  * @description Identifier for PouchDB flavor in the decorator system
  * @summary A string constant that identifies the PouchDB implementation in the decorator system.
@@ -9,4 +9,11 @@ exports.PouchFlavour = void 0;
  * @memberOf module:for-pouch
  */
 exports.PouchFlavour = "pouch";
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY29uc3RhbnRzLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vc3JjL2NvbnN0YW50cy50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiOzs7QUFBQTs7Ozs7O0dBTUc7QUFDVSxRQUFBLFlBQVksR0FBRyxPQUFPLENBQUMiLCJzb3VyY2VzQ29udGVudCI6WyIvKipcbiAqIEBkZXNjcmlwdGlvbiBJZGVudGlmaWVyIGZvciBQb3VjaERCIGZsYXZvciBpbiB0aGUgZGVjb3JhdG9yIHN5c3RlbVxuICogQHN1bW1hcnkgQSBzdHJpbmcgY29uc3RhbnQgdGhhdCBpZGVudGlmaWVzIHRoZSBQb3VjaERCIGltcGxlbWVudGF0aW9uIGluIHRoZSBkZWNvcmF0b3Igc3lzdGVtLlxuICogVGhpcyBpcyB1c2VkIHRvIHRhcmdldCBkZWNvcmF0b3JzIHNwZWNpZmljYWxseSBmb3IgUG91Y2hEQiBhZGFwdGVycy5cbiAqIEBjb25zdCBQb3VjaEZsYXZvdXJcbiAqIEBtZW1iZXJPZiBtb2R1bGU6Zm9yLXBvdWNoXG4gKi9cbmV4cG9ydCBjb25zdCBQb3VjaEZsYXZvdXIgPSBcInBvdWNoXCI7XG4iXX0=
+/**
+ * @description Default relative path where local PouchDB databases are stored
+ * @summary Used when creating a local PouchDB instance without a remote host; combined with dbName to form the filesystem path.
+ * @const DefaultLocalStoragePath
+ * @memberOf module:for-pouch
+ */
+exports.DefaultLocalStoragePath = "local_dbs";
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY29uc3RhbnRzLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vc3JjL2NvbnN0YW50cy50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiOzs7QUFBQTs7Ozs7O0dBTUc7QUFDVSxRQUFBLFlBQVksR0FBRyxPQUFPLENBQUM7QUFFcEM7Ozs7O0dBS0c7QUFDVSxRQUFBLHVCQUF1QixHQUFHLFdBQVcsQ0FBQyIsInNvdXJjZXNDb250ZW50IjpbIi8qKlxuICogQGRlc2NyaXB0aW9uIElkZW50aWZpZXIgZm9yIFBvdWNoREIgZmxhdm9yIGluIHRoZSBkZWNvcmF0b3Igc3lzdGVtXG4gKiBAc3VtbWFyeSBBIHN0cmluZyBjb25zdGFudCB0aGF0IGlkZW50aWZpZXMgdGhlIFBvdWNoREIgaW1wbGVtZW50YXRpb24gaW4gdGhlIGRlY29yYXRvciBzeXN0ZW0uXG4gKiBUaGlzIGlzIHVzZWQgdG8gdGFyZ2V0IGRlY29yYXRvcnMgc3BlY2lmaWNhbGx5IGZvciBQb3VjaERCIGFkYXB0ZXJzLlxuICogQGNvbnN0IFBvdWNoRmxhdm91clxuICogQG1lbWJlck9mIG1vZHVsZTpmb3ItcG91Y2hcbiAqL1xuZXhwb3J0IGNvbnN0IFBvdWNoRmxhdm91ciA9IFwicG91Y2hcIjtcblxuLyoqXG4gKiBAZGVzY3JpcHRpb24gRGVmYXVsdCByZWxhdGl2ZSBwYXRoIHdoZXJlIGxvY2FsIFBvdWNoREIgZGF0YWJhc2VzIGFyZSBzdG9yZWRcbiAqIEBzdW1tYXJ5IFVzZWQgd2hlbiBjcmVhdGluZyBhIGxvY2FsIFBvdWNoREIgaW5zdGFuY2Ugd2l0aG91dCBhIHJlbW90ZSBob3N0OyBjb21iaW5lZCB3aXRoIGRiTmFtZSB0byBmb3JtIHRoZSBmaWxlc3lzdGVtIHBhdGguXG4gKiBAY29uc3QgRGVmYXVsdExvY2FsU3RvcmFnZVBhdGhcbiAqIEBtZW1iZXJPZiBtb2R1bGU6Zm9yLXBvdWNoXG4gKi9cbmV4cG9ydCBjb25zdCBEZWZhdWx0TG9jYWxTdG9yYWdlUGF0aCA9IFwibG9jYWxfZGJzXCI7XG4iXX0=

package/lib/constants.d.ts

@@ -6,3 +6,10 @@
  * @memberOf module:for-pouch
  */
 export declare const PouchFlavour = "pouch";
+/**
+ * @description Default relative path where local PouchDB databases are stored
+ * @summary Used when creating a local PouchDB instance without a remote host; combined with dbName to form the filesystem path.
+ * @const DefaultLocalStoragePath
+ * @memberOf module:for-pouch
+ */
+export declare const DefaultLocalStoragePath = "local_dbs";

package/lib/esm/adapter.d.ts

@@ -4,7 +4,7 @@ import { BaseError, Context, OperationKeys } from "@decaf-ts/db-decorators";
 import { RelationsMetadata } from "@decaf-ts/core";
 import Database = PouchDB.Database;
 import { Constructor, Model } from "@decaf-ts/decorator-validation";
-import { PouchFlags } from "./types";
+import { PouchConfig, PouchFlags } from "./types";
 import { PouchRepository } from "./PouchRepository";
 /**
  * @description Sets the creator ID on a model during creation or update operations
@@ -25,25 +25,33 @@ import { PouchRepository } from "./PouchRepository";
 export declare function createdByOnPouchCreateUpdate<M extends Model, R extends PouchRepository<M>, V extends RelationsMetadata>(this: R, context: Context<PouchFlags>, data: V, key: keyof M, model: M): Promise<void>;
 /**
  * @description PouchDB implementation of the CouchDBAdapter
- * @summary This class provides a concrete implementation of the CouchDBAdapter for PouchDB.
- * It handles all database operations like create, read, update, delete (CRUD) for both
- * single documents and bulk operations. It also provides methods for querying and indexing.
- * @template Database - The PouchDB database type
+ * @summary Concrete adapter that bridges the generic CouchDBAdapter to a PouchDB backend. It supports CRUD (single and bulk), indexing and Mango queries, and wires flavour-specific decorations.
  * @template PouchFlags - The flags specific to PouchDB operations
  * @template Context<PouchFlags> - The context type with PouchDB flags
- * @param {Database} scope - The PouchDB database instance
+ * @param {PouchConfig} config - Adapter configuration (remote credentials or local storage path, db name, plugins)
  * @param {string} [alias] - Optional alias for the database
  * @class PouchAdapter
  * @example
  * ```typescript
- * import PouchDB from 'pouchdb';
  * import { PouchAdapter } from '@decaf-ts/for-pouch';
  *
- * // Create a new PouchDB instance
- * const db = new PouchDB('my-database');
+ * // Create a PouchAdapter with config
+ * const adapter = new PouchAdapter({
+ *   protocol: 'http',
+ *   host: 'localhost:5984',
+ *   user: 'admin',
+ *   password: 'secret',
+ *   dbName: 'my-database',
+ *   plugins: []
+ * });
  *
- * // Create a PouchAdapter with the database
- * const adapter = new PouchAdapter(db);
+ * // Or use local storage
+ * const localAdapter = new PouchAdapter({
+ *   protocol: 'http', // ignored for local
+ *   dbName: 'local-db',
+ *   storagePath: 'local_dbs',
+ *   plugins: []
+ * });
  *
  * // Use the adapter for database operations
  * const result = await adapter.read('users', 'user-123');
@@ -55,8 +63,8 @@ export declare function createdByOnPouchCreateUpdate<M extends Model, R extends
  *   participant PouchDB
  *   participant CouchDB
  *
- *   Client->>PouchAdapter: new PouchAdapter(db)
- *   PouchAdapter->>CouchDBAdapter: super(scope, PouchFlavour, alias)
+ *   Client->>PouchAdapter: new PouchAdapter(config, alias?)
+ *   PouchAdapter->>CouchDBAdapter: super(config, PouchFlavour, alias)
  *
  *   Client->>PouchAdapter: create(table, id, model)
  *   PouchAdapter->>PouchDB: put(model)
@@ -72,8 +80,33 @@ export declare function createdByOnPouchCreateUpdate<M extends Model, R extends
  *   PouchDB-->>PouchAdapter: Document
  *   PouchAdapter-->>Client: Model
  */
-export declare class PouchAdapter extends CouchDBAdapter<Database, PouchFlags, Context<PouchFlags>> {
-    constructor(scope: Database, alias?: string);
+export declare class PouchAdapter extends CouchDBAdapter<PouchConfig, Database, PouchFlags, Context<PouchFlags>> {
+    constructor(config: PouchConfig, alias?: string);
+    /**
+       * @description Lazily initializes and returns the underlying PouchDB client
+       * @summary Loads required PouchDB plugins once, builds the connection URL or local storage path from config, and caches the Database instance for reuse. Throws InternalError if client creation fails.
+       * @return {Database} A PouchDB Database instance ready to perform operations
+       * @mermaid
+       * sequenceDiagram
+       *   participant Caller
+       *   participant PouchAdapter
+       *   participant PouchDB
+       *   Caller->>PouchAdapter: getClient()
+       *   alt client not initialized
+       *     PouchAdapter->>PouchAdapter: register plugins
+       *     PouchAdapter->>PouchDB: new PouchDB(url or path)
+       *     alt creation fails
+       *       PouchDB-->>PouchAdapter: Error
+       *       PouchAdapter-->>Caller: throws InternalError
+       *     else success
+       *       PouchDB-->>PouchAdapter: Database
+       *       PouchAdapter-->>Caller: cached client
+       *     end
+       *   else client initialized
+       *     PouchAdapter-->>Caller: cached client
+       *   end
+       */
+    getClient(): Database;
     /**
      * @description Generates operation flags for PouchDB operations
      * @summary Creates a set of flags for a specific operation, including a UUID for identification.