@develit-io/backend-sdk 5.4.5

package/dist/index.d.ts

@@ -0,0 +1,330 @@
+import * as drizzle_orm_pg_core from 'drizzle-orm/pg-core';
+import { AnyPgTable } from 'drizzle-orm/pg-core';
+import * as drizzle_orm from 'drizzle-orm';
+import { ExtractTablesWithRelations, DBQueryConfig, BuildQueryResult } from 'drizzle-orm';
+import * as drizzle_orm_sqlite_core from 'drizzle-orm/sqlite-core';
+import { AnySQLiteTable } from 'drizzle-orm/sqlite-core';
+import { StatusCodes, ReasonPhrases } from 'http-status-codes';
+export { ReasonPhrases as InternalResponsePhrase, StatusCodes as InternalResponseStatus } from 'http-status-codes';
+import * as z from 'zod/v4/core';
+import { Queue } from '@cloudflare/workers-types';
+import * as drizzle_kit from 'drizzle-kit';
+import { BatchItem } from 'drizzle-orm/batch';
+import { DrizzleD1Database } from 'drizzle-orm/d1';
+
+declare const base: {
+    id: drizzle_orm.IsPrimaryKey<drizzle_orm.NotNull<drizzle_orm_sqlite_core.SQLiteTextBuilderInitial<"id", [string, ...string[]], number | undefined>>>;
+    createdAt: drizzle_orm.HasDefault<drizzle_orm_sqlite_core.SQLiteTimestampBuilderInitial<"created_at">>;
+    modifiedAt: drizzle_orm.HasDefault<drizzle_orm.HasDefault<drizzle_orm_sqlite_core.SQLiteTimestampBuilderInitial<"modified_at">>>;
+};
+declare const basePostgres: {
+    id: drizzle_orm.IsPrimaryKey<drizzle_orm.NotNull<drizzle_orm_pg_core.PgUUIDBuilderInitial<"id">>>;
+    createdAt: drizzle_orm.NotNull<drizzle_orm.HasDefault<drizzle_orm_pg_core.PgTimestampBuilderInitial<"created_at">>>;
+    modifiedAt: drizzle_orm.HasDefault<drizzle_orm.HasDefault<drizzle_orm_pg_core.PgTimestampBuilderInitial<"modified_at">>>;
+};
+
+type InternalErrorResponseStatus = Exclude<StatusCodes, 200 | 201 | 202 | 203 | 204 | 205 | 206 | 207>;
+interface InternalError {
+    status: InternalErrorResponseStatus;
+    code: string;
+    message: string;
+}
+interface IRPCResponse<T> {
+    status: StatusCodes;
+    message: string;
+    data: T | null | undefined;
+    error: boolean;
+    phrase?: ReasonPhrases;
+}
+interface GatewayResponse<T> {
+    status?: number;
+    message: string;
+    data?: T;
+}
+
+/**
+ * Utility type to infer possible relation includes (`with`) for a given table.
+ * This helps define which relations (one-to-many, many-to-one) can be included in a query.
+ *
+ * @template Tables - The Drizzle ORM schema object.
+ * @template TableName - The table for which relations should be inferred.
+ */
+type IncludeRelation<Tables extends Record<string, unknown>, TableName extends keyof ExtractTablesWithRelations<Tables>> = DBQueryConfig<'one' | 'many', boolean, ExtractTablesWithRelations<Tables>, ExtractTablesWithRelations<Tables>[TableName]>['with'];
+/**
+ * Infers the result type of Drizzle ORM select query with optional relations.
+ * This ensures correct TypeScript inference when querying tables and their relations.
+ *
+ * @template Tables - The Drizzle ORM schema object.
+ * @template TableName - The table for which the query result is being inferred.
+ * @template With - (Optional) Specifies which relations should be included in the result.
+ */
+type InferResultType<Tables extends Record<string, unknown>, TableName extends keyof ExtractTablesWithRelations<Tables>, With extends IncludeRelation<Tables, TableName> | undefined = undefined> = BuildQueryResult<ExtractTablesWithRelations<Tables>, ExtractTablesWithRelations<Tables>[TableName], {
+    with: With;
+}>;
+
+declare const ibanZodSchema: z.$ZodString<unknown>;
+declare const swiftZodSchema: z.$ZodString<unknown>;
+
+interface CommandLogPayload<T = string> {
+    action: T;
+    actorId: string;
+    actorUsername?: string;
+    entityId?: string;
+}
+
+interface CommandItem<TAuditAction = string> {
+    command: BatchItem<'sqlite'>;
+    logPayload: CommandLogPayload<TAuditAction>;
+    id: string;
+}
+
+declare const handleActionResponse: <T>({ error, status, message, data, }: {
+    error: boolean;
+    status: number;
+    message: string;
+    data: T;
+}) => T & {};
+
+type Constructor<T = {}> = abstract new (...args: any[]) => T;
+interface DevelitWorkerMethods {
+    name: string;
+    action: string;
+    fetch(): Promise<Response>;
+    log(data: object, identifier?: string): void;
+    logQueuePush(data: object): void;
+    logQueuePull(data: object): void;
+    logQueueRetries(data: object): void;
+    logInput(data: object): void;
+    logOutput(data: object): void;
+    logError(error: object): void;
+    pushToQueue<T>(queue: Queue, message: T | T[]): Promise<void>;
+    handleInput<T extends z.$ZodType>(args: {
+        input: z.infer<T>;
+        schema: T;
+    }): z.infer<T>;
+    handleAction<TInput, TOutput>(input: {
+        data: TInput;
+        schema: z.$ZodType<TInput>;
+    } | null, options: ActionHandlerOptions<TInput, TOutput>, actionExecution: (validatedInput: TInput | null) => Promise<TOutput>): Promise<IRPCResponse<TOutput>>;
+}
+declare function develitWorker<TWorker extends Constructor>(Worker: TWorker): TWorker & Constructor<DevelitWorkerMethods>;
+
+interface ActionHandlerOptions<TInput, TOutput> {
+    /**
+     * Success message to return in the response
+     * @default "Operation completed successfully."
+     */
+    successMessage?: string;
+    /**
+     * Transform function to modify the input before logging
+     * Useful for removing sensitive data from logs
+     */
+    logInputTransform?: (input: TInput) => object;
+    /**
+     * Transform function to modify the output before logging
+     * Useful for removing sensitive data from logs
+     */
+    logOutputTransform?: (data: TOutput) => object;
+    /**
+     * Skip input validation if true
+     * @default false
+     */
+    skipValidation?: boolean;
+    /**
+     * Skip logging if true
+     * @default false
+     */
+    skipLogging?: boolean;
+}
+/**
+ * Generic action handler that eliminates boilerplate code for service actions
+ *
+ * @template TInput - The input type for the action
+ * @template TOutput - The output type for the action
+ * @param worker - The worker instance (this context)
+ * @param input - The input data for the action
+ * @param options - Configuration options for the handler
+ * @param actionExecution - The actual business logic function
+ * @returns Promise resolving to IRPCResponse<TOutput>
+ */
+declare function handleAction<TInput, TOutput>(worker: DevelitWorkerMethods, input: {
+    data: TInput;
+    schema: z.$ZodType<TInput>;
+} | null, options: ActionHandlerOptions<TInput, TOutput> | undefined, actionExecution: (validatedInput: TInput | null) => Promise<TOutput>): Promise<IRPCResponse<TOutput>>;
+/**
+ * Utility type to extract the validated input type from a schema
+ */
+type ValidatedInput<T extends z.$ZodType> = z.infer<T>;
+/**
+ * Utility type for action execution functions
+ */
+type ActionExecution<TInput, TOutput> = (input: TInput) => Promise<TOutput>;
+
+declare const drizzleConfig: drizzle_kit.Config;
+declare function first<T>(rows: T[]): T | undefined;
+declare function firstOrError<T>(rows: T[]): T;
+declare const uuidv4: () => `${string}-${string}-${string}-${string}-${string}`;
+
+declare const createInternalError: (error: unknown, details?: {
+    status?: InternalErrorResponseStatus;
+    code?: string;
+    message?: string;
+}) => InternalError;
+declare const isInternalError: (error: unknown) => error is InternalError;
+
+declare const RPCResponse: {
+    /**
+     * ✅ Constructs a successful RPC response.
+     *
+     * This method wraps the provided data in a standardized response format,
+     * ensuring consistency across API responses.
+     *
+     * @template T - The type of the response data.
+     * @param message - Response message
+     * @param detail - Optional -> Contains data and status code
+     * @returns An `IRPCResponse<T>` with the provided data and no error.
+     */
+    ok<T>(message: string, detail?: {
+        data?: T;
+        status?: StatusCodes;
+    }): IRPCResponse<T>;
+    /**
+     * ❌ Constructs a generic service error response.
+     *
+     * This method logs the error and returns a standardized error response.
+     *
+     * @template T - The expected response type (typically ignored in errors).
+     * @param error - An `RPCError` containing error details.
+     * @returns An `IRPCResponse<T>` with `null` data and the provided error.
+     */
+    serviceError<T>(error: InternalError): IRPCResponse<T>;
+    /**
+     * ❌ Constructs a validation error response (HTTP 400).
+     *
+     * This is a convenience method for returning validation errors.
+     * It internally delegates to `serviceError()`.
+     *
+     * @template T - The expected response type (typically ignored in errors).
+     * @param error - An `RPCError` representing a validation failure.
+     * @returns An `IRPCResponse<T>` with `null` data and the provided error.
+     */
+    validationError<T>(error: InternalError): IRPCResponse<T>;
+};
+
+/**
+ * A utility function to handle operations and return a standardized result.
+ *
+ * This function wraps the call and ensures that both the resolved value
+ * and any potential errors are captured in a structured tuple format.
+ *
+ * @template T - The type of the expected result.
+ * @returns A call that resolves to a tuple containing:
+ *          - The resolved data (`T | null`) if successful.
+ *          - An `RPCError` object (`RPCError | null`) if an error occurs.
+ */
+type Result<T> = [data: T | null, error: InternalError | null];
+/**
+ * Executes a given promise and returns the result in a structured format.
+ *
+ * Instead of throwing errors, this function catches them and returns
+ * a standardized `RPCError` object, making error handling more predictable.
+ *
+ * @template T - The expected return type of the promise.
+ * @param promise - A promise representing an asynchronous operation.
+ * @returns A promise that resolves to a tuple:
+ *          - `[data, null]` if the operation succeeds.
+ *          - `[null, error]` if the operation fails.
+ */
+declare const useResult: <T>(promise: Promise<T>) => Promise<Result<T>>;
+/**
+ * Executes a given function and returns the result in a structured format.
+ *
+ * Instead of throwing errors, this function catches them and returns
+ * a standardized `RPCError` object, making error handling more predictable.
+ *
+ * @template T - The expected return type of the function.
+ * @param function - A function representing an synchronous operation.
+ * @returns A a tuple:
+ *          - `[data, null]` if the operation succeeds.
+ *          - `[null, error]` if the operation fails.
+ */
+declare const useResultSync: <T>(fn: () => T) => Result<T>;
+
+declare const calculateExponentialBackoff: (attempts: number, baseDelaySeconds: number) => number;
+
+interface AuditLogPayload<T> {
+    action: T;
+    actorId: string;
+    actorUsername?: string;
+    service: string;
+    entityId?: string;
+}
+
+interface Command<TAuditAction = string> {
+    handler: (db: DrizzleD1Database<Record<string, unknown>>) => CommandItem<TAuditAction>;
+}
+type CommandFactory<TParams = void, TAuditAction = string> = TParams extends void ? () => Command<TAuditAction> : (params: TParams) => Command<TAuditAction>;
+declare const defineCommand: <TParams = void, TAuditAction = string>(handler: (db: DrizzleD1Database<Record<string, unknown>>, params: TParams) => {
+    command: BatchItem<"sqlite">;
+    logPayload: CommandLogPayload<TAuditAction>;
+    id: string;
+}) => CommandFactory<TParams, TAuditAction>;
+
+declare class DatabaseTransaction<TAuditAction = string> {
+    private db;
+    private serviceName?;
+    private auditLogWriter?;
+    private commands;
+    private logs;
+    private ids;
+    constructor(db: DrizzleD1Database<Record<string, unknown>>, serviceName?: string | undefined, auditLogWriter?: ((logs: AuditLogPayload<TAuditAction>[], db: DrizzleD1Database<Record<string, unknown>>) => BatchItem<"sqlite">[]) | undefined);
+    enqueue<U extends Command<TAuditAction>, T extends Readonly<U> | Readonly<[U, ...U[]]>>(commands: T): string | string[] | undefined;
+    execute(commandItem: Command<TAuditAction>): Promise<void>;
+    executeAll(): Promise<void>;
+    getLogs(): readonly AuditLogPayload<TAuditAction>[];
+    getIds(): readonly string[];
+    getCommandsCount(): number;
+}
+
+type AuditLogTable = AnySQLiteTable | AnyPgTable;
+type AuditLogWriter<TAuditAction = string> = (logs: AuditLogPayload<TAuditAction>[], db: DrizzleD1Database<Record<string, unknown>>) => BatchItem<'sqlite'>[];
+/**
+ * Creates an audit log writer function that inserts audit logs into a specified table
+ *
+ * @param table - The Drizzle table definition for audit logs
+ * @returns A function that can be passed to DatabaseTransaction constructor
+ *
+ * @example
+ * ```typescript
+ * import { createAuditLogWriter } from '@develit-io/workers-sdk'
+ * import { auditLogsTable } from './schema'
+ *
+ * const auditWriter = createAuditLogWriter(auditLogsTable)
+ *
+ * // Use in initializeDB
+ * this.initializeDB(env.DB, schema, auditWriter)
+ * ```
+ */
+declare function createAuditLogWriter<TAuditAction = string>(table: AuditLogTable): AuditLogWriter<TAuditAction>;
+
+declare const service: (serviceName: string) => <T extends new (...args: any[]) => object>(constructor: T) => {
+    new (...args: any[]): {
+        name: string;
+    };
+} & T;
+
+/**
+ * Method decorator that sets `this.action` to a specific name before method execution.
+ *
+ * This is used to enforce logging context and input validation via `handleActionInput`.
+ */
+declare const action: (name: string) => MethodDecorator;
+
+interface WithRetryCounterOptions {
+    baseDelay: number;
+}
+type AsyncMethod<TArgs extends unknown[] = unknown[], TResult = unknown> = (...args: TArgs) => Promise<TResult>;
+declare function cloudflareQueue<TArgs extends unknown[] = unknown[], TResult = unknown>(options: WithRetryCounterOptions): (target: unknown, propertyKey: string | symbol, descriptor: TypedPropertyDescriptor<AsyncMethod<TArgs, TResult>>) => void;
+
+export { DatabaseTransaction, RPCResponse, action, base, basePostgres, calculateExponentialBackoff, cloudflareQueue, createAuditLogWriter, createInternalError, defineCommand, develitWorker, drizzleConfig, first, firstOrError, handleAction, handleActionResponse, ibanZodSchema, isInternalError, service, swiftZodSchema, useResult, useResultSync, uuidv4 };
+export type { ActionExecution, ActionHandlerOptions, AuditLogWriter, Command, CommandLogPayload, DevelitWorkerMethods, GatewayResponse, IRPCResponse, IncludeRelation, InferResultType, InternalError, InternalErrorResponseStatus, ValidatedInput };