@decaf-ts/for-typeorm 0.0.6

package/lib/esm/TypeORMAdapter.d.ts

@@ -0,0 +1,221 @@
+import { Adapter, RelationsMetadata, Sequence, type SequenceOptions } from "@decaf-ts/core";
+import { BaseError, Context, OperationKeys } from "@decaf-ts/db-decorators";
+import "reflect-metadata";
+import { type Constructor, Model } from "@decaf-ts/decorator-validation";
+import { TypeORMStatement } from "./query";
+import { TypeORMFlags, TypeORMQuery, TypeORMTableSpec } from "./types";
+import { TypeORMRepository } from "./TypeORMRepository";
+import { TypeORMDispatch } from "./TypeORMDispatch";
+import { DataSource } from "typeorm";
+import { DataSourceOptions } from "typeorm/data-source/DataSourceOptions";
+export declare function createdByOnPostgresCreateUpdate<M extends Model, R extends TypeORMRepository<M>, V extends RelationsMetadata>(this: R, context: Context<TypeORMFlags>, data: V, key: keyof M, model: M): Promise<void>;
+/**
+ * @description Adapter for TypeORM-backed persistence operations.
+ * @summary Implements the Decaf.ts Adapter over a TypeORM DataSource, providing CRUD operations, query/statement factories, sequence management, error parsing, and decoration helpers.
+ * @template Y The native configuration type (TypeORM DataSourceOptions).
+ * @template F The repository flags type.
+ * @template C The context type.
+ * @param {DataSourceOptions} scope The DataSource options for the adapter.
+ * @param {string} flavour The flavour of the adapter.
+ * @param {string} [alias] Optional alias for the adapter.
+ * @class TypeORMAdapter
+ * @example
+ * const adapter = new TypeORMAdapter({ type: 'postgres', /* ... *\/ });
+ * await adapter.initialize();
+ * const repo = new (adapter.repository<User>())(adapter, User);
+ * const created = await repo.create(new User({ name: 'Alice' }));
+ *
+ * @mermaid
+ * sequenceDiagram
+ *   participant App
+ *   participant Adapter as TypeORMAdapter
+ *   participant Repo as TypeORMRepository
+ *   participant DS as TypeORM DataSource
+ *
+ *   App->>Adapter: new TypeORMAdapter(opts)
+ *   Adapter->>DS: initialize()
+ *   App->>Adapter: repository()
+ *   Adapter-->>App: TypeORMRepository
+ *   App->>Repo: create(model)
+ *   Repo->>Adapter: prepare/create/revert
+ *   Adapter-->>Repo: Model
+ *   Repo-->>App: Model
+ */
+export declare class TypeORMAdapter extends Adapter<DataSourceOptions, TypeORMQuery, TypeORMFlags, Context<TypeORMFlags>> {
+    private _dataSource?;
+    get dataSource(): DataSource;
+    constructor(options: DataSourceOptions, alias?: string);
+    protected flags<M extends Model>(operation: OperationKeys, model: Constructor<M>, flags: Partial<TypeORMFlags>): Promise<TypeORMFlags>;
+    protected Dispatch(): TypeORMDispatch;
+    repository<M extends Model>(): Constructor<TypeORMRepository<M>>;
+    /**
+     * @description Creates a new Postgres statement for querying
+     * @summary Factory method that creates a new PostgresStatement instance for building queries
+     * @template M - The model type
+     * @return {TypeORMStatement<M, any>} A new PostgresStatement instance
+     */
+    Statement<M extends Model>(): TypeORMStatement<M, any>;
+    /**
+     * @description Creates a new PostgreSQL sequence
+     * @summary Factory method that creates a new PostgreSQLSequence instance for managing sequences
+     * @param {SequenceOptions} options - The options for the sequence
+     * @return {Promise<Sequence>} A promise that resolves to a new Sequence instance
+     */
+    Sequence(options: SequenceOptions): Promise<Sequence>;
+    /**
+     * @description Initializes the adapter by creating indexes for all managed models
+     * @summary Sets up the necessary database indexes for all models managed by this adapter
+     * @return {Promise<void>} A promise that resolves when initialization is complete
+     */
+    initialize(): Promise<void>;
+    /**
+     * @description Creates indexes for the given models
+     * @summary Abstract method that must be implemented to create database indexes for the specified models
+     * @template M - The model type
+     * @param {...Constructor<M>} models - The model constructors to create indexes for
+     * @return {Promise<void>} A promise that resolves when all indexes are created
+     */
+    protected index<M extends Model>(...models: Constructor<M>[]): Promise<void>;
+    /**
+     * @description Executes a raw SQL query against the database
+     * @summary Abstract method that must be implemented to execute raw SQL queries
+     * @template R - The result type
+     * @param {TypeORMQuery} q - The query to execute
+     * @return {Promise<R>} A promise that resolves to the query result
+     */
+    raw<R>(q: TypeORMQuery): Promise<R>;
+    prepare<M extends Model>(model: M, pk: keyof M, child?: boolean): {
+        record: Record<string, any>;
+        id: string;
+        transient?: Record<string, any>;
+    };
+    revert<M extends Model>(obj: Record<string, any>, clazz: string | Constructor<M>, pk: keyof M, id: string | number | bigint, transient?: Record<string, any>): M;
+    /**
+     * @description Creates a new record in the database
+     * @summary Abstract method that must be implemented to create a new record
+     * @param {string} tableName - The name of the table
+     * @param {string|number} id - The ID of the record
+     * @param {Record<string, any>} model - The model to create
+     * @param {...any[]} args - Additional arguments
+     * @return {Promise<Record<string, any>>} A promise that resolves to the created record
+     */
+    create(tableName: string, id: string | number, model: Record<string, any>, ...args: any[]): Promise<Record<string, any>>;
+    /**
+     * @description Reads a record from the database
+     * @summary Abstract method that must be implemented to read a record
+     * @param {string} tableName - The name of the table
+     * @param {string|number} id - The ID of the record
+     * @param {string} pk - primary key colum
+     * @return {Promise<Record<string, any>>} A promise that resolves to the read record
+     */
+    read(tableName: string, id: string | number, pk: string): Promise<Record<string, any>>;
+    /**
+     * @description Updates a record in the database
+     * @summary Abstract method that must be implemented to update a record
+     * @param {string} tableName - The name of the table
+     * @param {string|number} id - The ID of the record
+     * @param {Record<string, any>} model - The model to update
+     * @param {string} pk - Additional arguments
+     * @return A promise that resolves to the updated record
+     */
+    update(tableName: string, id: string | number, model: Record<string, any>, ...args: any[]): Promise<Record<string, any>>;
+    /**
+     * @description Deletes a record from the database
+     * @summary Abstract method that must be implemented to delete a record
+     * @param {string} tableName - The name of the table
+     * @param {string|number} id - The ID of the record
+     * @param {string} pk - Additional arguments
+     * @return A promise that resolves to the deleted record
+     */
+    delete(tableName: string, id: string | number, pk: string, ...args: any[]): Promise<Record<string, any>>;
+    createAll(tableName: string, id: (string | number)[], model: Record<string, any>[], ...args: any[]): Promise<Record<string, any>[]>;
+    readAll(tableName: string, id: (string | number | bigint)[], pk: string, ...args: any[]): Promise<Record<string, any>[]>;
+    updateAll(tableName: string, ids: string[] | number[], model: Record<string, any>[], pk: string, ...args: any[]): Promise<Record<string, any>[]>;
+    deleteAll(tableName: string, ids: (string | number | bigint)[], pk: string, ...args: any[]): Promise<Record<string, any>[]>;
+    /**
+     * @description Parses an error and converts it to a BaseError
+     * @summary Converts various error types to appropriate BaseError subtypes
+     * @param {Error|string} err - The error to parse
+     * @param {string} [reason] - Optional reason for the error
+     * @return {BaseError} The parsed error as a BaseError
+     */
+    parseError(err: Error | string, reason?: string): BaseError;
+    /**
+     * @description Checks if an attribute is reserved
+     * @summary Determines if an attribute name is reserved in PostgreSQL
+     * @param {string} attr - The attribute name to check
+     * @return {boolean} True if the attribute is reserved, false otherwise
+     */
+    protected isReserved(attr: string): boolean;
+    /**
+     * @description Static method to parse an error and convert it to a BaseError
+     * @summary Converts various error types to appropriate BaseError subtypes based on PostgreSQL error codes and messages
+     * @param {Error|string} err - The error to parse
+     * @param {string} [reason] - Optional reason for the error
+     * @return {BaseError} The parsed error as a BaseError
+     * @mermaid
+     * sequenceDiagram
+     *   participant Caller
+     *   participant parseError
+     *   participant ErrorTypes
+     *
+     *   Caller->>parseError: err, reason
+     *   Note over parseError: Check if err is already a BaseError
+     *   alt err is BaseError
+     *     parseError-->>Caller: return err
+     *   else err is string
+     *     Note over parseError: Extract code from string
+     *     alt code matches "duplicate key|already exists"
+     *       parseError->>ErrorTypes: new ConflictError(code)
+     *       ErrorTypes-->>Caller: ConflictError
+     *     else code matches "does not exist|not found"
+     *       parseError->>ErrorTypes: new NotFoundError(code)
+     *       ErrorTypes-->>Caller: NotFoundError
+     *     end
+     *   else err has code property
+     *     Note over parseError: Extract code and reason
+     *   else
+     *     Note over parseError: Use err.message as code
+     *   end
+     *
+     *   Note over parseError: Switch on PostgreSQL error code
+     *   alt code is 23505 (unique_violation)
+     *     parseError->>ErrorTypes: new ConflictError(reason)
+     *     ErrorTypes-->>Caller: ConflictError
+     *   else code is 23503 (foreign_key_violation)
+     *     parseError->>ErrorTypes: new ConflictError(reason)
+     *     ErrorTypes-->>Caller: ConflictError
+     *   else code is 42P01 (undefined_table)
+     *     parseError->>ErrorTypes: new NotFoundError(reason)
+     *     ErrorTypes-->>Caller: NotFoundError
+     *   else code is 42703 (undefined_column)
+     *     parseError->>ErrorTypes: new NotFoundError(reason)
+     *     ErrorTypes-->>Caller: NotFoundError
+     *   else code is 42P07 (duplicate_table)
+     *     parseError->>ErrorTypes: new ConflictError(reason)
+     *     ErrorTypes-->>Caller: ConflictError
+     *   else code is 42P16 (invalid_table_definition)
+     *     parseError->>ErrorTypes: new IndexError(err)
+     *     ErrorTypes-->>Caller: IndexError
+     *   else code matches "ECONNREFUSED"
+     *     parseError->>ErrorTypes: new ConnectionError(err)
+     *     ErrorTypes-->>Caller: ConnectionError
+     *   else
+     *     parseError->>ErrorTypes: new InternalError(err)
+     *     ErrorTypes-->>Caller: InternalError
+     *   end
+     */
+    protected static parseError(err: Error | string, reason?: string): BaseError;
+    static connect(config: DataSourceOptions): Promise<DataSource>;
+    static createDatabase(dataSource: DataSource, dbName: string): Promise<void>;
+    static createNotifyFunction(dataSource: DataSource, user: string): Promise<void>;
+    static deleteDatabase(dataSource: DataSource, dbName: string, user?: string): Promise<void>;
+    static createUser(dataSource: DataSource, dbName: string, user: string, password: string): Promise<void>;
+    static deleteUser(client: DataSource, user: string, admin: string): Promise<void>;
+    private static parseTypeToPostgres;
+    private static parseValidationToPostgres;
+    private static parseRelationsToPostgres;
+    static createTable<M extends Model>(client: DataSource, model: Constructor<M>): Promise<Record<string, TypeORMTableSpec>>;
+    static getCurrentUser(client: DataSource): Promise<string>;
+    static decoration(): void;
+}