@seedcord/plugins 0.3.3 → 0.4.1

package/dist/index.d.ts

@@ -1,59 +1,45 @@
-import { Plugin, Core, Logger } from 'seedcord';
+import { Plugin, Core, Logger, TypedOmit, TypedConstructor as TypedConstructor$1 } from 'seedcord';
+import mongoose, { Mongoose } from 'mongoose';
 import { TypedConstructor } from '@seedcord/types';
-import mongoose from 'mongoose';
 import { Constructor } from 'type-fest';
+import { PoolConfig, Pool } from 'pg';
+import { KyselyConfig, Kysely, NO_MIGRATIONS, Migration, MigrationInfo } from 'kysely';
+
+/**
+ * Configuration options for MongoDB connection and service loading.
+ */
+interface MongoOptions {
+    /** Directory path containing database service classes */
+    dir: string;
+    /** MongoDB connection URI */
+    uri: string;
+    /** Database name to use */
+    name: string;
+}
 
 /**
  * Registry of available database services.
  *
  * This interface can be augmented via declaration merging to add
- * type-safe service definitions when using the \@DatabaseService and \@DatabaseModel decorator.
+ * type-safe service definitions when using the \@RegisterMongoService and \@RegisterMongoModel decorator.
  *
  * @example
  * ```typescript
- * declare module 'seedcord' {
- *   interface Services {
- *     'user': UserService;
- *     'guild': GuildService;
+ * declare module '@seedcord/plugins' {
+ *   interface MongoServices {
+ *     'user': Users;
+ *     'guild': Guilds;
  *   }
  * }
  * ```
  */
-interface Services {
+interface MongoServices {
 }
 /**
  * Helper type to extract service keys from the Services interface.
  */
-type ServiceKeys = keyof Services;
-
-/**
- * Basic document interface with MongoDB ObjectId field.
- *
- * Represents the minimal structure of a MongoDB document
- * with the required `_id` field.
- */
-interface IDocument {
-    /** MongoDB document identifier */
-    _id: string;
-}
-/**
- * Helper type to extract the type of a document that extends IDocument.
- *
- * @typeParam Doc - The document type extending IDocument
- */
-type TypeOfIDocument<Doc extends IDocument = IDocument> = Doc;
+type MongoServiceKeys = keyof MongoServices;
 
-/**
- * Configuration options for MongoDB connection and service loading.
- */
-interface MongoOptions {
-    /** Directory path containing database service classes */
-    dir: string;
-    /** MongoDB connection URI */
-    uri: string;
-    /** Database name to use */
-    name: string;
-}
 /**
  * MongoDB integration plugin for Seedcord.
  *
@@ -68,9 +54,11 @@ declare class Mongo extends Plugin {
     private readonly uri;
     /**
      * Map of all loaded services.
-     * Keys come from `@DatabaseService('key')`
+     * Keys come from `@RegisterMongoService('key')`
      */
-    readonly services: Services;
+    readonly services: MongoServices;
+    /** Exposed Mongoose instance once `init` completes. */
+    connection: Mongoose;
     constructor(core: Core, options: MongoOptions);
     init(): Promise<void>;
     stop(): Promise<void>;
@@ -78,9 +66,31 @@ declare class Mongo extends Plugin {
     private disconnect;
     private loadServices;
     private isServiceClass;
-    _register<SKey extends keyof Services>(key: SKey, instance: Services[SKey]): void;
+    /**
+     * Register hook used by decorated services.
+     *
+     * @internal
+     */
+    _register<SKey extends keyof MongoServices>(key: SKey, instance: MongoServices[SKey]): void;
 }
 
+/**
+ * Basic document interface with MongoDB ObjectId field.
+ *
+ * Represents the minimal structure of a MongoDB document
+ * with the required `_id` field.
+ */
+interface MongoDocument {
+    /** MongoDB document identifier */
+    _id: string;
+}
+/**
+ * Helper type to extract the type of a document that extends MongoDocument.
+ *
+ * @typeParam Doc - The document type extending MongoDocument
+ */
+type MongoDocumentType<Doc extends MongoDocument = MongoDocument> = Doc;
+
 /**
  * Base class for MongoDB service layers
  *
@@ -90,9 +100,9 @@ declare class Mongo extends Plugin {
  * @typeParam Doc - The document type this service manages
  * @example
  * ```typescript
- * \@DatabaseService('users')
+ * \@RegisterMongoService('users')
  * export class Users extends MongoService<IUser> {
- *   \@DatabaseModel('users')
+ *   \@RegisterMongoModel('users')
  *   public static schema = new mongoose.Schema<IUser>({
  *     username: { type: String, required: true, unique: true }
  *   });
@@ -104,36 +114,15 @@ declare class Mongo extends Plugin {
  * }
  * ```
  */
-declare abstract class MongoService<Doc extends IDocument = IDocument> {
+declare abstract class MongoService<Doc extends MongoDocument = MongoDocument> {
     protected readonly db: Mongo;
     protected readonly core: Core;
     readonly model: mongoose.Model<Doc>;
     constructor(db: Mongo, core: Core);
 }
-/** Constructor type for MongoService classes */
+/** Constructor type for {@link MongoService} classes */
 type MongoServiceConstructor = TypedConstructor<typeof MongoService>;
 
-/**
- * Catches and wraps database operation errors.
- *
- * Automatically wraps non-CustomError exceptions in DatabaseError instances
- * with UUID tracking. Should be applied to database service methods.
- *
- * @typeParam TypeReturn - The return type of the decorated method
- * @param errorMessage - Message to include when wrapping errors
- * @decorator
- * @example
- * ```typescript
- * class UserService extends MongoService<IUser> {
- *   \@DBCatchable('Failed to find user')
- *   async findById(id: string) {
- *     return this.model.findById(id);
- *   }
- * }
- * ```
- */
-declare function DBCatchable<TypeReturn>(errorMessage: string): (_target: unknown, _propertyKey: string, descriptor: TypedPropertyDescriptor<(...args: any[]) => Promise<TypeReturn>>) => void;
-
 declare const ModelMetadataKey: unique symbol;
 /**
  * Associates a Mongoose model with a database service
@@ -147,16 +136,16 @@ declare const ModelMetadataKey: unique symbol;
  * @decorator
  * @example
  * ```typescript
- * \@DatabaseService('users')
+ * \@RegisterMongoService('users')
  * export class Users extends MongoService<IUser> {
- *   \@DatabaseModel('users')
+ *   \@RegisterMongoModel('users')
  *   public static schema = new mongoose.Schema<IUser>({
  *     username: { type: String, required: true, unique: true }
  *   });
  * }
  * ```
  */
-declare function DatabaseModel<TService extends ServiceKeys>(collection: TService): <SchemaObj extends Record<KeyOfSchema, mongoose.Schema>, KeyOfSchema extends keyof SchemaObj & (string | symbol)>(target: SchemaObj, propertyKey: KeyOfSchema) => void;
+declare function RegisterMongoModel<TService extends MongoServiceKeys>(collection: TService): <SchemaObj extends Record<KeyOfSchema, mongoose.Schema>, KeyOfSchema extends keyof SchemaObj & (string | symbol)>(target: SchemaObj, propertyKey: KeyOfSchema) => void;
 
 declare const ServiceMetadataKey: unique symbol;
 /**
@@ -170,14 +159,374 @@ declare const ServiceMetadataKey: unique symbol;
  * @decorator
  * @example
  * ```typescript
- * \@DatabaseService('users')
+ * \@RegisterMongoService('users')
  * export class Users<Doc extends IUser = IUser> extends MongoService<Doc> {
  *   // Some code
  * }
  * ```
  */
-declare function DatabaseService<TService extends ServiceKeys>(key: TService): <DatabaseCtor extends Constructor<unknown> & {
+declare function RegisterMongoService<TService extends MongoServiceKeys>(key: TService): <DatabaseCtor extends Constructor<unknown> & {
     prototype: MongoService;
 }>(ctor: DatabaseCtor) => void;
 
-export { DBCatchable, DatabaseModel, DatabaseService, type IDocument, ModelMetadataKey, Mongo, type MongoOptions, MongoService, type MongoServiceConstructor, type ServiceKeys, ServiceMetadataKey, type Services, type TypeOfIDocument };
+/**
+ * Handles ensuring the target Postgres database exists, creating it if necessary.
+ */
+declare class KpgDatabaseBootstrapper {
+    private readonly logger;
+    private static readonly ADMIN_DB;
+    private static readonly DATABASE_EXISTS_SQL;
+    constructor(logger: Logger);
+    resolveDatabaseName(config: PoolConfig): string | null;
+    resolveDatabaseFromPool(pool: Pool): string | null;
+    ensure(baseConfig: PoolConfig): Promise<void>;
+    private buildAdminConfig;
+    private databaseExists;
+    private createDatabase;
+    private static parseDatabaseName;
+    private static applyDatabaseToConnectionString;
+    private static escapeIdentifier;
+}
+
+/**
+ * Options that describe where migrations live and how the migrator should
+ * behave.
+ */
+interface KpgMigrationsOptions {
+    /** Directory path, single file path, or array of migration files */
+    readonly path: string | string[];
+    /** Allow running migrations even if new ones are inserted out of order */
+    readonly allowUnorderedMigrations?: boolean;
+    /** Custom table name used to track executed migrations */
+    readonly migrationTableName?: string;
+    /** Custom lock table name used by the migrator */
+    readonly migrationLockTableName?: string;
+    /** Schema that contains the migration bookkeeping tables */
+    readonly migrationTableSchema?: string;
+    /** Comparator that determines execution order for migrations */
+    readonly nameComparator?: (nameA: string, nameB: string) => number;
+    /** Behavior when the plugin connects. `true`/`undefined` runs to latest. */
+    readonly onStartup?: boolean | MigrationOptions;
+}
+/**
+ * Configuration options for Postgres connection and service discovery.
+ */
+interface KpgOptions {
+    /** Directory containing service classes. Make sure file(s)/folder(s) are built to `.js` in dist and aren't merged into a single file. */
+    readonly dir: string;
+    /** Migration settings */
+    readonly migrations: KpgMigrationsOptions;
+    /** Optional existing Pool instance or configuration overrides */
+    readonly pool?: Pool | PoolConfig;
+    /** Optional connection string used when a pool config is provided */
+    readonly connectionString?: string;
+    /** Optional SQL statements executed for each new connection */
+    readonly onConnectSQL?: string[];
+    /** Force using insecure SSL*/
+    readonly forceInsecureSSL?: boolean;
+    /** Kysely config (excludes dialect because it's Postgres for this plugin) */
+    readonly kysely?: TypedOmit<KyselyConfig, 'dialect'>;
+}
+
+/**
+ * Type representing a migration function (either `up` or `down`).
+ *
+ * @internal
+ */
+type MigrationFn<TKey extends keyof Migration> = NonNullable<Migration[TKey]>;
+/**
+ * Module exporting both `up` and `down` migration functions.
+ *
+ * @internal
+ */
+interface MigrationModule {
+    up: MigrationFn<'up'>;
+    down: MigrationFn<'down'>;
+}
+/**
+ * Target migration identifier used to indicate no migrations should be run. Uses Kysely's built-in `NO_MIGRATIONS` constant.
+ *
+ * @internal
+ */
+type MigrationTarget = string | typeof NO_MIGRATIONS;
+/**
+ * Behavior configuration for migrations that should run automatically when a
+ * database connection is established.
+ */
+interface MigrationOptions {
+    /** Optional target migration to reach. Defaults to latest if omitted. */
+    readonly target?: MigrationTarget;
+    /** Direction to move along the migration timeline. Defaults to `latest`. */
+    readonly direction?: 'latest' | 'up' | 'down';
+    /** Number of steps to apply when direction is `up` or `down`. */
+    readonly steps?: number;
+}
+/**
+ * Behavior configuration for step-based migrations.
+ */
+interface StepMigrationOptions {
+    /** Number of steps to apply when direction is `up` or `down`. */
+    readonly steps?: number | undefined;
+}
+/**
+ * Context provided to the migration manager for performing migrations.
+ *
+ * @internal
+ */
+interface MigrationManagerContext<Database extends object> {
+    readonly db: Kysely<Database>;
+    readonly logger: Logger;
+    readonly config: KpgMigrationsOptions;
+    readonly baseDir: string;
+}
+
+/**
+ * Migration tooling for KyselyPg.
+ */
+declare class KpgMigrationManager<Database extends object> {
+    private readonly ctx;
+    constructor(ctx: MigrationManagerContext<Database>);
+    migrate(options?: MigrationOptions): Promise<void>;
+    migrateUp(options?: StepMigrationOptions): Promise<void>;
+    migrateDown(options?: StepMigrationOptions): Promise<void>;
+    listMigrations(): Promise<readonly MigrationInfo[]>;
+    private runMigration;
+    private runStepwise;
+    private createMigrator;
+    private getMigrationProvider;
+    private createModuleProvider;
+    private logMigrationFiles;
+    private logPreparedMigrations;
+    private logMigrationResults;
+    private relativePath;
+    private resolvePath;
+    private handleMigrationError;
+    private isMigrationModule;
+}
+
+/**
+ * Namespace interface that gets augmented by individual service packages.
+ *
+ * This interface can be augmented via declaration merging to add
+ * type-safe service definitions when using the `@RegisterKpgService` decorator.
+ *
+ * @example
+ * ```typescript
+ * declare module '@seedcord/plugins' {
+ *   interface KpgServices {
+ *     'users': Users;
+ *   }
+ * }
+ * ```
+ */
+interface KpgServices {
+}
+/**
+ * Union of all registered service keys.
+ */
+type KpgServiceKeys = keyof KpgServices;
+/**
+ * Fallback database shape used when no services have extended the base interface.
+ *
+ * @internal
+ */
+type DefaultKpgDatabase = Record<string, unknown>;
+/**
+ * Fallback service type used while no concrete services are registered.
+ *
+ * @internal
+ */
+type DefaultKpgService = KpgService<DefaultKpgDatabase, string>;
+/**
+ * Either a real service from `KpgServices` or the default service placeholder.
+ *
+ * @internal
+ */
+type AnyKpgService = [KpgServiceKeys] extends [never] ? DefaultKpgService : KpgServices[KpgServiceKeys];
+
+/**
+ * Postgres plugin using Kysely.
+ *
+ * Handles setting up the connection pool, applying migrations, and
+ * registering decorated services so they can be resolved from the core.
+ */
+declare class KyselyPg<Database extends object> extends Plugin {
+    readonly core: Core;
+    private readonly options;
+    readonly logger: Logger;
+    private isInitialised;
+    /** Exposed Kysely instance once `init` completes. */
+    connection: Kysely<Database>;
+    private pool;
+    private migrationManager;
+    private readonly serviceRegistry;
+    private readonly databaseBootstrapper;
+    private databaseName;
+    /**
+     * Map of all services registered with the plugin, keyed by their decorator name.
+     */
+    get services(): KpgServices;
+    constructor(core: Core, options: KpgOptions);
+    /**
+     * Connects to Postgres, runs any startup migrations, and loads decorated services.
+     *
+     * Safe to call multiple times; subsequent calls exit early.
+     */
+    init(): Promise<void>;
+    /**
+     * Tears down the connection pool and clears the migration manager reference.
+     */
+    stop(): Promise<void>;
+    private connect;
+    private disconnect;
+    /**
+     * Runs migrations using the supplied options or defaults to `latest`.
+     *
+     * @param options - Target migration or direction overrides
+     */
+    migrate(options?: MigrationOptions): Promise<void>;
+    /**
+     * Runs a single upwards migration step unless a custom count is provided.
+     *
+     * @param options - Optional configuration for step-based execution
+     */
+    migrateUp(options?: StepMigrationOptions): Promise<void>;
+    /**
+     * Runs a single downwards migration step unless a custom count is provided.
+     *
+     * @param options - Optional configuration for step-based execution
+     */
+    migrateDown(options?: StepMigrationOptions): Promise<void>;
+    /**
+     * Lists every migration the manager knows about along with its execution state.
+     */
+    listMigrations(): Promise<readonly MigrationInfo[]>;
+    /**
+     * Lists unapplied migrations.
+     */
+    listPendingMigrations(): Promise<MigrationInfo[]>;
+    private getMigrationManager;
+    /**
+     * Register hook used by decorated services.
+     *
+     * @internal
+     */
+    _register(key: KpgServiceKeys, instance: AnyKpgService): void;
+    private resolvePool;
+    private createPoolConfig;
+    private registerOnConnectStatements;
+    private testPoolConnection;
+}
+
+/**
+ * Base class for KyselyPg services.
+ *
+ * Provides a small, typed shim around the shared Kysely instance and ensures
+ * that subclasses have been decorated with `@RegisterKpgService`.
+ *
+ * @typeParam Database - The database shape used by Kysely (tables as keys).
+ * @typeParam TTable - The specific table key from `Database` this service works with.
+ *
+ * @example
+ * ```typescript
+ * \@RegisterKpgService('users')
+ * export class UsersService extends KpgService<ImportedDatabaseInterface, 'users'> {
+ *   public async findById(id: string) {
+ *     return this.entity
+ *       .selectFrom(this.table)
+ *       .selectAll().where('id', '=', id)
+ *       .executeTakeFirst();
+ *   }
+ * }
+ *
+ * // Usage inside handlers:
+ * const user = await this.core.db.services.users.findById('abc');
+ * ```
+ */
+declare abstract class KpgService<Database extends object, TTable extends keyof Database & string> {
+    protected readonly kysely: KyselyPg<Database>;
+    protected readonly core: Core;
+    readonly table: TTable;
+    constructor(kysely: KyselyPg<Database>, core: Core);
+    /**
+     * Shared Kysely instance used to interact with the Postgres database.
+     */
+    get db(): Kysely<Database>;
+}
+/** Constructor type for {@link KpgService} classes */
+type KyselyServiceConstructor<Database extends object = object> = TypedConstructor$1<typeof KpgService<Database, keyof Database & string>>;
+
+/**
+ * Discovers and registers Postgres services for the plugin.
+ */
+declare class KpgServiceRegistry<Database extends object> {
+    private readonly plugin;
+    private readonly core;
+    private readonly logger;
+    private readonly services;
+    constructor(plugin: KyselyPg<Database>, core: Core, logger: Logger);
+    get map(): KpgServices;
+    register(key: KpgServiceKeys, instance: AnyKpgService): void;
+    loadFromDirectory(dir: string): Promise<void>;
+    private isServiceClass;
+}
+
+/**
+ * Extra configuration supplied to `@RegisterKpgService`.
+ */
+interface KpgServiceRegistrationOptions {
+    /** Optional override for the table name exposed via the service. Defaults to the provided key. */
+    table?: string;
+}
+
+declare const PgServiceMetadataKey: unique symbol;
+declare const PgTableMetadataKey: unique symbol;
+/**
+ *
+ * Registers a Kysely PG service with the specified key and options.
+ *
+ * Associates a service class with a key for dependency injection.
+ * The service becomes available via `core.db.services[key]`.
+ *
+ * @typeParam TKey - The service key type
+ * @param key - Service key for registration and type-safe access
+ * @param options - Additional registration options
+ * @decorator
+ * @example
+ * ```typescript
+ * \@RegisterKpgService('users', { table: 'app_users' })
+ * export class UsersService extends KpgService<{ users: IUser }, 'users'> {
+ *   // Some code
+ * }
+ * ```
+ *
+ * @see {@link KpgService}
+ */
+declare function RegisterKpgService<TKey extends KpgServiceKeys>(key: TKey, options?: KpgServiceRegistrationOptions): <Ctor extends Constructor<KpgServices[TKey]>>(ctor: Ctor) => void;
+
+/**
+ * Catches and wraps database operation errors.
+ *
+ * Wraps non-CustomError exceptions in DatabaseError instances
+ * with UUID tracking. Should be applied to database service methods.
+ *
+ * @typeParam TypeReturn - The return type of the decorated method
+ * @param errorMessage - Message to include when wrapping errors
+ * @decorator
+ * @example
+ * ```typescript
+ * class UserService extends MongoService<IUser> {
+ *   \@WrapDatabaseError('Failed to find user')
+ *   async findById(id: string) {
+ *     return this.model.findById(id);
+ *   }
+ * }
+ * ```
+ *
+ * @see {@link DatabaseError}
+ * @see {@link CustomError}
+ * @see {@link MongoService}
+ */
+declare function WrapDatabaseError<TypeReturn>(errorMessage: string): (_target: unknown, _propertyKey: string, descriptor: TypedPropertyDescriptor<(...args: any[]) => Promise<TypeReturn>>) => void;
+
+export { type AnyKpgService, type DefaultKpgDatabase, type DefaultKpgService, KpgDatabaseBootstrapper, KpgMigrationManager, type KpgMigrationsOptions, type KpgOptions, KpgService, type KpgServiceKeys, type KpgServiceRegistrationOptions, KpgServiceRegistry, type KpgServices, KyselyPg, type KyselyServiceConstructor, type MigrationFn, type MigrationManagerContext, type MigrationModule, type MigrationOptions, type MigrationTarget, ModelMetadataKey, Mongo, type MongoDocument, type MongoDocumentType, MongoService, type MongoServiceConstructor, type MongoServiceKeys, type MongoServices, PgServiceMetadataKey, PgTableMetadataKey, RegisterKpgService, RegisterMongoModel, RegisterMongoService, ServiceMetadataKey, type StepMigrationOptions, WrapDatabaseError };