From fa2712840a96e9debc31882a42d19297da31d483 Mon Sep 17 00:00:00 2001 From: ethangardner Date: Mon, 6 Jan 2025 09:19:58 -0500 Subject: [PATCH 1/2] add jsdoc comments for database package --- packages/database/src/clients/knex.ts | 18 +++++++++----- .../database/src/clients/kysely/postgres.ts | 7 ++++++ .../database/src/clients/kysely/sqlite3.ts | 24 +++++-------------- packages/database/src/context/file-system.ts | 3 +++ packages/database/src/context/in-memory.ts | 5 ++++ packages/database/src/context/postgres.ts | 3 +++ .../src/management/migrate-database.ts | 11 +++++++++ 7 files changed, 47 insertions(+), 24 deletions(-) diff --git a/packages/database/src/clients/knex.ts b/packages/database/src/clients/knex.ts index 71f393fc7..bf2211581 100644 --- a/packages/database/src/clients/knex.ts +++ b/packages/database/src/clients/knex.ts @@ -9,8 +9,13 @@ const migrationsDirectory = path.resolve( '../../migrations' ); -export const createKnex = (config: Knex.Config): Knex => knex(config); - +/** + * Creates and configures a query builder instance configured for a PostgreSQL database. + * + * @param {string} connectionString - The connection string for the PostgreSQL database. + * @param {boolean} [ssl=false] - Indicates whether SSL should be enabled for the connection. + * If enabled, `rejectUnauthorized` will be set to `false` to allow self-signed certificates. + */ export const getPostgresKnex = ( connectionString: string, ssl: boolean = false @@ -33,10 +38,11 @@ export const getInMemoryKnex = (): Knex => { return getSqlite3Knex(':memory:'); }; -export const getFileSystemKnex = (path: string): Knex => { - return getSqlite3Knex(path); -}; - +/** + * Creates and configures a query builder instance configured for a SQLite database. + * + * @param {string} filename - The path to the SQLite database file. + */ const getSqlite3Knex = (filename: string): Knex => { return knex({ client: 'better-sqlite3', diff --git a/packages/database/src/clients/kysely/postgres.ts b/packages/database/src/clients/kysely/postgres.ts index c6bcc5972..0a11af709 100644 --- a/packages/database/src/clients/kysely/postgres.ts +++ b/packages/database/src/clients/kysely/postgres.ts @@ -3,6 +3,13 @@ import pg from 'pg'; import { type Database } from './types.js'; +/** + * Creates a new Postgres database connection. + * + * @param {string} connectionString - The connection string to connect to the Postgres database. + * @param {boolean} ssl - A boolean indicating whether SSL should be used for the connection. + * If true, SSL is enabled with the option to not reject unauthorized certificates. + */ export const createPostgresDatabase = ( connectionString: string, ssl: boolean diff --git a/packages/database/src/clients/kysely/sqlite3.ts b/packages/database/src/clients/kysely/sqlite3.ts index 88e70077e..d38ceec29 100644 --- a/packages/database/src/clients/kysely/sqlite3.ts +++ b/packages/database/src/clients/kysely/sqlite3.ts @@ -1,27 +1,15 @@ import { Kysely, SqliteDialect } from 'kysely'; -import BetterSqliteDatabase, { +import { type Database as SqliteDatabase, } from 'better-sqlite3'; import { type Database } from './types.js'; -type TestDatabase = { - kysely: Kysely; - sqlite: SqliteDatabase; -}; - -export const createInMemoryDatabase = (): TestDatabase => { - const database = new BetterSqliteDatabase(':memory:'); - return { - kysely: new Kysely({ - dialect: new SqliteDialect({ - database, - }), - }), - sqlite: database, - }; -}; - +/** + * Creates a query builder instance configured to use SQLite as the database dialect. + * + * @param {SqliteDatabase} database - The SQLite database connection or configuration object. + */ export const createSqliteDatabase = (database: SqliteDatabase) => { return new Kysely({ dialect: new SqliteDialect({ diff --git a/packages/database/src/context/file-system.ts b/packages/database/src/context/file-system.ts index 8d7833dc3..52f8169e6 100644 --- a/packages/database/src/context/file-system.ts +++ b/packages/database/src/context/file-system.ts @@ -16,6 +16,9 @@ const migrationsDirectory = path.resolve( '../../migrations' ); +/** + * Provides a context for accessing and managing a SQLite database stored on the filesystem. + */ export class FilesystemDatabaseContext implements DatabaseContext { public readonly engine = 'sqlite'; knex?: Knex; diff --git a/packages/database/src/context/in-memory.ts b/packages/database/src/context/in-memory.ts index 62c85f880..b0dc7ffb5 100644 --- a/packages/database/src/context/in-memory.ts +++ b/packages/database/src/context/in-memory.ts @@ -9,6 +9,11 @@ import { migrateDatabase } from '../management/migrate-database.js'; import { type DatabaseContext } from './types.js'; +/** + * Provides a context for accessing and managing a SQLite database stored in memory. + * + * This context is implemented for testing or temporary use cases where persistence is not required. + */ export class InMemoryDatabaseContext implements DatabaseContext { public readonly engine = 'sqlite'; knex?: Knex; diff --git a/packages/database/src/context/postgres.ts b/packages/database/src/context/postgres.ts index c6658a4bb..02983298c 100644 --- a/packages/database/src/context/postgres.ts +++ b/packages/database/src/context/postgres.ts @@ -9,6 +9,9 @@ import { migrateDatabase } from '../management/migrate-database.js'; import { type DatabaseContext } from './types.js'; import { Pool } from 'pg'; +/** + * Provides a context for accessing and managing a PostgreSQL database. + */ export class PostgresDatabaseContext implements DatabaseContext { public readonly engine = 'postgres'; knex?: Knex; diff --git a/packages/database/src/management/migrate-database.ts b/packages/database/src/management/migrate-database.ts index 0c26637c8..e3fb3f6c3 100644 --- a/packages/database/src/management/migrate-database.ts +++ b/packages/database/src/management/migrate-database.ts @@ -1,5 +1,16 @@ import { type DatabaseContext } from '../context/types.js'; +/** + * Handles database migration operations. + * + * Executes the latest database migrations for the given context and + * returns a function to roll back these migrations if needed. + * + * @param {DatabaseContext} ctx - The database context providing access to + * the database instance and migration utilities. + * + * @returns {Function} A function to roll back the last applied migrations. + */ export const migrateDatabase = async (ctx: DatabaseContext) => { const db = await ctx.getKnex(); await db.migrate.latest(); From b8f4cc5a714522a5d7791d0253beab4278349b3f Mon Sep 17 00:00:00 2001 From: ethangardner Date: Mon, 6 Jan 2025 10:08:39 -0500 Subject: [PATCH 2/2] formatting --- packages/database/src/clients/kysely/sqlite3.ts | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/packages/database/src/clients/kysely/sqlite3.ts b/packages/database/src/clients/kysely/sqlite3.ts index d38ceec29..75e3f9add 100644 --- a/packages/database/src/clients/kysely/sqlite3.ts +++ b/packages/database/src/clients/kysely/sqlite3.ts @@ -1,7 +1,5 @@ import { Kysely, SqliteDialect } from 'kysely'; -import { - type Database as SqliteDatabase, -} from 'better-sqlite3'; +import { type Database as SqliteDatabase } from 'better-sqlite3'; import { type Database } from './types.js';