@e-mc/db

* NodeJS 18.20.5 LTS
* ES2022

General Usage

* Read the Docs

Interface

* View Source

``typescript
import type { DbDataSource } from "./squared";

import type { IHost } from "./index";
import type { ClientDbConstructor, IClientDb } from "./core";
import type { BatchQueryResult, DB_TYPE, ErrorQueryCallback, ExecuteBatchQueryOptions, ExecuteQueryOptions, HandleFailOptions, ProcessRowsOptions, QueryResult, SQL_COMMAND } from "./db";
import type { AuthValue } from "./http";
import type { DbCoerceSettings, DbModule, DbSourceOptions, PoolConfig } from "./settings";

import type { SecureContextOptions } from "node:tls";

interface IDb extends IClientDb {
setCredential(item: DbDataSource): Promise;
getCredential(item: DbDataSource): Record;
hasSource(source: string, ...type: number[]): boolean;
applyCommand(...items: DbDataSource[]): void;
executeQuery(item: V, callback: ErrorQueryCallback): Promise;
executeQuery(item: DbDataSource, sessionKey: string): Promise;
executeQuery(item: DbDataSource, options?: ExecuteQueryOptions | string): Promise;
executeBatchQuery(batch: DbDataSource[], callback: ErrorQueryCallback, outResult?: BatchQueryResult): Promise;
executeBatchQuery(batch: DbDataSource[], sessionKey: string, outResult?: BatchQueryResult): Promise;
executeBatchQuery(batch: DbDataSource[], options?: ExecuteBatchQueryOptions | string, outResult?: BatchQueryResult): Promise;
processRows(batch: DbDataSource[], tasks: Promise[], parallel: boolean): Promise;
processRows(batch: DbDataSource[], tasks: Promise[], options?: ProcessRowsOptions | boolean, outResult?: BatchQueryResult): Promise;
handleFail(err: unknown, item: DbDataSource, options?: HandleFailOptions): boolean;
readTLSCert(value: unknown, cache?: boolean): string;
readTLSConfig(options: SecureContextOptions, cache?: boolean): void;
settingsOf(source: string, name: keyof Omit): unknown;
settingsOf(source: string, name: "coerce", component: keyof DbCoerceSettings): unknown;
settingsKey(source: string, name: keyof Omit): unknown;
settingsKey(source: string, name: "coerce", component: keyof DbCoerceSettings): unknown;
getPoolConfig(source: string, uuidKey?: string): Required | undefined;
get sourceType(): DB_TYPE;
get commandType(): SQL_COMMAND;

/ EventEmitter /
on(event: "db:result", listener: (batch: DbDataSource[], result: BatchQueryResult) => void): this;
on(event: "db:fail", listener: (err: unknown, item: DbDataSource) => void): this;
once(event: "db:result", listener: (batch: DbDataSource[], result: BatchQueryResult) => void): this;
once(event: "db:fail", listener: (err: unknown, item: DbDataSource) => void): this;
emit(event: "db:result", batch: DbDataSource[], result: BatchQueryResult): boolean;
emit(event: "db:fail", err: unknown, item: DbDataSource): boolean;
}

interface DbConstructor extends ClientDbConstructor {
setPoolConfig(value: Record): void;
getPoolConfig(source: string): Required | undefined;
readonly prototype: IDb;
new(module?: DbModule, database?: DbDataSource[], ...args: unknown[]): IDb;
}

interface IDbSourceClient {
DB_SOURCE_NAME: string;
DB_SOURCE_CLIENT: boolean;
DB_SOURCE_TYPE: number;
setCredential(this: IDb, item: DbDataSource): Promise;
executeQuery(this: IDb, item: DbDataSource, options?: ExecuteQueryOptions | string): Promise;
executeBatchQuery(this: IDb, batch: DbDataSource[], options?: ExecuteBatchQueryOptions | string, outResult?: BatchQueryResult): Promise;
checkTimeout?(this: IDbSourceClient, value: number, limit?: number): Promise;
}

interface IDbPool {
client: unknown;
lastAccessed: number;
success: number;
failed: number;
poolKey: string;
uuidKey: AuthValue | null;
add(item: DbDataSource, uuidKey?: string): this;
has(item: DbDataSource): boolean;
getConnection(credential?: unknown): Promise;
remove(): void;
detach(force?: boolean): Promise;
close(): Promise;
isIdle(timeout: number): boolean;
isEmpty(): boolean;
set connected(value: boolean);
get persist(): boolean;
get closed(): boolean;
get closeable(): boolean;
set parent(value: Record);
}

interface DbPoolConstructor {
CACHE_UNUSED: readonly string[];
CACHE_IGNORE: readonly string[];
asString(credential: unknown): string;
canCache(credential: unknown): boolean;
sanitize(credential: unknown): unknown;
removeUUIDKey(credential: unknown): unknown;
findKey(pools: Record, uuidKey: unknown, poolKey: string | undefined, ...items: DbDataSource[]): Record | null;
validateKey(pools: Record, username: string, uuidKey: unknown): [string, Record | null];
checkTimeout(pools: Record, value: number, limit?: number): Promise;
readonly prototype: IDbPool;
new(pool: unknown, poolKey: string, uuidKey?: AuthValue | null): IDbPool;
}
`

Settings

`typescript
import type { DbSourceOptions, PurgeComponent } from "./settings";

interface DbModule {
// handler: "@e-mc/db";
mariadb?: DbStoredCredentials;
mongodb?: DbStoredCredentials;
mssql?: DbStoredCredentials;
mysql?: DbStoredCredentials;
oracle?: DbStoredCredentials;
postgres?: DbStoredCredentials;
redis?: DbStoredCredentials;
settings?: {
broadcast_id?: string | string[];
users?: Record>;
cache_dir?: string;
session_expires?: number;
user_key?: Record;
imports?: StringMap;
purge?: PurgeComponent;
mariadb?: DbSourceOptions;
mongodb?: DbSourceOptions;
mssql?: DbSourceOptions;
mysql?: DbSourceOptions;
oracle?: DbSourceOptions;
postgres?: DbSourceOptions;
redis?: DbSourceOptions;
};
}

type DbStoredCredentials = Record>;
`

$3

`javascript
const Db = require("@e-mc/db"); // Using @pi-r/mongodb

const instance = new Db({
mongodb: {
main: {
server: "localhost:27017",
auth: {
username: "",
password: ""
},
authMechanism: "SCRAM-SHA-1"
}
},
settings: {
mongodb: {
pool: {
max: 10,
idle: 60 * 1000,
queue_max: 4,
queue_idle: 30 * 1000,
timeout: 10 * 1000
},
cache: {
timeout: "1d",
when_empty: false
},
coerce: {
credential: false,
options: true
}
}
}
});
// instance.host = new Host();
instance.init();

const item = {
source: "mongodb",
credential: "main",
table: "demo",
name: "nodejs",
query: {
id: {
"$eq": "1"
}
},
willAbort: true
};
await instance.setCredential(item);

const rows = await instance.executeQuery(item, (err, item) => {
if (err.code === "E11000") {
return true; // throw err;
}
return false; // return [];
});

const [rows1, rows2] = await instance.executeBatchQuery([
{ ...item, usePool: true },
{ ...item, query: { id: { "$eq": "2" } } }
],
{ parallel: true, connectOnce: true }
);
``

References

- https://www.unpkg.com/@e-mc/types@0.13.7/lib/squared.d.ts
- https://www.unpkg.com/@e-mc/types@0.13.7/lib/core.d.ts
- https://www.unpkg.com/@e-mc/types@0.13.7/lib/db.d.ts
- https://www.unpkg.com/@e-mc/types@0.13.7/lib/http.d.ts
- https://www.unpkg.com/@e-mc/types@0.13.7/lib/settings.d.ts

* https://www.npmjs.com/package/@types/node

LICENSE

BSD 3-Clause