@grupodiariodaregiao/bunstone 0.7.0 → 0.7.2

package/dist/lib/app-startup.d.ts

@@ -86,6 +86,7 @@ export declare class AppStartup {
     private static buildEffectiveRateLimit;
     private static registerTimeouts;
     private static registerCronJobs;
+    private static invokeScheduledHandler;
     private static registerBullMqWorkers;
     /**
      * Sets up RabbitMQ consumers for every provider that has `@RabbitSubscribe`

package/dist/lib/database/sql-module.d.ts

@@ -1,19 +1,36 @@
 import { SQL } from "bun";
-type ConnectionOptions = {
+type Provider = "postgresql" | "mysql" | "sqlite";
+type BunSqlPoolOptions = Pick<SQL.PostgresOrMySQLOptions, "max" | "maxLifetime" | "connectionTimeout" | "idleTimeout" | "connection" | "tls" | "prepare" | "bigint" | "onconnect" | "onclose" | "path">;
+type BunSqliteClientOptions = Pick<SQL.SQLiteOptions, "readonly" | "create" | "safeIntegers" | "strict">;
+/** Options forwarded by Bunstone to the underlying Bun.SQL client. */
+export type BunSqlClientOptions = Partial<BunSqlPoolOptions & BunSqliteClientOptions>;
+/**
+ * Options accepted by {@link SqlModule.register}.
+ * Only Bunstone-supported settings are allowed.
+ */
+export type SqlModuleOptions = BunSqlClientOptions & {
+    /**
+     * Timezone used for date/time interpretation on the database connection.
+     * Mapped to driver `connection` settings when not provided explicitly.
+     * Defaults to `UTC`.
+     */
+    timezone?: string;
+};
+export type SqlConnectionDetails = {
     host: string;
     port: number;
     username: string;
     password: string;
     database: string;
-    provider: "postgresql" | "mysql" | "sqlite";
-    /**
-     * Timezone used for date/time interpretation on the database connection.
-     * Defaults to 'UTC' to ensure consistent, offset-free date handling.
-     * Set to 'local' to use the process timezone, or any valid tz identifier.
-     */
-    timezone?: string;
+    provider: Provider;
 };
-type Provider = "postgresql" | "mysql" | "sqlite";
+export type ConnectionOptions = SqlConnectionDetails & SqlModuleOptions;
+/** @deprecated Use {@link ConnectionOptions} */
+export type SqlConnectionOptions = ConnectionOptions;
+/** @deprecated Use {@link SqlModuleOptions} */
+export type SqlRegisterOptions = SqlModuleOptions;
+/** Pool-related subset of {@link SqlModuleOptions}. */
+export type SqlPoolOptions = Pick<SqlModuleOptions, "max" | "maxLifetime" | "connectionTimeout" | "idleTimeout">;
 export declare class SqlService {
     query<T = any>(query: string, params?: any[]): Promise<T[]>;
     transaction(queries: Array<{
@@ -21,13 +38,16 @@ export declare class SqlService {
         params?: any[];
     }>): Promise<void>;
     bulkInsert<T = any>(table: string, values: T[]): Promise<void>;
+    private executeQuery;
+    private executeTransaction;
+    private executeBulkInsert;
     private getSqlInstance;
 }
 export declare class SqlModule {
     private static sqlInstance;
     private static provider;
     static register(connection: ConnectionOptions): typeof SqlModule;
-    static register(connection: string, timezone?: string): typeof SqlModule;
+    static register(connection: string, options?: SqlModuleOptions | string): typeof SqlModule;
     static getSqlInstance(): SQL;
     static getProvider(): Provider | undefined;
 }

package/dist/lib/errors/index.d.ts

@@ -75,10 +75,12 @@ export declare class CqrsError extends BunstoneError {
  * Codes:
  * - `BNS-DB-001` – SQL instance not initialised
  * - `BNS-DB-002` – query / transaction execution failed
+ * - `BNS-DB-003` – invalid SqlModule configuration option
  */
 export declare class DatabaseError extends BunstoneError {
-    constructor(message: string, code?: "BNS-DB-001" | "BNS-DB-002", suggestion?: string, context?: Record<string, unknown>, cause?: Error);
+    constructor(message: string, code?: "BNS-DB-001" | "BNS-DB-002" | "BNS-DB-003", suggestion?: string, context?: Record<string, unknown>, cause?: Error);
     static notInitialized(): DatabaseError;
+    static invalidConfig(invalidKeys: string[], allowedKeys: readonly string[]): DatabaseError;
 }
 /**
  * Thrown when BullMQ operations fail.

package/docs/database-sql.md

@@ -43,6 +43,68 @@ OR using a connection string:
 export class AppModule {}
 ```
 
+### Connection options
+
+You can pass a second argument with pool and client settings. Bunstone forwards only the supported options to [Bun.SQL](https://bun.sh/docs/api/sql):
+
+```typescript
+@Module({
+  imports: [
+    SqlModule.register("mysql://user:pass@host:3306/db", {
+      maxLifetime: 25200,
+      connectionTimeout: 30,
+      max: 10,
+      timezone: "UTC",
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+The same options can be combined with the object-style registration:
+
+```typescript
+SqlModule.register({
+  provider: "postgresql",
+  host: "localhost",
+  port: 5432,
+  username: "user",
+  password: "password",
+  database: "my_db",
+  max: 20,
+  idleTimeout: 30,
+});
+```
+
+For backward compatibility, the second argument may still be a timezone string:
+
+```typescript
+SqlModule.register("mysql://user:pass@host/db", "UTC");
+```
+
+#### Supported options (`SqlModuleOptions`)
+
+| Option | Description |
+|---|---|
+| `timezone` | Bunstone helper for date/time handling. Defaults to `UTC`. Mapped to driver `connection` settings. |
+| `max` | Maximum connections in the pool |
+| `maxLifetime` | Maximum connection lifetime in seconds |
+| `connectionTimeout` | Timeout when establishing a connection (seconds) |
+| `idleTimeout` | Close idle connections after N seconds |
+| `connection` | Driver-specific runtime settings (e.g. PostgreSQL `TimeZone`) |
+| `tls` | TLS/SSL configuration |
+| `prepare` | Enable automatic prepared statements |
+| `bigint` | Return out-of-range integers as `BigInt` |
+| `onconnect` | Callback when a connection attempt completes |
+| `onclose` | Callback when a connection closes |
+| `path` | Unix domain socket path |
+| `readonly` | SQLite read-only mode |
+| `create` | SQLite create-if-missing behavior |
+| `safeIntegers` | SQLite safe integer handling |
+| `strict` | SQLite strict mode |
+
+Only the options listed above are accepted. Invalid keys are rejected by TypeScript and also throw `DatabaseError` (`BNS-DB-003`) at runtime.
+
 ## Usage
 
 Once registered, the `SqlService` is globally available. You can inject it into any controller or provider without needing to import `SqlModule` into subsequent modules.

package/docs/pt-BR/database-sql.md

@@ -43,6 +43,68 @@ OU usando uma string de conexão:
 export class AppModule {}
 ```
 
+### Opções de conexão
+
+Você pode passar um segundo argumento com configurações de pool e do client. O Bunstone repassa apenas as opções suportadas para o [Bun.SQL](https://bun.sh/docs/api/sql):
+
+```typescript
+@Module({
+  imports: [
+    SqlModule.register("mysql://user:pass@host:3306/db", {
+      maxLifetime: 25200,
+      connectionTimeout: 30,
+      max: 10,
+      timezone: "UTC",
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+As mesmas opções podem ser usadas no registro via objeto:
+
+```typescript
+SqlModule.register({
+  provider: "postgresql",
+  host: "localhost",
+  port: 5432,
+  username: "user",
+  password: "password",
+  database: "my_db",
+  max: 20,
+  idleTimeout: 30,
+});
+```
+
+Por compatibilidade, o segundo argumento ainda pode ser uma string de timezone:
+
+```typescript
+SqlModule.register("mysql://user:pass@host/db", "UTC");
+```
+
+#### Opções suportadas (`SqlModuleOptions`)
+
+| Opção | Descrição |
+|---|---|
+| `timezone` | Helper do Bunstone para datas/horas. Padrão: `UTC`. Mapeado para `connection` do driver. |
+| `max` | Máximo de conexões no pool |
+| `maxLifetime` | Tempo máximo de vida da conexão em segundos |
+| `connectionTimeout` | Timeout ao estabelecer conexão (segundos) |
+| `idleTimeout` | Fecha conexões ociosas após N segundos |
+| `connection` | Configurações runtime do driver (ex.: `TimeZone` no PostgreSQL) |
+| `tls` | Configuração TLS/SSL |
+| `prepare` | Habilita prepared statements automáticos |
+| `bigint` | Retorna inteiros fora do range como `BigInt` |
+| `onconnect` | Callback ao concluir tentativa de conexão |
+| `onclose` | Callback ao fechar conexão |
+| `path` | Caminho do Unix domain socket |
+| `readonly` | Modo somente leitura (SQLite) |
+| `create` | Comportamento de criação do arquivo (SQLite) |
+| `safeIntegers` | Tratamento seguro de inteiros (SQLite) |
+| `strict` | Modo strict (SQLite) |
+
+Somente as opções listadas acima são aceitas. Chaves inválidas são rejeitadas pelo TypeScript e também lançam `DatabaseError` (`BNS-DB-003`) em runtime.
+
 ## Uso
 
 Depois de registrado, o `SqlService` fica disponível globalmente. Você pode injetá-lo em qualquer controller ou provider sem precisar importar o `SqlModule` nos módulos subsequentes.

package/lib/app-startup.ts

@@ -906,7 +906,11 @@ export class AppStartup {
 					`Scheduling timeout for method: ${timeout.methodName} with delay: ${timeout.delay}ms`,
 				);
 				setTimeout(() => {
-					provider[timeout.methodName]();
+					void AppStartup.invokeScheduledHandler(
+						provider,
+						timeout.methodName,
+						"timeout",
+					);
 				}, timeout.delay);
 			}
 		}
@@ -935,12 +939,40 @@ export class AppStartup {
 			for (const cron of crons) {
 				AppStartup.logger.log(`Scheduling cron for method: ${cron.methodName}`);
 				scheduler.schedule(cron.expression, () => {
-					provider[cron.methodName]();
+					void AppStartup.invokeScheduledHandler(
+						provider,
+						cron.methodName,
+						"cron",
+					);
 				});
 			}
 		}
 	}
 
+	private static async invokeScheduledHandler(
+		provider: Record<string, unknown>,
+		methodName: string,
+		kind: "cron" | "timeout",
+	): Promise<void> {
+		const handler = provider[methodName];
+		if (typeof handler !== "function") {
+			AppStartup.logger.error(
+				`${kind === "cron" ? "Cron" : "Timeout"} job "${methodName}" is not a method on the provider`,
+			);
+			return;
+		}
+
+		try {
+			const result = handler.call(provider);
+			await Promise.resolve(result);
+		} catch (err) {
+			AppStartup.logger.error(
+				`${kind === "cron" ? "Cron" : "Timeout"} job "${methodName}" failed`,
+				err,
+			);
+		}
+	}
+
 	private static registerBullMqWorkers(module: any) {
 		const providersBullMq: Map<any, { name?: string; methodName: string }[]> =
 			Reflect.getMetadata("dip:bullmq", module);

package/lib/database/sql-module.ts

@@ -9,22 +9,133 @@ import { DatabaseError } from "../errors";
 import { Injectable } from "../injectable";
 import { Module } from "../module";
 
-type ConnectionOptions = {
+type Provider = "postgresql" | "mysql" | "sqlite";
+
+type BunSqlPoolOptions = Pick<
+	SQL.PostgresOrMySQLOptions,
+	| "max"
+	| "maxLifetime"
+	| "connectionTimeout"
+	| "idleTimeout"
+	| "connection"
+	| "tls"
+	| "prepare"
+	| "bigint"
+	| "onconnect"
+	| "onclose"
+	| "path"
+>;
+
+type BunSqliteClientOptions = Pick<
+	SQL.SQLiteOptions,
+	"readonly" | "create" | "safeIntegers" | "strict"
+>;
+
+/** Options forwarded by Bunstone to the underlying Bun.SQL client. */
+export type BunSqlClientOptions = Partial<
+	BunSqlPoolOptions & BunSqliteClientOptions
+>;
+
+/**
+ * Options accepted by {@link SqlModule.register}.
+ * Only Bunstone-supported settings are allowed.
+ */
+export type SqlModuleOptions = BunSqlClientOptions & {
+	/**
+	 * Timezone used for date/time interpretation on the database connection.
+	 * Mapped to driver `connection` settings when not provided explicitly.
+	 * Defaults to `UTC`.
+	 */
+	timezone?: string;
+};
+
+export type SqlConnectionDetails = {
 	host: string;
 	port: number;
 	username: string;
 	password: string;
 	database: string;
-	provider: "postgresql" | "mysql" | "sqlite";
-	/**
-	 * Timezone used for date/time interpretation on the database connection.
-	 * Defaults to 'UTC' to ensure consistent, offset-free date handling.
-	 * Set to 'local' to use the process timezone, or any valid tz identifier.
-	 */
-	timezone?: string;
+	provider: Provider;
 };
 
-type Provider = "postgresql" | "mysql" | "sqlite";
+export type ConnectionOptions = SqlConnectionDetails & SqlModuleOptions;
+
+/** @deprecated Use {@link ConnectionOptions} */
+export type SqlConnectionOptions = ConnectionOptions;
+
+/** @deprecated Use {@link SqlModuleOptions} */
+export type SqlRegisterOptions = SqlModuleOptions;
+
+/** Pool-related subset of {@link SqlModuleOptions}. */
+export type SqlPoolOptions = Pick<
+	SqlModuleOptions,
+	"max" | "maxLifetime" | "connectionTimeout" | "idleTimeout"
+>;
+
+type SqlClientInitOptions = Omit<
+	SqlModuleOptions,
+	"url" | "filename" | "timezone"
+>;
+
+const SQL_MODULE_OPTION_KEYS = [
+	"timezone",
+	"max",
+	"maxLifetime",
+	"connectionTimeout",
+	"idleTimeout",
+	"connection",
+	"tls",
+	"prepare",
+	"bigint",
+	"onconnect",
+	"onclose",
+	"path",
+	"readonly",
+	"create",
+	"safeIntegers",
+	"strict",
+] as const satisfies readonly (keyof SqlModuleOptions)[];
+
+const SQL_CONNECTION_DETAIL_KEYS = [
+	"host",
+	"port",
+	"username",
+	"password",
+	"database",
+	"provider",
+] as const satisfies readonly (keyof SqlConnectionDetails)[];
+
+const CONNECTION_CLOSED_CODES = new Set([
+	"ERR_MYSQL_CONNECTION_CLOSED",
+	"ERR_POSTGRES_CONNECTION_CLOSED",
+]);
+
+function assertOnlyAllowedKeys(
+	source: Record<string, unknown>,
+	allowedKeys: readonly string[],
+): void {
+	const invalidKeys = Object.keys(source).filter(
+		(key) => !allowedKeys.includes(key),
+	);
+
+	if (invalidKeys.length > 0) {
+		throw DatabaseError.invalidConfig(invalidKeys, allowedKeys);
+	}
+}
+
+function pickSqlModuleOptions(
+	source: Record<string, unknown>,
+): SqlModuleOptions {
+	assertOnlyAllowedKeys(source, SQL_MODULE_OPTION_KEYS);
+
+	const picked = {} as SqlModuleOptions;
+	for (const key of SQL_MODULE_OPTION_KEYS) {
+		if (key in source) {
+			(picked as Record<string, unknown>)[key] = source[key];
+		}
+	}
+	return picked;
+}
 
 function detectProvider(url: string): Provider {
 	if (url.startsWith("mysql://") || url.startsWith("mysql2://")) {
@@ -45,21 +156,146 @@ function detectProvider(url: string): Provider {
 function buildConnectionConfig(
 	provider: Provider,
 	timezone: string,
-): Record<string, string | boolean | number> | undefined {
+): NonNullable<SQL.PostgresOrMySQLOptions["connection"]> | undefined {
 	if (provider === "postgresql") {
 		return { TimeZone: timezone };
 	}
 	if (provider === "mysql") {
-		// Normalise to MySQL's expected offset format ('+00:00') or named zone
 		const tz = timezone.toLowerCase() === "utc" ? "+00:00" : timezone;
 		return { time_zone: tz };
 	}
 	return undefined;
 }
 
+function normalizeRegisterOptions(
+	options?: SqlModuleOptions | string,
+): SqlModuleOptions {
+	if (typeof options === "string") {
+		return { timezone: options };
+	}
+	if (!options) {
+		return {};
+	}
+
+	return pickSqlModuleOptions(options as Record<string, unknown>);
+}
+
+function buildSqlClientOptions(
+	provider: Provider,
+	timezone: string,
+	options: SqlModuleOptions,
+): SqlClientInitOptions {
+	const { timezone: _timezone, connection: userConnection, ...rest } = options;
+	const driverConnectionConfig = buildConnectionConfig(provider, timezone);
+	const connection = {
+		...driverConnectionConfig,
+		...userConnection,
+	};
+
+	return {
+		...rest,
+		...(Object.keys(connection).length > 0 && { connection }),
+	};
+}
+
+function resolveConnectionUrl(connection: string | ConnectionOptions): string {
+	if (typeof connection === "string") {
+		return connection;
+	}
+
+	return `${connection.provider}://${connection.username}:${connection.password}@${connection.host}:${connection.port}/${connection.database}`;
+}
+
+function resolveProvider(connection: string | ConnectionOptions): Provider {
+	return typeof connection === "string"
+		? detectProvider(connection)
+		: connection.provider;
+}
+
+function resolveTimezone(
+	connection: string | ConnectionOptions,
+	options: SqlModuleOptions,
+): string {
+	if (options.timezone) {
+		return options.timezone;
+	}
+
+	if (typeof connection === "object" && connection.timezone) {
+		return connection.timezone;
+	}
+
+	return "UTC";
+}
+
+function resolveRegisterOptions(
+	connection: string | ConnectionOptions,
+	options?: SqlModuleOptions | string,
+): SqlModuleOptions {
+	const normalized = normalizeRegisterOptions(options);
+
+	if (typeof connection !== "object") {
+		return normalized;
+	}
+
+	assertOnlyAllowedKeys(
+		connection as Record<string, unknown>,
+		[...SQL_CONNECTION_DETAIL_KEYS, ...SQL_MODULE_OPTION_KEYS],
+	);
+
+	const {
+		host: _host,
+		port: _port,
+		username: _username,
+		password: _password,
+		database: _database,
+		provider: _provider,
+		...connectionSqlOptions
+	} = connection;
+
+	return {
+		...pickSqlModuleOptions(connectionSqlOptions as Record<string, unknown>),
+		...normalized,
+	};
+}
+
+function isConnectionClosedError(err: unknown): boolean {
+	return (
+		typeof err === "object" &&
+		err !== null &&
+		"code" in err &&
+		CONNECTION_CLOSED_CODES.has(String((err as { code: unknown }).code))
+	);
+}
+
+async function withConnectionRetry<T>(fn: () => Promise<T>): Promise<T> {
+	try {
+		return await fn();
+	} catch (err) {
+		if (!isConnectionClosedError(err)) {
+			throw err;
+		}
+	}
+
+	return await fn();
+}
+
 @Injectable()
 export class SqlService {
 	async query<T = any>(query: string, params?: any[]): Promise<T[]> {
+		return withConnectionRetry(() => this.executeQuery<T>(query, params));
+	}
+
+	async transaction(
+		queries: Array<{ query: string; params?: any[] }>,
+	): Promise<void> {
+		return withConnectionRetry(() => this.executeTransaction(queries));
+	}
+
+	async bulkInsert<T = any>(table: string, values: T[]): Promise<void> {
+		return withConnectionRetry(() => this.executeBulkInsert(table, values));
+	}
+
+	private async executeQuery<T>(query: string, params?: any[]): Promise<T[]> {
 		const sql = this.getSqlInstance();
 		const tracer = trace.getTracer("bunstone.db");
 		const operation = detectOperation(query);
@@ -91,7 +327,7 @@ export class SqlService {
 		);
 	}
 
-	async transaction(
+	private async executeTransaction(
 		queries: Array<{ query: string; params?: any[] }>,
 	): Promise<void> {
 		const sql = this.getSqlInstance();
@@ -127,7 +363,10 @@ export class SqlService {
 		);
 	}
 
-	async bulkInsert<T = any>(table: string, values: T[]): Promise<void> {
+	private async executeBulkInsert<T>(
+		table: string,
+		values: T[],
+	): Promise<void> {
 		const sql = this.getSqlInstance();
 		const tracer = trace.getTracer("bunstone.db");
 		const span = tracer.startSpan("db.INSERT", {
@@ -176,31 +415,30 @@ export class SqlModule {
 	private static provider: Provider | undefined;
 
 	static register(connection: ConnectionOptions): typeof SqlModule;
-	static register(connection: string, timezone?: string): typeof SqlModule;
-	static register(connection: string | ConnectionOptions, timezone?: string) {
-		const url =
-			typeof connection === "string"
-				? connection
-				: `${connection.provider}://${connection.username}:${connection.password}@${connection.host}:${connection.port}/${connection.database}`;
-
-		const provider =
-			typeof connection === "string"
-				? detectProvider(connection)
-				: connection.provider;
+	static register(
+		connection: string,
+		options?: SqlModuleOptions | string,
+	): typeof SqlModule;
+	static register(
+		connection: string | ConnectionOptions,
+		options?: SqlModuleOptions | string,
+	) {
+		const resolvedOptions = resolveRegisterOptions(connection, options);
+		const url = resolveConnectionUrl(connection);
+		const provider = resolveProvider(connection);
+		const timezone = resolveTimezone(connection, resolvedOptions);
+		const sqlOptions = buildSqlClientOptions(
+			provider,
+			timezone,
+			resolvedOptions,
+		);
 
 		SqlModule.provider = provider;
 
-		const tz =
-			typeof connection === "string"
-				? (timezone ?? "UTC")
-				: (connection.timezone ?? "UTC");
-
-		const connectionConfig = buildConnectionConfig(provider, tz);
-
 		SqlModule.sqlInstance = new SQL({
 			url,
-			...(connectionConfig && { connection: connectionConfig }),
-		});
+			...sqlOptions,
+		} as SQL.Options);
 
 		return SqlModule;
 	}
@@ -236,10 +474,6 @@ function detectOperation(query: string): string {
 	return "QUERY";
 }
 
-/**
- * Strips parameter values from SQL for safe inclusion in telemetry.
- * Keeps the query structure readable without leaking user data.
- */
 function sanitizeSql(query: string): string {
 	return query
 		.replace(/'[^']*'/g, "'?'")

package/lib/errors/index.ts

@@ -244,11 +244,12 @@ export class CqrsError extends BunstoneError {
  * Codes:
  * - `BNS-DB-001` – SQL instance not initialised
  * - `BNS-DB-002` – query / transaction execution failed
+ * - `BNS-DB-003` – invalid SqlModule configuration option
  */
 export class DatabaseError extends BunstoneError {
 	constructor(
 		message: string,
-		code: "BNS-DB-001" | "BNS-DB-002" = "BNS-DB-001",
+		code: "BNS-DB-001" | "BNS-DB-002" | "BNS-DB-003" = "BNS-DB-001",
 		suggestion?: string,
 		context?: Record<string, unknown>,
 		cause?: Error,
@@ -266,6 +267,18 @@ export class DatabaseError extends BunstoneError {
 			].join("\n  "),
 		);
 	}
+
+	static invalidConfig(
+		invalidKeys: string[],
+		allowedKeys: readonly string[],
+	): DatabaseError {
+		return new DatabaseError(
+			`Invalid SqlModule option(s): ${invalidKeys.join(", ")}.`,
+			"BNS-DB-003",
+			`Use only supported options: ${allowedKeys.join(", ")}.`,
+			{ invalidKeys, allowedKeys },
+		);
+	}
 }
 
 // ─── BullMQ ───────────────────────────────────────────────────────────────────

package/package.json

@@ -13,7 +13,7 @@
       "types": "./dist/*.d.ts"
     }
   },
-  "version": "0.7.0",
+  "version": "0.7.2",
   "homepage": "https://bunstone.diario.one/",
   "repository": {
     "url": "https://github.com/diariodaregiao/bunstone.git",