@decaf-ts/for-nano 0.7.6 → 0.9.0

package/lib/types/adapter.d.mts

@@ -0,0 +1,449 @@
+import { OperationKeys, PrimaryKeyType } from "@decaf-ts/db-decorators";
+import { CouchDBAdapter, MangoQuery, ViewResponse } from "@decaf-ts/for-couchdb";
+import { DocumentScope, ServerScope } from "nano";
+import { Model } from "@decaf-ts/decorator-validation";
+import { NanoConfig, NanoFlags } from "./types.js";
+import { Adapter, Context, ContextOf, ContextualArgs, MaybeContextualArg, RelationsMetadata, Repository } from "@decaf-ts/core";
+import { NanoRepository } from "./NanoRepository.js";
+import { NanoDispatch } from "./NanoDispatch.js";
+import { Constructor } from "@decaf-ts/decoration";
+/**
+ * @description Sets the creator or updater field in a model based on the user in the context
+ * @summary Callback function used in decorators to automatically set the created_by or updated_by fields
+ * with the username from the context when a document is created or updated
+ * @template M - Type extending Model
+ * @template R - Type extending NanoRepository<M>
+ * @template V - Type extending RelationsMetadata
+ * @param {R} this - The repository instance
+ * @param {Context<NanoFlags>} context - The operation context containing user information
+ * @param {V} data - The relation metadata
+ * @param key - The property key to set with the username
+ * @param {M} model - The model instance being created or updated
+ * @return {Promise<void>} A promise that resolves when the operation is complete
+ * @function createdByOnNanoCreateUpdate
+ * @memberOf module:for-nano
+ * @mermaid
+ * sequenceDiagram
+ *   participant F as createdByOnNanoCreateUpdate
+ *   participant C as Context
+ *   participant M as Model
+ *   F->>C: get("user")
+ *   C-->>F: user object
+ *   F->>M: set key to user.name
+ *   Note over F: If no user in context
+ *   F-->>F: throw UnsupportedError
+ */
+export declare function createdByOnNanoCreateUpdate<M extends Model, R extends NanoRepository<M>, V extends RelationsMetadata>(this: R, context: ContextOf<R>, data: V, key: keyof M, model: M): Promise<void>;
+/**
+ * @description Adapter for interacting with Nano databases
+ * @summary Provides a standardized interface for performing CRUD operations on Nano databases,
+ * extending the CouchDB adapter with Nano-specific functionality. This adapter handles document
+ * creation, reading, updating, and deletion, as well as bulk operations and index management.
+ * @template DocumentScope - The Nano document scope type
+ * @template NanoFlags - Configuration flags for Nano operations
+ * @template Context - Context type for operations
+ * @param {DocumentScope<any>} scope - The Nano document scope to use for database operations
+ * @param {string} [alias] - Optional alias for the adapter
+ * @class NanoAdapter
+ * @example
+ * ```typescript
+ * // Connect to a Nano database
+ * const server = NanoAdapter.connect('admin', 'password', 'localhost:5984');
+ * const db = server.db.use('my_database');
+ *
+ * // Create an adapter instance
+ * const adapter = new NanoAdapter(db);
+ *
+ * // Use the adapter for database operations
+ * const document = await adapter.read('users', '123');
+ * ```
+ * @mermaid
+ * classDiagram
+ *   class CouchDBAdapter {
+ *     +flags()
+ *     +Dispatch()
+ *     +index()
+ *     +create()
+ *     +read()
+ *     +update()
+ *     +delete()
+ *   }
+ *   class NanoAdapter {
+ *     +flags()
+ *     +Dispatch()
+ *     +index()
+ *     +create()
+ *     +createAll()
+ *     +read()
+ *     +readAll()
+ *     +update()
+ *     +updateAll()
+ *     +delete()
+ *     +deleteAll()
+ *     +raw()
+ *     +static connect()
+ *     +static createDatabase()
+ *     +static deleteDatabase()
+ *     +static createUser()
+ *     +static deleteUser()
+ *     +static decoration()
+ *   }
+ *   CouchDBAdapter <|-- NanoAdapter
+ */
+export declare class NanoAdapter extends CouchDBAdapter<NanoConfig, DocumentScope<any>, Context<NanoFlags>> {
+    constructor(scope: NanoConfig, alias?: string);
+    /**
+     * @description Shuts down the adapter instance
+     * @summary Cleans up internal resources and clears the cached Nano client instance
+     * @return {Promise<void>} A promise that resolves when shutdown completes
+     */
+    shutdown(...args: MaybeContextualArg<Context<NanoFlags>>): Promise<void>;
+    /**
+     * @description Lazily creates and returns the Nano DocumentScope client
+     * @summary Uses the adapter configuration to establish a connection and wrap a database scope with credentials
+     * @return {DocumentScope<any>} The ready-to-use Nano DocumentScope for the configured database
+     */
+    protected getClient(): any;
+    /**
+     * @description Generates flags for database operations
+     * @summary Creates a set of flags for a specific operation, including user information
+     * @template M - Type extending Model
+     * @param {OperationKeys} operation - The operation being performed (create, read, update, delete)
+     * @param {Constructor<M>} model - The model constructor
+     * @param {Partial<NanoFlags>} flags - Partial flags to be merged
+     * @return {Promise<NanoFlags>} Complete flags for the operation
+     */
+    protected flags<M extends Model>(operation: OperationKeys, model: Constructor<M>, flags: Partial<NanoFlags>, ...args: any[]): Promise<NanoFlags>;
+    /**
+     * @description Creates a new NanoDispatch instance
+     * @summary Returns a dispatcher for handling Nano-specific operations
+     * @return {NanoDispatch} A new NanoDispatch instance
+     */
+    protected Dispatch(): NanoDispatch;
+    repository<R extends Repository<any, Adapter<NanoConfig, DocumentScope<any>, MangoQuery, Context<NanoFlags>>>>(): Constructor<R>;
+    /**
+     * @description Creates database indexes for models
+     * @summary Generates and creates indexes in the Nano database based on the provided models
+     * @template M - Type extending Model
+     * @param models - Model constructors to create indexes for
+     * @return {Promise<void>} A promise that resolves when all indexes are created
+     * @mermaid
+     * sequenceDiagram
+     *   participant A as NanoAdapter
+     *   participant G as generateIndexes
+     *   participant DB as Nano Database
+     *   A->>G: generateIndexes(models)
+     *   G-->>A: indexes
+     *   loop For each index
+     *     A->>DB: createIndex(index)
+     *     DB-->>A: response
+     *     Note over A: Check if index already exists
+     *     alt Index exists
+     *       A-->>A: throw ConflictError
+     *     end
+     *   end
+     */
+    protected index<M extends Model>(...models: Constructor<M>[]): Promise<void>;
+    /**
+     * @description Creates a new document in the database
+     * @summary Inserts a new document into the Nano database with the provided data
+     * @param {string} tableName - The name of the table/collection
+     * @param {string | number} id - The document identifier
+     * @param {Record<string, any>} model - The document data to insert
+     * @return {Promise<Record<string, any>>} A promise that resolves to the created document with metadata
+     * @mermaid
+     * sequenceDiagram
+     *   participant A as NanoAdapter
+     *   participant DB as Nano Database
+     *   A->>DB: insert(model)
+     *   alt Success
+     *     DB-->>A: response with ok=true
+     *     A->>A: assignMetadata(model, response.rev)
+     *     A-->>A: return document with metadata
+     *   else Error
+     *     DB-->>A: error
+     *     A-->>A: throw parseError(e)
+     *   else Not OK
+     *     DB-->>A: response with ok=false
+     *     A-->>A: throw InternalError
+     *   end
+     */
+    create<M extends Model>(tableName: Constructor<M>, id: PrimaryKeyType, model: Record<string, any>, ...args: ContextualArgs<Context<NanoFlags>>): Promise<Record<string, any>>;
+    /**
+     * @description Creates multiple documents in the database
+     * @summary Inserts multiple documents into the Nano database in a single bulk operation
+     * @param {string} tableName - The name of the table/collection
+     * @param {string[] | number[]} ids - Array of document identifiers
+     * @param models - Array of document data to insert
+     * @return A promise that resolves to an array of created documents with metadata
+     * @mermaid
+     * sequenceDiagram
+     *   participant A as NanoAdapter
+     *   participant DB as Nano Database
+     *   A->>DB: bulk({docs: models})
+     *   alt Success
+     *     DB-->>A: response array
+     *     A->>A: Check if all responses have no errors
+     *     alt All OK
+     *       A->>A: assignMultipleMetadata(models, revs)
+     *       A-->>A: return documents with metadata
+     *     else Some errors
+     *       A->>A: Collect error messages
+     *       A-->>A: throw InternalError with collected messages
+     *     end
+     *   else Error
+     *     DB-->>A: error
+     *     A-->>A: throw parseError(e)
+     *   end
+     */
+    createAll<M extends Model>(tableName: Constructor<M>, ids: PrimaryKeyType[], models: Record<string, any>[], ...args: ContextualArgs<Context<NanoFlags>>): Promise<Record<string, any>[]>;
+    /**
+     * @description Retrieves a document from the database
+     * @summary Fetches a single document from the Nano database by its ID
+     * @param {string} tableName - The name of the table/collection
+     * @param {string | number} id - The document identifier
+     * @return {Promise<Record<string, any>>} A promise that resolves to the retrieved document with metadata
+     * @mermaid
+     * sequenceDiagram
+     *   participant A as NanoAdapter
+     *   participant DB as Nano Database
+     *   A->>A: generateId(tableName, id)
+     *   A->>DB: get(_id)
+     *   alt Success
+     *     DB-->>A: record
+     *     A->>A: assignMetadata(record, record._rev)
+     *     A-->>A: return document with metadata
+     *   else Error
+     *     DB-->>A: error
+     *     A-->>A: throw parseError(e)
+     *   end
+     */
+    read<M extends Model>(tableName: Constructor<M>, id: PrimaryKeyType, ...args: ContextualArgs<Context<NanoFlags>>): Promise<Record<string, any>>;
+    /**
+     * @description Retrieves multiple documents from the database
+     * @summary Fetches multiple documents from the Nano database by their IDs in a single operation
+     * @param {string} tableName - The name of the table/collection
+     * @param {Array<string | number | bigint>} ids - Array of document identifiers
+     * @return A promise that resolves to an array of retrieved documents with metadata
+     * @mermaid
+     * sequenceDiagram
+     *   participant A as NanoAdapter
+     *   participant DB as Nano Database
+     *   A->>A: Map ids to generateId(tableName, id)
+     *   A->>DB: fetch({keys: mappedIds}, {})
+     *   DB-->>A: results
+     *   A->>A: Process each result row
+     *   loop For each row
+     *     alt Row has error
+     *       A-->>A: throw InternalError
+     *     else Row has document
+     *       A->>A: assignMetadata(doc, doc._rev)
+     *     else No document
+     *       A-->>A: throw InternalError
+     *     end
+     *   end
+     *   A-->>A: return documents with metadata
+     */
+    readAll<M extends Model>(tableName: Constructor<M>, ids: (string | number | bigint)[], ...args: ContextualArgs<Context<NanoFlags>>): Promise<Record<string, any>[]>;
+    /**
+     * @description Updates a document in the database
+     * @summary Updates an existing document in the Nano database with the provided data
+     * @param {string} tableName - The name of the table/collection
+     * @param {string | number} id - The document identifier
+     * @param {Record<string, any>} model - The updated document data
+     * @return {Promise<Record<string, any>>} A promise that resolves to the updated document with metadata
+     * @mermaid
+     * sequenceDiagram
+     *   participant A as NanoAdapter
+     *   participant DB as Nano Database
+     *   A->>DB: insert(model)
+     *   alt Success
+     *     DB-->>A: response with ok=true
+     *     A->>A: assignMetadata(model, response.rev)
+     *     A-->>A: return document with metadata
+     *   else Error
+     *     DB-->>A: error
+     *     A-->>A: throw parseError(e)
+     *   else Not OK
+     *     DB-->>A: response with ok=false
+     *     A-->>A: throw InternalError
+     *   end
+     */
+    update<M extends Model>(tableName: Constructor<M>, id: PrimaryKeyType, model: Record<string, any>, ...args: ContextualArgs<Context<NanoFlags>>): Promise<Record<string, any>>;
+    /**
+     * @description Updates multiple documents in the database
+     * @summary Performs a bulk update operation on the Nano database for the provided documents
+     * @param {string} tableName - The name of the table/collection
+     * @param {Array<string|number>} ids - Array of document identifiers
+     * @param {Promise<Array<Record<string, any>>>} models - Array of updated document data
+     * @return {Promise<Promise<Array<Record<string, any>>>>} A promise that resolves to the updated documents with metadata
+     */
+    updateAll<M extends Model>(tableName: Constructor<M>, ids: PrimaryKeyType[], models: Record<string, any>[], ...args: ContextualArgs<Context<NanoFlags>>): Promise<Record<string, any>[]>;
+    /**
+     * @description Deletes a document from the database
+     * @summary Removes a single document from the Nano database by its ID and returns the deleted document metadata
+     * @param {string} tableName - The name of the table/collection
+     * @param {string|number} id - The document identifier
+     * @return {Promise<Record<string, any>>} A promise that resolves to the deleted document with metadata
+     */
+    delete<M extends Model>(tableName: Constructor<M>, id: PrimaryKeyType, ...args: ContextualArgs<Context<NanoFlags>>): Promise<Record<string, any>>;
+    /**
+     * @description Deletes multiple documents from the database
+     * @summary Performs a bulk delete operation for the provided IDs and returns the deleted documents metadata
+     * @param {string} tableName - The name of the table/collection
+     * @param {Array<string|number|bigint>} ids - Array of document identifiers to delete
+     * @return {Promise<Array<Record<string, any>>>} A promise resolving to the deleted documents with metadata
+     */
+    deleteAll<M extends Model>(tableName: Constructor<M>, ids: PrimaryKeyType[], ...args: ContextualArgs<Context<NanoFlags>>): Promise<Record<string, any>[]>;
+    /**
+     * @description Executes a raw Mango query against the database
+     * @summary Runs a Mango query using Nano's find API and optionally returns only the documents array
+     * @template R - The expected response or document array type
+     * @param {MangoQuery} rawInput - The Mango query to execute
+     * @param {boolean} [docsOnly=true] - Whether to return only the docs array or the full response
+     * @return {Promise<R>} A promise that resolves to the query result, shaped according to docsOnly
+     */
+    raw<R>(rawInput: MangoQuery, docsOnly?: boolean, ...args: ContextualArgs<Context<NanoFlags>>): Promise<R>;
+    view<R>(ddoc: string, viewName: string, options: Record<string, any>, ..._args: ContextualArgs<Context<NanoFlags>>): Promise<ViewResponse<R>>;
+    /**
+     * @description Establishes a connection to a Nano (CouchDB) server
+     * @summary Creates and returns a Nano ServerScope using the given credentials, host, and protocol
+     * @param {string} user - Username used for authentication
+     * @param {string} pass - Password used for authentication
+     * @param {string} [host="localhost:5984"] - Host and port of the CouchDB server
+     * @param {("http"|"https")} [protocol="http"] - Protocol to use for the connection
+     * @return {ServerScope} The Nano ServerScope connection
+     */
+    static connect(user: string, pass: string, host?: string, protocol?: "http" | "https", agent?: any): ServerScope;
+    /**
+     * @description Creates a new database on the Nano server
+     * @summary Creates a new database with the specified name on the connected Nano server
+     * @param {ServerScope} con - The Nano server connection
+     * @param {string} name - The name of the database to create
+     * @return {Promise<void>} A promise that resolves when the database is created
+     * @mermaid
+     * sequenceDiagram
+     *   participant A as NanoAdapter
+     *   participant DB as Nano Server
+     *   A->>DB: db.create(name)
+     *   alt Success
+     *     DB-->>A: result with ok=true
+     *   else Error
+     *     DB-->>A: error
+     *     A-->>A: throw parseError(e)
+     *   else Not OK
+     *     DB-->>A: result with ok=false
+     *     A-->>A: throw parseError(error, reason)
+     *   end
+     */
+    static createDatabase(con: ServerScope, name: string): Promise<void>;
+    /**
+     * @description Deletes a database from the Nano server
+     * @summary Removes an existing database with the specified name from the connected Nano server
+     * @param {ServerScope} con - The Nano server connection
+     * @param {string} name - The name of the database to delete
+     * @return {Promise<void>} A promise that resolves when the database is deleted
+     * @mermaid
+     * sequenceDiagram
+     *   participant A as NanoAdapter
+     *   participant DB as Nano Server
+     *   A->>DB: db.destroy(name)
+     *   alt Success
+     *     DB-->>A: result with ok=true
+     *   else Error
+     *     DB-->>A: error
+     *     A-->>A: throw parseError(e)
+     *   else Not OK
+     *     DB-->>A: result with ok=false
+     *     A-->>A: throw InternalError
+     *   end
+     */
+    static deleteDatabase(con: ServerScope, name: string): Promise<void>;
+    /**
+     * @description Closes the keep-alive agent associated with a Nano connection
+     * @summary Destroys the custom HTTP/HTTPS agent that was created during connection setup
+     * @param {ServerScope} con - The Nano server connection whose agent should be destroyed
+     */
+    static closeConnection(con?: ServerScope | null): void;
+    /**
+     * @description Creates a new user and grants access to a database
+     * @summary Creates a new user in the Nano server and configures security to grant the user access to a specific database
+     * @param {ServerScope} con - The Nano server connection
+     * @param {string} dbName - The name of the database to grant access to
+     * @param {string} user - The username to create
+     * @param {string} pass - The password for the new user
+     * @param {string[]} [roles=["reader", "writer"]] - The roles to assign to the user
+     * @return {Promise<void>} A promise that resolves when the user is created and granted access
+     * @mermaid
+     * sequenceDiagram
+     *   participant A as NanoAdapter
+     *   participant U as _users Database
+     *   participant S as Security API
+     *   A->>A: Create user object
+     *   A->>U: insert(user)
+     *   alt Success
+     *     U-->>A: response with ok=true
+     *     A->>S: PUT _security with user permissions
+     *     alt Security Success
+     *       S-->>A: security response with ok=true
+     *     else Security Failure
+     *       S-->>A: security response with ok=false
+     *       A-->>A: throw InternalError
+     *     end
+     *   else Error
+     *     U-->>A: error
+     *     A-->>A: throw parseError(e)
+     *   else Not OK
+     *     U-->>A: response with ok=false
+     *     A-->>A: throw InternalError
+     *   end
+     */
+    static createUser(con: ServerScope, dbName: string, user: string, pass: string, roles?: string[]): Promise<void>;
+    /**
+     * @description Deletes a user from the Nano server
+     * @summary Removes an existing user from the Nano server
+     * @param {ServerScope} con - The Nano server connection
+     * @param {string} dbName - The name of the database (used for logging purposes)
+     * @param {string} user - The username to delete
+     * @return {Promise<void>} A promise that resolves when the user is deleted
+     * @mermaid
+     * sequenceDiagram
+     *   participant A as NanoAdapter
+     *   participant U as _users Database
+     *   A->>A: Generate user ID
+     *   A->>U: get(id)
+     *   U-->>A: user document
+     *   A->>U: destroy(id, user._rev)
+     *   alt Success
+     *     U-->>A: success response
+     *   else Error
+     *     U-->>A: error
+     *     A-->>A: throw parseError(e)
+     *   end
+     */
+    static deleteUser(con: ServerScope, dbName: string, user: string): Promise<void>;
+    /**
+     * @description Sets up decorations for Nano-specific model properties
+     * @summary Configures decorators for created_by and updated_by fields in models to be automatically
+     * populated with the user from the context when documents are created or updated
+     * @return {void}
+     * @mermaid
+     * sequenceDiagram
+     *   participant A as NanoAdapter
+     *   participant D as Decoration
+     *   participant R as Repository
+     *   A->>R: key(PersistenceKeys.CREATED_BY)
+     *   R-->>A: createdByKey
+     *   A->>D: flavouredAs("nano")
+     *   A->>D: for(createdByKey)
+     *   A->>D: define(onCreate(createdByOnNanoCreateUpdate), propMetadata)
+     *   A->>D: apply()
+     *   A->>R: key(PersistenceKeys.UPDATED_BY)
+     *   R-->>A: updatedByKey
+     *   A->>D: flavouredAs("nano")
+     *   A->>D: for(updatedByKey)
+     *   A->>D: define(onCreate(createdByOnNanoCreateUpdate), propMetadata)
+     *   A->>D: apply()
+     */
+    static decoration(): void;
+}

package/lib/types/constants.d.cts

@@ -0,0 +1,7 @@
+/**
+ * @description Identifier for the Nano database flavor
+ * @summary Constant string that identifies the database type as "nano" for use in adapter selection and configuration
+ * @const NanoFlavour
+ * @memberOf module:for-nano
+ */
+export declare const NanoFlavour = "nano";

package/lib/types/constants.d.mts

@@ -0,0 +1,7 @@
+/**
+ * @description Identifier for the Nano database flavor
+ * @summary Constant string that identifies the database type as "nano" for use in adapter selection and configuration
+ * @const NanoFlavour
+ * @memberOf module:for-nano
+ */
+export declare const NanoFlavour = "nano";

package/lib/types/index.d.cts

@@ -0,0 +1,23 @@
+export * from "./constants.cjs";
+export * from "./NanoRepository.cjs";
+export * from "./types.cjs";
+export * from "./adapter.cjs";
+/**
+ * @description A TypeScript module for interacting with Nano databases
+ * @summary This module provides a set of utilities, classes, and types for working with Nano databases. It includes repository patterns, adapters, and type definitions to simplify database operations. Key exports include {@link NanoAdapter}, {@link NanoRepository}, {@link NanoFlags}, and {@link NanoFlavour}.
+ * @module for-nano
+ */
+/**
+ * @description Package version identifier
+ * @summary Stores the current package version string for the for-nano module
+ * @const VERSION
+ * @memberOf module:for-nano
+ */
+export declare const VERSION = "0.8.0";
+/**
+ * @description Package version identifier
+ * @summary Stores the current package version string for the for-nano module
+ * @const PACKAGE_NAME
+ * @memberOf module:for-nano
+ */
+export declare const PACKAGE_NAME = "@decaf-ts/for-nano";

package/lib/types/index.d.mts

@@ -0,0 +1,23 @@
+export * from "./constants.js";
+export * from "./NanoRepository.js";
+export * from "./types.js";
+export * from "./adapter.js";
+/**
+ * @description A TypeScript module for interacting with Nano databases
+ * @summary This module provides a set of utilities, classes, and types for working with Nano databases. It includes repository patterns, adapters, and type definitions to simplify database operations. Key exports include {@link NanoAdapter}, {@link NanoRepository}, {@link NanoFlags}, and {@link NanoFlavour}.
+ * @module for-nano
+ */
+/**
+ * @description Package version identifier
+ * @summary Stores the current package version string for the for-nano module
+ * @const VERSION
+ * @memberOf module:for-nano
+ */
+export declare const VERSION = "0.8.0";
+/**
+ * @description Package version identifier
+ * @summary Stores the current package version string for the for-nano module
+ * @const PACKAGE_NAME
+ * @memberOf module:for-nano
+ */
+export declare const PACKAGE_NAME = "@decaf-ts/for-nano";

package/lib/types/index.d.ts

@@ -13,7 +13,7 @@ export * from "./adapter";
  * @const VERSION
  * @memberOf module:for-nano
  */
-export declare const VERSION = "0.7.5";
+export declare const VERSION = "0.8.0";
 /**
  * @description Package version identifier
  * @summary Stores the current package version string for the for-nano module

package/lib/types/types.d.cts

@@ -0,0 +1,39 @@
+import { AdapterFlags } from "@decaf-ts/core";
+/**
+ * @description Configuration flags for Nano database operations
+ * @summary Extended repository flags that include user authentication information for Nano database connections
+ * @interface NanoFlags
+ * @memberOf module:for-nano
+ */
+export interface NanoFlags extends AdapterFlags {
+    /**
+     * @description User authentication information for Nano database connections
+     */
+    user: {
+        /**
+         * @description Username for authentication with the Nano database
+         */
+        name: string;
+        /**
+         * @description Optional array of roles assigned to the user
+         */
+        roles?: string[];
+    };
+}
+/**
+ * @description Connection configuration for Nano
+ * @summary Defines the necessary parameters to establish a connection to a Nano (CouchDB) server and select a database
+ * @property {string} user - Username to authenticate against the server
+ * @property {string} password - Password to authenticate the user
+ * @property {string} host - Host and port of the server (e.g., "localhost:5984") or full URL host without protocol
+ * @property {string} dbName - The database name to use on the server
+ * @typeDef NanoConfig
+ * @memberOf module:for-nano
+ */
+export type NanoConfig = {
+    user: string;
+    password: string;
+    host: string;
+    dbName: string;
+    protocol: "http" | "https";
+};

package/lib/types/types.d.mts

@@ -0,0 +1,39 @@
+import { AdapterFlags } from "@decaf-ts/core";
+/**
+ * @description Configuration flags for Nano database operations
+ * @summary Extended repository flags that include user authentication information for Nano database connections
+ * @interface NanoFlags
+ * @memberOf module:for-nano
+ */
+export interface NanoFlags extends AdapterFlags {
+    /**
+     * @description User authentication information for Nano database connections
+     */
+    user: {
+        /**
+         * @description Username for authentication with the Nano database
+         */
+        name: string;
+        /**
+         * @description Optional array of roles assigned to the user
+         */
+        roles?: string[];
+    };
+}
+/**
+ * @description Connection configuration for Nano
+ * @summary Defines the necessary parameters to establish a connection to a Nano (CouchDB) server and select a database
+ * @property {string} user - Username to authenticate against the server
+ * @property {string} password - Password to authenticate the user
+ * @property {string} host - Host and port of the server (e.g., "localhost:5984") or full URL host without protocol
+ * @property {string} dbName - The database name to use on the server
+ * @typeDef NanoConfig
+ * @memberOf module:for-nano
+ */
+export type NanoConfig = {
+    user: string;
+    password: string;
+    host: string;
+    dbName: string;
+    protocol: "http" | "https";
+};

package/package.json

@@ -1,17 +1,22 @@
 {
   "name": "@decaf-ts/for-nano",
-  "version": "0.7.6",
+  "version": "0.9.0",
   "description": "decaf-ts persistence adapter for CouchDB via nano",
   "type": "module",
   "exports": {
     ".": {
-      "types": "./lib/types/index.d.ts",
-      "import": "./lib/esm/index.js",
-      "require": "./lib/cjs/index.cjs",
+      "import": {
+        "types": "./lib/types/index.d.mts",
+        "default": "./lib/esm/index.js"
+      },
+      "require": {
+        "types": "./lib/types/index.d.cts",
+        "default": "./lib/cjs/index.cjs"
+      },
       "default": "./lib/esm/index.js"
     }
   },
-  "types": "./lib/types/index.d.ts",
+  "types": "./lib/types/index.d.mts",
   "main": "./lib/cjs/index.cjs",
   "module": "./lib/esm/index.js",
   "sideEffects": false,
@@ -23,8 +28,8 @@
     "set-git-auth": "git config url.\"https://api:$(cat .token)@github.com/\".insteadOf \"https://github.com/\" && git config url.\"https://ssh:$(cat .token)@github.com/\".insteadOf \"ssh://git@github.com/\" && git config url.\"https://git:$(cat .token)@github.com/\".insteadOf \"git@github.com:\"",
     "flash-forward": "npx npm-check-updates -u && npm run do-install",
     "reset": "rm -rf * && git checkout . && git pull && npm run do-install",
-    "build": "npx build-scripts --dev",
-    "build:prod": "npx build-scripts --prod",
+    "build": "build-scripts --dev",
+    "build:prod": "build-scripts --prod",
     "test": "jest --runInBand --coverage --detectOpenHandles",
     "test:unit": "jest --testPathPatterns=\"/tests/unit\" --passWithNoTests --detectOpenHandles",
     "test:integration": "jest --testPathPatterns=\"/tests/(integration)\" --passWithNoTests --detectOpenHandles",
@@ -39,7 +44,7 @@
     "clean-publish": "npx clean-publish",
     "drawings": "for FILE in workdocs/drawings/*.drawio; do echo \"converting $FILE to image...\" && docker run --rm -v $(pwd):/data rlespinasse/drawio-export --format png $FILE; done && cp -rf workdocs/drawings/export/* workdocs/resources/",
     "uml": "cd workdocs/uml && for FILE in ./*.puml; do docker run --rm -v $(pwd):/work -w /work miy4/plantuml -DPLANTUML_LIMIT_SIZE=8192 -tpng $FILE; done && cd ../.. && cp -fr workdocs/uml/*.png workdocs/resources/",
-    "docs": "npx rimraf ./docs && mkdir docs && npx build-scripts --docs",
+    "docs": "npx rimraf ./docs && mkdir docs && build-scripts --docs",
     "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",
     "repo:init": "codex exec \"$(cat ./.codex/prompts/repo-setup.md)\nbase_path is `./`, initialize the repository\"",
     "repo:setup": "codex exec \"$(cat ./.codex/prompts/repo-setup.md)\nbase_path is ./\"",

package/lib/cjs/NanoDispatch.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"NanoDispatch.js","sourceRoot":"","sources":["../../src/NanoDispatch.ts"],"names":[],"mappings":"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"}