@elysiumjs/mnemosyne 0.1.2 → 0.3.1

package/dist/interfaces.d.ts

@@ -0,0 +1,360 @@
+import type { TSchema } from 'elysia';
+/**
+ * Contract for ORM drivers.
+ *
+ * A database driver is responsible for creating connections, managing
+ * transactions, and exposing the raw underlying client.
+ *
+ * @author Axel Nana <axel.nana@workbud.com>
+ * @template TConnection The connection type managed by the driver.
+ * @template TConnectionConfig The configuration used to create a connection.
+ */
+export interface DatabaseDriver<TConnection = unknown, TConnectionConfig = unknown> {
+    /**
+     * Creates a new database connection from the given configuration.
+     * @param config The connection configuration.
+     * @param name The name of the connection, when the driver scopes resources by connection.
+     * @returns A new database connection.
+     */
+    createConnection(config: TConnectionConfig, name?: string): TConnection;
+    /**
+     * Executes a callback within a database transaction.
+     * @param connection The connection to use for the transaction.
+     * @param callback The function to execute within the transaction.
+     * @returns The return value of the callback.
+     */
+    withTransaction<T>(connection: TConnection, callback: (tx: TConnection) => Promise<T>): Promise<T>;
+    /**
+     * Returns the raw underlying client from a connection.
+     * @param connection The connection to extract the raw client from.
+     * @returns The raw client instance.
+     */
+    getRawClient(connection: TConnection): unknown;
+}
+/**
+ * Normalized column metadata for a table.
+ *
+ * Provides an ORM-agnostic description of a column's name, type,
+ * nullability, default status, and primary key status.
+ *
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export interface ColumnMetadata {
+    /**
+     * The column name.
+     */
+    name: string;
+    /**
+     * The normalized data type of the column.
+     */
+    dataType: 'string' | 'number' | 'boolean' | 'date' | 'datetime' | 'json' | 'array' | 'bigint' | 'buffer' | 'uuid';
+    /**
+     * Whether the column allows `NULL` values.
+     */
+    nullable: boolean;
+    /**
+     * Whether the column has a default value.
+     */
+    hasDefault: boolean;
+    /**
+     * Whether the column is a primary key.
+     */
+    isPrimaryKey: boolean;
+}
+/**
+ * Bridges ORM-specific table schemas to framework metadata.
+ *
+ * A model adapter translates between the ORM's internal table
+ * representation and the normalized metadata used by the framework.
+ *
+ * @author Axel Nana <axel.nana@workbud.com>
+ * @template TTable The ORM-specific table type.
+ */
+export interface ModelAdapter<TTable = unknown> {
+    /**
+     * Returns the name of the given table.
+     * @param table The table to get the name of.
+     * @returns The table name.
+     */
+    getTableName(table: TTable): string;
+    /**
+     * Returns the normalized column metadata for the given table.
+     * @param table The table to extract columns from.
+     * @returns An array of column metadata.
+     */
+    getColumns(table: TTable): ColumnMetadata[];
+    /**
+     * Creates a tenant-scoped copy of the given table.
+     * @param table The original table.
+     * @param tenant The tenant identifier.
+     * @returns A new table scoped to the given tenant.
+     */
+    createTenantTable(table: TTable, tenant: string): TTable;
+}
+/**
+ * Contract for tenancy strategies.
+ *
+ * A tenancy strategy determines how tables and connections are
+ * scoped to a specific tenant.
+ *
+ * @author Axel Nana <axel.nana@workbud.com>
+ * @template TTable The ORM-specific table type.
+ * @template TConnection The connection type used by the strategy.
+ */
+export interface TenancyStrategy<TTable = unknown, TConnection = unknown> {
+    /**
+     * The tenancy mode identifier (e.g. `'schema'`, `'rls'`).
+     */
+    readonly mode: string;
+    /**
+     * Resolves a table to its tenant-scoped equivalent.
+     * @param table The original table.
+     * @param tenant The tenant identifier.
+     * @returns The tenant-scoped table.
+     */
+    resolveTable(table: TTable, tenant: string): TTable;
+    /**
+     * Executes a callback with tenant-level isolation applied to the connection.
+     * @param connection The database connection.
+     * @param tenant The tenant identifier.
+     * @param callback The function to execute within the isolated context.
+     * @returns The return value of the callback.
+     */
+    withIsolation<T>(connection: TConnection, tenant: string, callback: () => Promise<T>): Promise<T>;
+}
+/**
+ * Contract for database query cache strategies.
+ *
+ * Implementations are responsible for storing, retrieving, and
+ * invalidating cached query results.
+ *
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export interface DatabaseCacheStrategy {
+    /**
+     * Retrieves a cached query result by key.
+     * @param key The cache key.
+     * @returns The cached result, or `undefined` if not found.
+     */
+    get(key: string): Promise<unknown[] | undefined>;
+    /**
+     * Stores a query result in the cache.
+     * @param key The cache key.
+     * @param response The query result to cache.
+     * @param tables The tables involved in the query.
+     * @param config Optional cache configuration.
+     */
+    put(key: string, response: unknown[], tables: string[], config?: {
+        ttl?: number;
+    }): Promise<void>;
+    /**
+     * Invalidates cached entries affected by a mutation.
+     * @param params The tables and/or tags affected by the mutation.
+     */
+    onMutate(params: {
+        tables?: string[];
+        tags?: string[];
+    }): Promise<void>;
+}
+/**
+ * Configuration for database query caching.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export interface DatabaseCacheConfig {
+    /**
+     * Whether caching is enabled.
+     */
+    enabled?: boolean;
+    /**
+     * The default TTL for cached data, in seconds. Drivers apply it to every cached result that
+     * does not set its own expiry.
+     * @default 60
+     */
+    ttl?: number;
+    /**
+     * The caching strategy.
+     * - `'explicit'`: Only cache queries that explicitly opt in.
+     * - `'all'`: Cache all queries automatically.
+     */
+    strategy?: 'explicit' | 'all';
+    /**
+     * The storage engine to use for the cache.
+     */
+    storage?: 'redis' | 'memory';
+    /**
+     * A prefix for every cache key, before the connection name. Set it when several applications
+     * or environments share one cache store, so that connections with the same name but different
+     * databases do not share results.
+     * @default ''
+     */
+    prefix?: string;
+}
+/**
+ * Database primary column type.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export type IdType = number | string;
+/**
+ * ORM-agnostic CRUD repository contract.
+ *
+ * Provides a standard interface for common database operations
+ * regardless of the underlying ORM implementation.
+ *
+ * @author Axel Nana <axel.nana@workbud.com>
+ * @template TSelect The type returned by select queries.
+ * @template TInsert The type needed by insert queries.
+ * @template TUpdate The type needed by update queries.
+ * @template TId The primary key type.
+ */
+export interface RepositoryInterface<TSelect, TInsert, TUpdate, TId extends IdType = string> {
+    /**
+     * Retrieves all the records in the database.
+     * @returns All the records in the database.
+     */
+    all(): Promise<TSelect[]>;
+    /**
+     * Retrieves a paginated subset of the records in the database.
+     * @param count The number of records per page.
+     * @param page The page number to retrieve.
+     * @returns A paginated response containing the records and the total count.
+     */
+    paginate(count: number, page: number): Promise<{
+        page: number;
+        data: TSelect[];
+        total: number;
+    }>;
+    /**
+     * Retrieves a record by its id.
+     * @param id The id of the record to retrieve.
+     * @returns The record with the given id, or `null` if not found.
+     */
+    find(id: TId): Promise<TSelect | null>;
+    /**
+     * Finds the first record with a column matching the given value.
+     * @param column The column to filter by.
+     * @param value The value the column should match.
+     * @returns The first record with a column matching the given value, or `null`.
+     */
+    findBy<TKey extends keyof TSelect>(column: TKey, value: TSelect[TKey]): Promise<TSelect | null>;
+    /**
+     * Inserts a new record in the database.
+     * @param data The data to insert.
+     * @returns The inserted record.
+     */
+    insert(data: TInsert): Promise<TSelect>;
+    /**
+     * Updates a record in the database.
+     * @param id The id of the record to update.
+     * @param data The data to update.
+     * @returns The updated record, or `null` if no record has that id.
+     */
+    update(id: TId, data: TUpdate): Promise<TSelect | null>;
+    /**
+     * Updates all the records in the database.
+     * @param data The data to update.
+     * @returns The updated records.
+     */
+    updateAll(data: TUpdate): Promise<TSelect[]>;
+    /**
+     * Deletes a record from the database.
+     * @param id The ID of the record to delete.
+     * @returns The deleted record, or `null` if no record has that id.
+     */
+    delete(id: TId): Promise<TSelect | null>;
+    /**
+     * Deletes all the records from the database.
+     * @returns All the deleted records.
+     */
+    deleteAll(): Promise<TSelect[]>;
+    /**
+     * Checks if a record exists in the database.
+     * @param id The ID of the record to check.
+     * @returns `true` if the record exists, `false` otherwise.
+     */
+    exists(id: TId): Promise<boolean>;
+}
+/**
+ * Shape of a model class.
+ *
+ * Describes the static interface that a model class must expose,
+ * including inferred types, table metadata, and validation schemas.
+ *
+ * @author Axel Nana <axel.nana@workbud.com>
+ * @template TSelect The type returned by select queries.
+ * @template TInsert The type needed by insert queries.
+ * @template TUpdate The type needed by update queries.
+ * @template TTable The ORM-specific table type.
+ */
+export type ModelClass<TSelect = unknown, TInsert = unknown, TUpdate = unknown, TTable = unknown> = {
+    /**
+     * The data type returned by select queries.
+     */
+    readonly $inferSelect: TSelect;
+    /**
+     * The data type needed by insert queries.
+     */
+    readonly $inferInsert: TInsert;
+    /**
+     * The data type needed by update queries.
+     */
+    readonly $inferUpdate: TUpdate;
+    /**
+     * The ORM-specific table schema wrapped by this model.
+     */
+    readonly table: TTable;
+    /**
+     * The name of the table wrapped by the model.
+     */
+    readonly tableName: string;
+    /**
+     * The table columns configuration.
+     */
+    readonly columns: Record<string, unknown>;
+    /**
+     * The validation schema for creating records.
+     */
+    readonly insertSchema: TSchema;
+    /**
+     * The validation schema for updating records.
+     */
+    readonly updateSchema: TSchema;
+    /**
+     * The validation schema for selecting records.
+     */
+    readonly selectSchema: TSchema;
+    /**
+     * Whether the model supports tenancy.
+     */
+    readonly supportTenancy: boolean;
+    /**
+     * Creates a new instance of the model.
+     * @param args The arguments to pass to the constructor.
+     * @returns A new instance of the model.
+     */
+    new (...args: unknown[]): unknown;
+};
+/**
+ * Shape of a repository class.
+ *
+ * Describes the static interface that a repository class must expose,
+ * including the associated model and connection name.
+ *
+ * @author Axel Nana <axel.nana@workbud.com>
+ * @template TModel The model class type wrapped by the repository.
+ */
+export type RepositoryClass<TModel extends ModelClass = ModelClass> = {
+    /**
+     * The model class wrapped by this repository.
+     */
+    readonly Model: TModel;
+    /**
+     * The database connection name to use in the repository.
+     */
+    readonly connection: string;
+    /**
+     * Creates a new instance of the repository.
+     * @param args The arguments to pass to the constructor.
+     * @returns A new repository instance.
+     */
+    new (...args: unknown[]): RepositoryInterface<TModel['$inferSelect'], TModel['$inferInsert'], TModel['$inferUpdate']>;
+};

package/dist/keyv-redis.d.ts

@@ -0,0 +1,88 @@
+import type { KeyvStoreAdapter } from 'cacheable';
+import type { KeyvEntry, StoredData } from 'keyv';
+import { EventEmitter } from 'node:events';
+/**
+ * Keyv adapter for redis. This adapter is based on the Bun's Redis client.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export declare class KeyvRedis extends EventEmitter implements KeyvStoreAdapter {
+    #private;
+    constructor(props: {
+        /**
+         * The Redis connection to use.
+         */
+        connection: string;
+        /**
+         * Namespace for the connection.
+         */
+        namespace?: string;
+        /**
+         * Separator to use between namespace and key.
+         */
+        keyPrefixSeparator?: string;
+        /**
+         * Number of keys to delete in a single batch.
+         */
+        clearBatchSize?: number;
+        /**
+         * Use UNLINK instead of DEL to delete keys. UNLINK frees memory in the background (Redis 4+).
+         */
+        useUnlink?: boolean;
+        /**
+         * Whether to allow clearing all keys when no namespace is set.
+         * If set to true and no namespace is set, iterate() will return all keys.
+         * Defaults to `false`.
+         */
+        noNamespaceAffectsAll?: boolean;
+    });
+    /**
+     * Resolves the Redis client on first use. The async path is always safe, even when the
+     * Redis module has not been initialised yet (lazy boot).
+     */
+    protected getClient(): Promise<Bun.RedisClient>;
+    /**
+     * Get the options for the adapter.
+     */
+    get opts(): {
+        namespace: string | undefined;
+        keyPrefixSeparator: string;
+        clearBatchSize: number;
+        noNamespaceAffectsAll: boolean;
+        dialect: string;
+        url: string;
+    };
+    /**
+     * Gets the namespace for the adapter. If undefined, it will not use a namespace including keyPrefixing.
+     * @default undefined
+     */
+    get namespace(): string | undefined;
+    /**
+     * Sets the namespace for the adapter. If undefined, it will not use a namespace including keyPrefixing.
+     */
+    set namespace(value: string | undefined);
+    get<Value>(key: string): Promise<StoredData<Value> | undefined>;
+    set(key: string, value: any, ttl?: number): Promise<void>;
+    setMany(values: Array<KeyvEntry>): Promise<void>;
+    delete(key: string): Promise<boolean>;
+    clear(): Promise<void>;
+    has(key: string): Promise<boolean>;
+    hasMany(keys: string[]): Promise<boolean[]>;
+    getMany<Value>(keys: string[]): Promise<Array<StoredData<Value | undefined>>>;
+    disconnect(): Promise<void>;
+    deleteMany(keys: string[]): Promise<boolean>;
+    iterator<Value>(namespace?: string): AsyncGenerator<Array<string | Awaited<Value> | undefined>, void>;
+    /**
+     * Helper function to create a key with a namespace.
+     * @param key The key to prefix.
+     * @param namespace The namespace to prefix the key with.
+     * @returns The key with the namespace such as 'namespace::key'.
+     */
+    createKeyPrefix(key: string, namespace?: string): string;
+    /**
+     * Helper function to remove the namespace from a key.
+     * @param key The key to remove the namespace from.
+     * @param namespace The namespace to remove from the key.
+     * @returns The key without the namespace.
+     */
+    getKeyWithoutPrefix(key: string, namespace?: string): string;
+}

package/dist/mnemosyne.module.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Configuration of the {@link MnemosyneModule}.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export type MnemosyneModuleConfig = {
+    cache: {
+        /** The Redis-backed cache. Set to `false` to not provide `Cache.redis`. */
+        redis?: {
+            /** The name of the Redis connection to use. */
+            connection: string;
+        } | false;
+        /** The memory cache. Set to `false` to not provide `Cache.memory`. */
+        memory?: {
+            /** The default TTL of entries, in milliseconds. */
+            ttl: number;
+            /** The maximum number of entries kept. */
+            lruSize: number;
+        } | false;
+    };
+};
+declare const MnemosyneModule_base: (abstract new () => {
+    readonly config: MnemosyneModuleConfig;
+    onInit(): Promise<void> | void;
+    onDestroy(): Promise<void> | void;
+    onServe(_app: import("elysia").default<any>): Promise<void> | void;
+}) & {
+    readonly config: string;
+    with(config: Partial<MnemosyneModuleConfig> | (() => Partial<MnemosyneModuleConfig> | Promise<Partial<MnemosyneModuleConfig>>)): import("@elysiumjs/core").ConfiguredModule<MnemosyneModuleConfig>;
+    resolveConfig(input?: Partial<MnemosyneModuleConfig> | undefined): MnemosyneModuleConfig;
+    register<TConfig_1 = any>(props?: import("@elysiumjs/core").ModuleProps<TConfig_1>): (target: import("@elysiumjs/core").ModuleClass) => void;
+    configurable<TConfig extends object>(options?: {
+        defaults?: Partial<TConfig>;
+        required?: (keyof TConfig)[];
+    }): any;
+};
+/**
+ * Provides the caches as the global services `mnemosyne.cache.redis` and
+ * `mnemosyne.cache.memory`. Tenancy config and strategy, and database connections, are
+ * registered by the database driver modules.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export declare class MnemosyneModule extends MnemosyneModule_base {
+}
+export {};

package/dist/model.d.ts

@@ -0,0 +1,68 @@
+import type { ColumnMetadata, ModelAdapter } from './interfaces';
+/**
+ * Creates a validation schema from normalized column metadata.
+ * @author Axel Nana <axel.nana@workbud.com>
+ * @param columns The column metadata to create the schema from.
+ * @param options The schema generation options.
+ * @returns A validation schema based on the given columns.
+ */
+export declare const createSchemaFromModel: (columns: ColumnMetadata[], { mode }?: {
+    mode?: 'create' | 'update' | 'select';
+}) => import("@sinclair/typebox").TObject<{}>;
+/**
+ * Mixin used to create a new abstract model class.
+ * @author Axel Nana <axel.nana@workbud.com>
+ * @template TTable The ORM-specific table type.
+ * @template TColumns The table columns configuration type.
+ * @param tableName The name of the table.
+ * @param columns The table columns configuration.
+ * @param adapter The model adapter for the ORM.
+ * @param baseTable The base ORM table instance.
+ */
+export declare const AbstractModel: <TTable, TColumns extends Record<string, unknown>>(tableName: string, columns: TColumns, adapter: ModelAdapter<TTable>, baseTable: TTable) => {
+    new (): {};
+    /**
+     * The data type returned by the select queries.
+     */
+    readonly $inferSelect: unknown;
+    /**
+     * The data type needed by the insert queries.
+     */
+    readonly $inferInsert: unknown;
+    /**
+     * The data type needed by the update queries.
+     */
+    readonly $inferUpdate: unknown;
+    /**
+     * The ORM-specific table schema wrapped by this model.
+     * Will be automatically resolved to a tenant-scoped table when tenancy is active.
+     */
+    get table(): TTable;
+    /**
+     * The name of the table wrapped by the model.
+     */
+    readonly tableName: string;
+    /**
+     * The table columns configuration.
+     */
+    readonly columns: TColumns;
+    /**
+     * The validation schema for creating records.
+     */
+    readonly insertSchema: import("@sinclair/typebox").TObject<{}>;
+    /**
+     * The validation schema for updating records.
+     */
+    readonly updateSchema: import("@sinclair/typebox").TObject<{}>;
+    /**
+     * The validation schema for selecting records.
+     */
+    readonly selectSchema: import("@sinclair/typebox").TObject<{}>;
+    /**
+     * Whether the model supports tenancy.
+     *
+     * Set it to `true` if the model supports tenancy. This means that the model will be
+     * wrapped by the tenancy strategy when the current tenant is not `public`.
+     */
+    readonly supportTenancy: boolean;
+};

package/dist/repository.d.ts

@@ -0,0 +1,96 @@
+import type { AbstractDatabase } from './database';
+import type { IdType, ModelClass } from './interfaces';
+/**
+ * Mixin used to create a new abstract repository class over a model.
+ *
+ * All CRUD methods are abstract and must be implemented by driver-specific
+ * subclasses.
+ *
+ * @author Axel Nana <axel.nana@workbud.com>
+ * @template TModel The type of the model class wrapped by the repository.
+ * @template TConnection The database connection type.
+ * @param model The model class wrapped by the repository.
+ * @param database The database manager instance.
+ */
+export declare const AbstractRepository: <TModel extends ModelClass, TConnection>(model: TModel, database: AbstractDatabase<TConnection, unknown>) => (abstract new () => {
+    /**
+     * The database connection used by this repository.
+     */
+    get db(): TConnection;
+    /**
+     * Retrieves all the records in the database.
+     * @returns All the records in the database.
+     */
+    all(): Promise<TModel["$inferSelect"][]>;
+    /**
+     * Get a paginated subset of the records in the database.
+     * @param count The number of records to retrieve per page.
+     * @param page The page number to retrieve.
+     * @returns A paginated response containing the records and the total number of records.
+     */
+    paginate(count: number, page?: number): Promise<{
+        page: number;
+        data: TModel["$inferSelect"][];
+        total: number;
+    }>;
+    /**
+     * Retrieves a record by its id.
+     * @param id The id of the record to retrieve.
+     * @returns The record with the given id, or `null` if not found.
+     */
+    find(id: IdType): Promise<TModel["$inferSelect"] | null>;
+    /**
+     * Finds the first record with a column matching the given value.
+     * @param column The column to filter by.
+     * @param value The value the column should match.
+     * @returns The first record with a column matching the given value.
+     */
+    findBy<TKey extends keyof TModel["$inferSelect"]>(column: TKey, value: TModel["$inferSelect"][TKey]): Promise<TModel["$inferSelect"] | null>;
+    /**
+     * Inserts a new record in the database.
+     * @param data The data to insert.
+     * @returns The inserted record.
+     */
+    insert(data: TModel["$inferInsert"]): Promise<TModel["$inferSelect"]>;
+    /**
+     * Updates a record in the database.
+     * @param id The id of the record to update.
+     * @param data The data to update.
+     * @returns The updated record, or `null` if no record has that id.
+     */
+    update(id: IdType, data: TModel["$inferUpdate"]): Promise<TModel["$inferSelect"] | null>;
+    /**
+     * Updates all the records in the database.
+     * @param data The data to update.
+     * @returns The updated records.
+     */
+    updateAll(data: TModel["$inferUpdate"]): Promise<TModel["$inferSelect"][]>;
+    /**
+     * Deletes a record from the database.
+     * @param id The ID of the record to delete.
+     * @returns The deleted record, or `null` if no record has that id.
+     */
+    delete(id: IdType): Promise<TModel["$inferSelect"] | null>;
+    /**
+     * Deletes all the records from the database.
+     * @returns All the deleted records.
+     */
+    deleteAll(): Promise<TModel["$inferSelect"][]>;
+    /**
+     * Checks if a record exists in the database.
+     * @param id The ID of the record to check.
+     * @returns True if the record exists, false otherwise.
+     */
+    exists(id: IdType): Promise<boolean>;
+}) & {
+    /**
+     * The model class wrapped by this repository.
+     */
+    readonly Model: TModel;
+    /**
+     * The database connection name to use.
+     *
+     * Update this value to change the database connection used by this repository.
+     */
+    readonly connection: string;
+};