@rapidrest/service-core 1.0.0-beta.1

package/dist/types/database/MongoConnection.d.ts

@@ -0,0 +1,54 @@
+import type { Admin, Db, MongoClient } from "mongodb";
+import { MongoRepository } from "./MongoRepository.js";
+/**
+ * Represents a single named connection to a MongoDB database using the native `mongodb` driver, including the
+ * registry of all model classes assigned to the connection's datastore.
+ *
+ * Note that this class only references the `mongodb` package via type-only imports and is therefore safe to load
+ * when the optional `mongodb` peer dependency is not installed.
+ *
+ * @author Jean-Philippe Steinmetz <rapidrests@gmail.com>
+ */
+export declare class MongoConnection {
+    /** The underlying MongoDB client. */
+    readonly client: MongoClient;
+    /** The database that this connection is bound to. */
+    readonly db: Db;
+    /** The name of the datastore that this connection was created for. */
+    readonly name: string;
+    private connected;
+    private entities;
+    private repos;
+    constructor(name: string, client: MongoClient, db: Db, entities?: Iterable<any>);
+    /** Indicates whether or not the connection is currently active. */
+    get isConnected(): boolean;
+    /** Returns the admin interface of the underlying database. */
+    admin(): Admin;
+    /**
+     * Closes the connection to the database server.
+     */
+    close(): Promise<void>;
+    /**
+     * Returns the name of the collection that records of the given model class are stored in.
+     *
+     * @param clazz The model class to resolve the collection name for.
+     */
+    collectionNameFor(clazz: any): string;
+    /**
+     * Returns the list of all model classes registered with this connection.
+     */
+    get entityClasses(): any[];
+    /**
+     * Returns a repository for performing operations against the collection associated with the given model class.
+     *
+     * @param classOrName The model class, or the name of a registered model class, to retrieve a repository for.
+     */
+    getRepository<T extends object = any>(classOrName: any | string): MongoRepository<T>;
+    /**
+     * Returns a repository for performing operations against the collection associated with the given model class.
+     * This is an alias of `getRepository` provided for compatibility with TypeORM's `DataSource` interface.
+     *
+     * @param classOrName The model class, or the name of a registered model class, to retrieve a repository for.
+     */
+    getMongoRepository<T extends object = any>(classOrName: any | string): MongoRepository<T>;
+}

package/dist/types/database/MongoRepository.d.ts

@@ -0,0 +1,92 @@
+import type { AggregationCursor, Collection, Db, DeleteResult, Document, UpdateResult } from "mongodb";
+/**
+ * Provides a lightweight repository for performing common operations against a single MongoDB collection using the
+ * native `mongodb` driver. Instances of this class are obtained via `MongoConnection.getRepository`.
+ *
+ * Note that this class only references the `mongodb` package via type-only imports and is therefore safe to load
+ * when the optional `mongodb` peer dependency is not installed.
+ *
+ * @author Jean-Philippe Steinmetz <rapidrests@gmail.com>
+ */
+export declare class MongoRepository<T extends Document = any> {
+    /** The database that the underlying collection belongs to. */
+    readonly db: Db;
+    /** The underlying MongoDB collection that operations are performed against. */
+    readonly collection: Collection<T>;
+    /** The model class associated with this repository. */
+    readonly modelClass: any;
+    constructor(db: Db, collection: Collection<T>, modelClass?: any);
+    /** The name of the underlying MongoDB collection. */
+    get collectionName(): string;
+    /**
+     * Executes the given aggregation pipeline against the collection and returns the resulting cursor.
+     *
+     * @param pipeline The aggregation pipeline stages to execute.
+     */
+    aggregate(pipeline: Document[]): AggregationCursor<any>;
+    /**
+     * Drops the entire collection from the database, removing all documents and indexes. Does nothing if the
+     * collection does not exist.
+     */
+    clear(): Promise<void>;
+    /**
+     * Returns the number of documents matching the given filter.
+     *
+     * @param filter The query filter to match documents against.
+     */
+    count(filter?: any): Promise<number>;
+    /**
+     * Deletes all documents matching the given filter.
+     *
+     * @param filter The query filter to match documents against.
+     */
+    deleteMany(filter: any): Promise<DeleteResult>;
+    /**
+     * Deletes the first document matching the given filter.
+     *
+     * @param filter The query filter to match documents against.
+     */
+    deleteOne(filter: any): Promise<DeleteResult>;
+    /**
+     * Returns the list of distinct values of the given field for all documents matching the given filter.
+     *
+     * @param field The name of the document field to return distinct values of.
+     * @param filter The query filter to match documents against.
+     */
+    distinct(field: string, filter?: any): Promise<any[]>;
+    /**
+     * Returns all documents matching the given filter.
+     *
+     * @param filter The query filter to match documents against.
+     */
+    find(filter?: any): Promise<any[]>;
+    /**
+     * Returns the first document matching the given filter.
+     *
+     * @param filter The query filter to match documents against.
+     */
+    findOne(filter: any): Promise<any | null>;
+    /**
+     * Saves the given document to the collection. If the document has an existing `_id` the stored document is
+     * replaced (inserting if missing), otherwise the document is inserted and its newly assigned `_id` is set on
+     * the returned object.
+     *
+     * @param doc The document to save.
+     * @returns The saved document.
+     */
+    save(doc: any): Promise<any>;
+    /**
+     * Updates all documents matching the given filter with the provided update operations.
+     *
+     * @param filter The query filter to match documents against.
+     * @param update The update operations (e.g. `$set`) to apply.
+     */
+    updateMany(filter: any, update: any): Promise<UpdateResult>;
+    /**
+     * Updates the first document matching the given filter with the provided update operations.
+     *
+     * @param filter The query filter to match documents against.
+     * @param update The update operations (e.g. `$set`) to apply.
+     */
+    updateOne(filter: any, update: any): Promise<UpdateResult>;
+}

package/dist/types/database/MongoSchemaSync.d.ts

@@ -0,0 +1,41 @@
+import type { Db } from "mongodb";
+/**
+ * Performs structure synchronization of MongoDB collections based on the persistence metadata of model classes.
+ *
+ * For each collection associated with a model class the following operations are performed:
+ * - The collection is created if it does not already exist.
+ * - Indexes declared via the `@Index` and `@Unique` decorators are created if missing.
+ * - Existing declared indexes whose definition has changed are dropped and re-created.
+ *
+ * The synchronization process never drops collections or data, never modifies the built-in `_id_` index, and never
+ * drops indexes that are not declared by the model class (e.g. shard keys or manually created indexes).
+ *
+ * @author Jean-Philippe Steinmetz <rapidrests@gmail.com>
+ */
+export declare class MongoSchemaSync {
+    private db;
+    private logger;
+    constructor(db: Db, logger?: any);
+    /**
+     * Synchronizes the structure of all collections associated with the given model classes.
+     *
+     * @param entities The list of model classes to synchronize collections for.
+     */
+    synchronize(entities: Iterable<any>): Promise<void>;
+    /**
+     * Synchronizes the structure of a single collection.
+     *
+     * @param name The name of the collection to synchronize.
+     * @param classes The list of model classes whose records are stored in the collection.
+     */
+    private syncCollection;
+    /**
+     * Converts declared index metadata into a desired index specification.
+     */
+    private toDesiredIndex;
+    /**
+     * Determines whether an existing index satisfies the desired index specification. The `background` option is
+     * a build-time hint and is intentionally excluded from the comparison.
+     */
+    private optionsMatch;
+}

package/dist/types/database/NamingUtils.d.ts

@@ -0,0 +1,24 @@
+import "reflect-metadata";
+/**
+ * Converts a string into snake_case.
+ *
+ * Note: This function is intentionally identical in behavior to TypeORM's `snakeCase` utility so that
+ * collection/table names derived from class names remain stable for existing deployments.
+ *
+ * @param str The string to convert.
+ */
+export declare function snakeCase(str: string): string;
+/**
+ * Resolves the name of the database collection (or table) that records of the given model class are stored in.
+ *
+ * The name is resolved using the following rules:
+ * 1. The nearest class in the inheritance chain (starting with `clazz` itself) that specifies an explicit
+ * entity name via the `@Entity(name)` decorator.
+ * 2. Otherwise, the most ancestral class in the inheritance chain that declares its own `@DataStore` binding.
+ * This ensures that `@ChildEntity` subclasses are stored in the same collection as their parent entity
+ * (single collection inheritance).
+ * 3. Otherwise, the snake_case form of the class name.
+ *
+ * @param clazz The model class to resolve the collection name for.
+ */
+export declare function resolveCollectionName(clazz: any): string;

package/dist/types/database/TypeOrmSupport.d.ts

@@ -0,0 +1,20 @@
+import * as typeorm from "typeorm";
+/**
+ * Bridges framework persistence metadata (declared via the decorators in `PersistenceDecorators`) into TypeORM's
+ * global metadata storage so that entity classes using framework decorators behave identically to entity classes
+ * using TypeORM's own decorators. Registrations are deduplicated so that consumer entities decorated with real
+ * TypeORM decorators are never modified.
+ *
+ * @param entities The list of entity classes to register metadata for.
+ */
+export declare function registerFrameworkMetadata(entities: any[]): void;
+/**
+ * Establishes a TypeORM connection for the given SQL datastore configuration. If a connection with the given name
+ * already exists it is reused (and reconnected if necessary).
+ *
+ * @param name The name of the datastore to connect to.
+ * @param datastore The datastore configuration to pass to TypeORM.
+ * @param entities The list of entity classes assigned to this connection.
+ * @param url The connection URL of the database.
+ */
+export declare function connect(name: string, datastore: any, entities: any[], url: string): Promise<typeorm.DataSource>;

package/dist/types/database/index.d.ts

@@ -0,0 +1,6 @@
+export * from "./ConnectionKinds.js";
+export * from "./ConnectionManager.js";
+export * from "./MongoConnection.js";
+export * from "./MongoRepository.js";
+export * from "./MongoSchemaSync.js";
+export * from "./NamingUtils.js";

package/dist/types/decorators/DatabaseDecorators.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Apply this to a property to have the TypeORM `MongoRepository` for the given entity type injected at instantiation.
+ *
+ * @param {any} type The entity type whose repository will be injected.
+ */
+export declare function MongoRepository(type: any): (target: any, propertyKey: string | symbol) => void;
+/**
+ * Apply this to a property to have the TypeORM `Repository` for the given entity type injected at instantiation.
+ *
+ * @param {any} type The entity type whose repository will be injected.
+ */
+export declare function Repository(type: any): (target: any, propertyKey: string | symbol) => void;
+/**
+ * Apply this to a property to have the `Redis` connection injected at instantiation.
+ *
+ * @param {string} name The name of the database connection to inject.
+ */
+export declare function RedisConnection(name: string): (target: any, propertyKey: string | symbol) => void;

package/dist/types/decorators/DocDecorators.d.ts

@@ -0,0 +1,69 @@
+import "reflect-metadata";
+export interface DocumentsData {
+    default?: any;
+    description?: string;
+    example?: any;
+    format?: 'int32' | 'int64' | 'float' | 'double' | 'byte' | 'binary' | 'date' | 'date-time' | 'password' | string;
+    summary?: string;
+    tags?: string[];
+}
+/**
+ * Provides a set of documentation data for a given class, property or function.
+ *
+ * @param value The default value.
+ */
+export declare function Document(value: DocumentsData): (target: any, propertyKey?: string) => void;
+/**
+ * Provides a default value for property of a class.
+ *
+ * @param value The default value.
+ */
+export declare function Default(value: string): (target: any, propertyKey?: string) => void;
+/**
+ * Provides a detailed describing the class, property or function.
+ *
+ * @param value The description of the class, property or function.
+ */
+export declare function Description(value: string): (target: any, propertyKey?: string) => void;
+/**
+ * Provides a example representation of the property or function return value.
+ *
+ * @param value The example value.
+ */
+export declare function Example(value: any): (target: any, propertyKey?: string) => void;
+/**
+ * Describes the underlying format of a class's property.
+ *
+ * @param value The format of the property's property.
+ */
+export declare function Format(value: 'int32' | 'int64' | 'float' | 'double' | 'byte' | 'binary' | 'date' | 'date-time' | 'password' | string): (target: any, propertyKey?: string) => void;
+/**
+ * Provides a brief summary about the class, property or function.
+ *
+ * @param value The summary of the class, property or function.
+ */
+export declare function Summary(value: string): (target: any, propertyKey?: string) => void;
+/**
+ * Provides a list of searchable tags associated with the property or function.
+ *
+ * @param value The list of searchable tags.
+ */
+export declare function Tags(value: string[]): (target: any, propertyKey?: string) => void;
+/**
+ * Stores runtime metadata about the typing information of a function's return value.
+ *
+ * @param types The optional return type(s) of the function. Can represent a single type (e.g. `MyClass`) or a union
+ * of types (e.g. `string | number | null`). When describing a generic type such as a collection this
+ * should be encoded as an array with the templated type as additional elements (e.g. `Array<MyClass>`
+ * becomes `[[Array, MyClass]]`).
+ */
+export declare function Returns(types?: any | any[]): (target: any, propertyKey: string) => void;
+/**
+ * Stores runtime metadata about the typing information of a class property.
+ *
+ * @param types The optional primary type(s) of the property. Can represent a single type (e.g. `MyClass`) or a union
+ * of types (e.g. `string | number | null`). When describing a generic type such as a collection this
+ * should be encoded as an array with the templated type as additional elements (e.g. `Array<MyClass>`
+ * becomes `[[Array, MyClass]]`).
+ */
+export declare function TypeInfo(types?: any | any[]): (target: any, propertyKey: string) => void;

package/dist/types/decorators/EventDecorators.d.ts

@@ -0,0 +1,12 @@
+import "reflect-metadata";
+/**
+ * Apply this to a function that will be called when events arrive for the specified type(s). If no event type is
+ * specified, then the function will be called upon each event that arrives.
+ *
+ * @param type The name or list of names corresponding to events that the function will handle.
+ */
+export declare function OnEvent(type?: string | string[]): (target: any, propertyKey: string, descriptor: PropertyDescriptor) => void;
+/**
+ * Apply this optionally to a abitary class, that has a no argument constructor, to auto register it as an event listener. Will still require add `@OnEvent` to methods
+ */
+export declare function EventListener(): (target: any) => void;

package/dist/types/decorators/ModelDecorators.d.ts

@@ -0,0 +1,80 @@
+import "reflect-metadata";
+import { AccessControlList } from "../security/AccessControlList.js";
+/**
+ * Describes a column registration that must be bridged into TypeORM's metadata storage when (and only when) a SQL
+ * connection is established. Entries are queued here by decorators so that this module does not depend on the
+ * optional `typeorm` package.
+ */
+export interface PendingTypeOrmColumn {
+    target: any;
+    propertyName: string;
+    mode: "regular";
+    options: any;
+}
+/**
+ * The list of column registrations waiting to be bridged into TypeORM's metadata storage. This list is drained by
+ * the TypeORM support module when a SQL connection is created.
+ */
+export declare const pendingTypeOrmColumns: PendingTypeOrmColumn[];
+/**
+ * Indicates that the class is cacheable with the specified TTL.
+ *
+ * @param ttl The time, in seconds, that an object will be cached before being invalidated.
+ */
+export declare function Cache(ttl?: number): (target: any) => void;
+/**
+ * Indicates that a class is a child entity to some parent. Child entities will inherit all datastore configuration
+ * of the parent, including cache settings.
+ */
+export declare function ChildEntity(): <T extends {
+    new (...args: any[]): {};
+}>(constructor: T) => {
+    new (...args: any[]): {
+        /** The class type of the instance. */
+        readonly _type: string;
+    };
+} & T;
+/**
+ * Indicates that the class describes an entity that will be persisted in the datastore with the given name.
+ *
+ * @param datastore The name of the datastore to store records of the decorated class.
+ */
+export declare function DataStore(datastore: string): (target: any) => void;
+/**
+ * Apply this to a property that is considered a unique identifier.
+ */
+export declare function Identifier(target: any, propertyKey: string | symbol): void;
+type PartialACL = Partial<AccessControlList> & Pick<AccessControlList, "records">;
+/**
+ * Apply this to a model class to indicate that it should be protected by the AccessControlList security system.
+ * The `classACL` parameter specifies the default ACL governing access to general operations against the model class
+ * (e.g. create, truncate, find). The `recordACL` parameter indicates whether or not per-record ACLs should be created
+ * for this type in order to govern access to individual record operations (e.g. delete, update, find).
+ *
+ * @param classACL The default access control list to limit access to general class operations.
+ * @param recordACL Set to `true` to create an ACL for each new record of the given type, otherwise set to false. Default
+ * is `false`.
+ */
+export declare function Protect(classACL?: PartialACL, recordACL?: boolean): (target: any) => void;
+/**
+ * Apply this to a property to indicate that the value is a reference to another stored entity.
+ *
+ * @param clazz The class type of the referenced object.
+ */
+export declare function Reference(clazz: any): (target: any, propertyKey: string | symbol) => void;
+/**
+ * Indicates that the class describes an entity that will be persisted in a sharded database collection.
+ *
+ * Note: Only supported by MongoDB.
+ *
+ * @param config The sharding configuration to pass to the database server. Default value is `{ key: { uid: 1 }, unique: false, options: {} }`.
+ */
+export declare function Shard(config?: any): (target: any) => void;
+/**
+ * Indicates that the class will track changes for each document update limited to the specified number of versions.
+ *
+ * @param versions The number of versions that will be tracked for each document change. Set to `-1` to store all
+ * versions. Default value is `-1`.
+ */
+export declare function TrackChanges(versions?: number): (target: any) => void;
+export {};

package/dist/types/decorators/PersistenceDecorators.d.ts

@@ -0,0 +1,117 @@
+import "reflect-metadata";
+/**
+ * The set of options available when declaring a persisted column/property via the `@Column` decorator.
+ */
+export interface ColumnOptions {
+    /** The name of the column in the datastore. Defaults to the property name. */
+    name?: string;
+    /** Set to `true` if the column may store `null`/`undefined` values. */
+    nullable?: boolean;
+    /** Set to `true` if the column is a primary key. */
+    primary?: boolean;
+    /** Set to `true` if the column stores a MongoDB `ObjectId` value. */
+    isObjectId?: boolean;
+}
+/**
+ * The set of options available when declaring a database index via the `@Index` decorator.
+ */
+export interface IndexOptions {
+    /** Set to `true` to enforce that all values of the indexed properties are unique. */
+    unique?: boolean;
+    /** Set to `true` to only index documents in which the indexed properties exist. (MongoDB only) */
+    sparse?: boolean;
+    /** Set to `true` to build the index in the background. (MongoDB only) */
+    background?: boolean;
+    /** The time, in seconds, after which indexed documents will be automatically deleted. (MongoDB only) */
+    expireAfterSeconds?: number;
+}
+/**
+ * Describes a single persisted column/property of a model class.
+ */
+export interface ColumnInfo {
+    /** The name of the class property. */
+    propertyName: string;
+    /** The design type of the property as captured at decoration time. */
+    designType?: any;
+    /** The options that the column was declared with. */
+    options: ColumnOptions;
+}
+/**
+ * Describes a single database index of a model class.
+ */
+export interface IndexInfo {
+    /** The explicit name of the index, if any. */
+    name?: string;
+    /** The list of class properties that make up the index. */
+    columns: string[];
+    /** The options that the index was declared with. */
+    options: IndexOptions;
+}
+/**
+ * Indicates that the decorated property will be persisted as a column/property in the datastore.
+ *
+ * @param options The options describing the column.
+ */
+export declare function Column(options?: ColumnOptions): (target: any, propertyKey: string | symbol) => void;
+/**
+ * Indicates that the decorated property is a primary key column in the datastore.
+ *
+ * @param options The options describing the column.
+ */
+export declare function PrimaryColumn(options?: ColumnOptions): (target: any, propertyKey: string | symbol) => void;
+/**
+ * Declares a database index.
+ *
+ * When applied to a property, creates an index on that single property:
+ * ```
+ * @Index()                            // unnamed index
+ * @Index("myName")                    // named index
+ * @Index({ unique: true })            // unnamed unique index
+ * @Index("myName", { unique: true })  // named unique index
+ * ```
+ *
+ * When applied to a class, creates a compound index across the given properties:
+ * ```
+ * @Index(["firstName", "lastName"])
+ * @Index("fullName", ["firstName", "lastName"], { unique: true })
+ * ```
+ */
+export declare function Index(nameOrOptions?: string | IndexOptions, options?: IndexOptions): PropertyDecorator;
+export declare function Index(fields: string[], options?: IndexOptions): ClassDecorator;
+export declare function Index(name: string, fields: string[], options?: IndexOptions): ClassDecorator;
+/**
+ * Declares a unique constraint. This is shorthand for `@Index` with the `unique` option set to `true` and may be
+ * applied to a property (single-column constraint) or a class (compound constraint).
+ */
+export declare function Unique(name?: string): PropertyDecorator;
+export declare function Unique(fields: string[]): ClassDecorator;
+export declare function Unique(name: string, fields: string[]): ClassDecorator;
+/**
+ * Indicates that the class describes an entity that is persisted to a datastore.
+ *
+ * @param name The name of the collection (or table) that records will be stored in. Defaults to the snake_case
+ * form of the class name.
+ */
+export declare function Entity(name?: string): (target: any) => void;
+/**
+ * Returns the merged list of persisted columns declared across the entire class hierarchy of the given model
+ * class. Columns declared in subclasses override columns of the same property name declared in parent classes.
+ *
+ * @param clazz The model class to retrieve column metadata for.
+ */
+export declare function getColumnMetadata(clazz: any): ColumnInfo[];
+/**
+ * Returns the merged list of indexes declared across the entire class hierarchy of the given model class,
+ * including both property-level and class-level (compound) indexes. Indexes declared in subclasses override
+ * indexes with the same identity (name, or column set when unnamed) declared in parent classes.
+ *
+ * @param clazz The model class to retrieve index metadata for.
+ */
+export declare function getIndexMetadata(clazz: any): IndexInfo[];
+/**
+ * Returns the explicit entity name declared via `@Entity(name)` on the given class or the nearest ancestor that
+ * declares one, otherwise `undefined`.
+ *
+ * @param clazz The model class to retrieve the entity name for.
+ */
+export declare function getEntityName(clazz: any): string | undefined;