@grupodiariodaregiao/bunstone 0.7.1 → 0.7.2

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

@@ -1,38 +1,36 @@
 import { SQL } from "bun";
-export type SqlPoolOptions = {
-    /** Maximum connections in the pool. Bun default: 10 */
-    max?: number;
-    /**
-     * Seconds before closing idle pool connections. Bun default: 0 (no limit).
-     * For MariaDB/MySQL, set below the server `wait_timeout` (often 28800 = 8h).
-     */
-    idleTimeout?: number;
+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 & {
     /**
-     * Max connection lifetime in seconds. Bun default: 0 (no limit).
-     * Forces periodic reconnection before the server drops stale sockets.
+     * Timezone used for date/time interpretation on the database connection.
+     * Mapped to driver `connection` settings when not provided explicitly.
+     * Defaults to `UTC`.
      */
-    maxLifetime?: number;
-    /** Seconds to wait when opening a new connection. Bun default: 30 */
-    connectionTimeout?: number;
+    timezone?: string;
 };
-export type SqlConnectionOptions = SqlPoolOptions & {
+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;
 };
-export type SqlRegisterOptions = SqlPoolOptions & {
-    timezone?: string;
-};
-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<{
@@ -48,9 +46,8 @@ export declare class SqlService {
 export declare class SqlModule {
     private static sqlInstance;
     private static provider;
-    static register(connection: SqlConnectionOptions): typeof SqlModule;
-    static register(connection: string, timezone?: string): typeof SqlModule;
-    static register(connection: string, options: SqlRegisterOptions): typeof SqlModule;
+    static register(connection: ConnectionOptions): 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/database/sql-module.ts

@@ -9,49 +9,134 @@ import { DatabaseError } from "../errors";
 import { Injectable } from "../injectable";
 import { Module } from "../module";
 
-export type SqlPoolOptions = {
-	/** Maximum connections in the pool. Bun default: 10 */
-	max?: number;
-	/**
-	 * Seconds before closing idle pool connections. Bun default: 0 (no limit).
-	 * For MariaDB/MySQL, set below the server `wait_timeout` (often 28800 = 8h).
-	 */
-	idleTimeout?: number;
+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 & {
 	/**
-	 * Max connection lifetime in seconds. Bun default: 0 (no limit).
-	 * Forces periodic reconnection before the server drops stale sockets.
+	 * Timezone used for date/time interpretation on the database connection.
+	 * Mapped to driver `connection` settings when not provided explicitly.
+	 * Defaults to `UTC`.
 	 */
-	maxLifetime?: number;
-	/** Seconds to wait when opening a new connection. Bun default: 30 */
-	connectionTimeout?: number;
+	timezone?: string;
 };
 
-export type SqlConnectionOptions = SqlPoolOptions & {
+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;
 };
 
-export type SqlRegisterOptions = SqlPoolOptions & {
-	timezone?: string;
-};
-
-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://")) {
 		return "mysql";
@@ -71,34 +156,106 @@ 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 pickPoolOptions(
-	source: SqlPoolOptions | undefined,
-): SqlPoolOptions | undefined {
-	if (!source) {
-		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;
 	}
 
-	const pool: SqlPoolOptions = {};
-	if (source.max !== undefined) pool.max = source.max;
-	if (source.idleTimeout !== undefined) pool.idleTimeout = source.idleTimeout;
-	if (source.maxLifetime !== undefined) pool.maxLifetime = source.maxLifetime;
-	if (source.connectionTimeout !== undefined) {
-		pool.connectionTimeout = source.connectionTimeout;
+	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;
 	}
 
-	return Object.keys(pool).length > 0 ? pool : undefined;
+	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 {
@@ -138,10 +295,7 @@ export class SqlService {
 		return withConnectionRetry(() => this.executeBulkInsert(table, values));
 	}
 
-	private async executeQuery<T>(
-		query: string,
-		params?: any[],
-	): Promise<T[]> {
+	private async executeQuery<T>(query: string, params?: any[]): Promise<T[]> {
 		const sql = this.getSqlInstance();
 		const tracer = trace.getTracer("bunstone.db");
 		const operation = detectOperation(query);
@@ -209,7 +363,10 @@ export class SqlService {
 		);
 	}
 
-	private async executeBulkInsert<T>(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", {
@@ -257,51 +414,31 @@ export class SqlModule {
 	private static sqlInstance: SQL;
 	private static provider: Provider | undefined;
 
-	static register(connection: SqlConnectionOptions): typeof SqlModule;
-	static register(connection: string, timezone?: string): typeof SqlModule;
+	static register(connection: ConnectionOptions): typeof SqlModule;
 	static register(
 		connection: string,
-		options: SqlRegisterOptions,
+		options?: SqlModuleOptions | string,
 	): typeof SqlModule;
 	static register(
-		connection: string | SqlConnectionOptions,
-		second?: string | SqlRegisterOptions,
+		connection: string | ConnectionOptions,
+		options?: SqlModuleOptions | 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;
+		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;
 
-		let timezone = "UTC";
-		let poolOptions: SqlPoolOptions | undefined;
-
-		if (typeof connection === "string") {
-			if (typeof second === "string") {
-				timezone = second;
-			} else if (second) {
-				timezone = second.timezone ?? "UTC";
-				poolOptions = pickPoolOptions(second);
-			}
-		} else {
-			timezone = connection.timezone ?? "UTC";
-			poolOptions = pickPoolOptions(connection);
-		}
-
-		const connectionConfig = buildConnectionConfig(provider, timezone);
-		const pool = poolOptions ?? {};
-
 		SqlModule.sqlInstance = new SQL({
 			url,
-			...pool,
-			...(connectionConfig && { connection: connectionConfig }),
-		});
+			...sqlOptions,
+		} as SQL.Options);
 
 		return SqlModule;
 	}
@@ -337,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.1",
+  "version": "0.7.2",
   "homepage": "https://bunstone.diario.one/",
   "repository": {
     "url": "https://github.com/diariodaregiao/bunstone.git",