@rapidrest/service-core 1.0.0-beta.1

package/dist/types/models/ModelUtils.d.ts

@@ -0,0 +1,166 @@
+import type { Repository } from "typeorm";
+import { MongoRepository } from "../database/MongoRepository.js";
+import "reflect-metadata";
+/**
+ * Utility class for working with data model classes.
+ *
+ * @author Jean-Philippe Steinmetz
+ */
+export declare class ModelUtils {
+    /** The `typeorm` module containing the query operators used to build SQL queries. */
+    private static typeOrm;
+    /**
+     * Provides the `typeorm` module to use when building SQL queries. This is called automatically when a SQL
+     * datastore connection is established.
+     *
+     * @param module The `typeorm` module.
+     */
+    static setTypeOrm(module: any): void;
+    /**
+     * Returns the `typeorm` module, throwing an error if it has not been provided.
+     */
+    private static get orm();
+    /**
+     * Retrieves a list of all of the specified class's properties that have the @Identifier decorator applied.
+     *
+     * @param modelClass The class definition to search for identifiers from.
+     * @returns The list of all property names that have the @Identifier decorator applied.
+     */
+    static getIdPropertyNames(modelClass: any): string[];
+    /**
+     * Builds a query object for use with `find` functions of the given repository for retrieving objects matching the
+     * specified unique identifier.
+     *
+     * @param repo The repository to build the query for.
+     * @param modelClass The class definition of the data model to build a search query for.
+     * @param id The unique identifier to search for.
+     * @param version The version number of the document to search for.
+     * @param productUid The optional product uid that is associated with the uid (when a compound key is used).
+     * @returns An object that can be passed to a TypeORM `find` function.
+     */
+    static buildIdSearchQuery<T extends {}>(repo: Repository<T> | MongoRepository<T> | undefined, modelClass: any, id: any | any[], version?: number, productUid?: string): any;
+    /**
+     * Builds a TypeORM compatible query object for use in `find` functions for retrieving objects matching the
+     * specified unique identifier.
+     *
+     * @param modelClass The class definition of the data model to build a search query for.
+     * @param id The unique identifier to search for.
+     * @param version The version number of the document to search for.
+     * @param productUid The optional product uid that is associated with the uid (when a compound key is used).
+     * @returns An object that can be passed to a TypeORM `find` function.
+     */
+    static buildIdSearchQuerySQL(modelClass: any, id: any | any[], version?: number, productUid?: string): any;
+    /**
+     * Builds a MongoDB compatible query object for use in `find` functions for retrieving objects matching the
+     * specified unique identifier.
+     *
+     * @param modelClass The class definition of the data model to build a search query for.
+     * @param id The unique identifier to search for.
+     * @param version The version number of the document to search for.
+     * @param productUid The optional product uid that is associated with the uid (when a compound key is used).
+     * @returns An object that can be passed to a MongoDB `find` function.
+     */
+    static buildIdSearchQueryMongo(modelClass: any, id: any | any[], version?: number, productUid?: string): any;
+    /**
+     * Given a string containing a parameter value and/or a comparison operation return a TypeORM compatible find value.
+     * e.g.
+     * Given the string "myvalue" will return an Eq("myvalue") object.
+     * Given the string "Like(myvalue)" will return an Like("myvalue") object.
+     *
+     * @param param
+     */
+    private static getQueryParamValue;
+    /**
+     * Given a string containing a parameter value and/or a comparison operation return a MongoDB compatible find value.
+     * e.g.
+     * Given the string "myvalue" will return an `"myvalue"` object.
+     * Given the string "not(myvalue)" will return an `{ $not: "myvalue" }` object.
+     *
+     * @param param
+     */
+    private static getQueryParamValueMongo;
+    /**
+     * Builds a query object for the given criteria and repository. Query params can have a value containing a
+     * conditional operator to apply for the search. The operator is encoded with the format `op(value)`. The following
+     * operators are supported:
+     * * `eq` - Returns matches whose parameter exactly matches of the given value. e.g. `param = value`
+     * * `gt` - Returns matches whose parameter is greater than the given value. e.g. `param > value`
+     * * `gte` - Returns matches whose parameter is greater than or equal to the given value. e.g. `param >= value`
+     * * `in` - Returns matches whose parameter includes one of the given values. e.g. `param in ('value1', 'value2', 'value3', ...)`
+     * * `like` - Returns matches whose parameter is lexographically similar to the given value. `param like value`
+     * * `lt` -  Returns matches whose parameter is less than the given value. e.g. `param < value`
+     * * `lte` - Returns matches whose parameter is less than or equal to than the given value. e.g. `param < value`
+     * * `not` - Returns matches whose parameter is not equal to the given value. e.g. `param not value`
+     * * `range` - Returns matches whose parameter is greater than or equal to first given value and less than or equal to the second. e.g. `param between(1,100)`
+     *
+     * When no operator is provided the comparison will always be evaluated as `eq`.
+     *
+     * NOTE: The result of this function is only compatible with the `aggregate()` function when MongoDB is used.
+     *
+     * @param modelClass The class definition of the data model to build a search query for.
+     * @param repo The repository to build a search query for.
+     * @param {any} params The URI parameters for the endpoint that was requested.
+     * @param {any} queryParams The URI query parameters that were included in the request.
+     * @param {bool} exactMatch Set to true to create a query where parameters are to be matched exactly, otherwise set to false to use a 'contains' search.
+     * @param {any} user The user that is performing the request.
+     * @returns {object} The TypeORM compatible query object.
+     */
+    static buildSearchQuery<T extends {}>(modelClass: any, repo: Repository<T> | MongoRepository<T> | undefined, params?: any, queryParams?: any, exactMatch?: boolean, user?: any): any;
+    /**
+     * Builds a TypeORM compatible query object for the given criteria. Query params can have a value containing a
+     * conditional operator to apply for the search. The operator is encoded with the format `op(value)`. The following
+     * operators are supported:
+     * * `eq` - Returns matches whose parameter exactly matches of the given value. e.g. `param = value`
+     * * `gt` - Returns matches whose parameter is greater than the given value. e.g. `param > value`
+     * * `gte` - Returns matches whose parameter is greater than or equal to the given value. e.g. `param >= value`
+     * * `in` - Returns matches whose parameter includes one of the given values. e.g. `param in ('value1', 'value2', 'value3', ...)`
+     * * `like` - Returns matches whose parameter is lexographically similar to the given value. `param like value`
+     * * `lt` -  Returns matches whose parameter is less than the given value. e.g. `param < value`
+     * * `lte` - Returns matches whose parameter is less than or equal to than the given value. e.g. `param < value`
+     * * `not` - Returns matches whose parameter is not equal to the given value. e.g. `param not value`
+     * * `range` - Returns matches whose parameter is greater than or equal to first given value and less than or equal to the second. e.g. `param between(1,100)`
+     *
+     * When no operator is provided the comparison will always be evaluated as `eq`.
+     *
+     * @param modelClass The class definition of the data model to build a search query for.
+     * @param {any} params The URI parameters for the endpoint that was requested.
+     * @param {any} queryParams The URI query parameters that were included in the request.
+     * @param {bool} exactMatch Set to true to create a query where parameters are to be matched exactly, otherwise set to false to use a 'contains' search.
+     * @param {any} user The user that is performing the request.
+     * @returns {object} The TypeORM compatible query object.
+     */
+    static buildSearchQuerySQL(modelClass: any, params?: any, queryParams?: any, exactMatch?: boolean, user?: any): any;
+    /**
+     * Builds a MongoDB compatible query object for the given criteria. Query params can have a value containing a
+     * conditional operator to apply for the search. The operator is encoded with the format `op(value)`. The following
+     * operators are supported:
+     * * `eq` - Returns matches whose parameter exactly matches of the given value. e.g. `param = value`
+     * * `gt` - Returns matches whose parameter is greater than the given value. e.g. `param > value`
+     * * `gte` - Returns matches whose parameter is greater than or equal to the given value. e.g. `param >= value`
+     * * `in` - Returns matches whose parameter includes one of the given values. e.g. `param in ('value1', 'value2', 'value3', ...)`
+     * * `like` - Returns matches whose parameter is lexographically similar to the given value. `param like value`
+     * * `lt` -  Returns matches whose parameter is less than the given value. e.g. `param < value`
+     * * `lte` - Returns matches whose parameter is less than or equal to than the given value. e.g. `param < value`
+     * * `not` - Returns matches whose parameter is not equal to the given value. e.g. `param not value`
+     * * `range` - Returns matches whose parameter is greater than or equal to first given value and less than or equal to the second. e.g. `param between(1,100)`
+     *
+     * When no operator is provided the comparison will always be evaluated as `eq`.
+     *
+     * NOTE: The result of this function is only compatible with the `aggregate()` function.
+     *
+     * @param modelClass The class definition of the data model to build a search query for.
+     * @param {any} params The URI parameters for the endpoint that was requested.
+     * @param {any} queryParams The URI query parameters that were included in the request.
+     * @param {bool} exactMatch Set to true to create a query where parameters are to be matched exactly, otherwise set to false to use a 'contains' search.
+     * @param {any} user The user that is performing the request.
+     * @returns {object} The TypeORM compatible query object.
+     */
+    static buildSearchQueryMongo(modelClass: any, params?: any, queryParams?: any, exactMatch?: boolean, user?: any): any;
+    /**
+     * Loads all model schema files from the specified path and returns a map containing all the definitions.
+     *
+     * @param src The path to the model files to load.
+     * @returns A map containing of all loaded model names to their class definitions.
+     */
+    static loadModels(src: string, result?: Map<string, any>): Promise<Map<string, any>>;
+}

package/dist/types/models/RecoverableBaseEntity.d.ts

@@ -0,0 +1,16 @@
+import { BaseEntity } from "./BaseEntity.js";
+/**
+ * The `RecoverableBaseEntity` provides an entity base class for those classes wishing to implement
+ * soft delete capability. A soft delete means that a delete operation does not remove the entity
+ * from the database but instead simply marks it as deleted. To completely remove the entity from
+ * the database the user must explicitly specify the entity to be purged.
+ *
+ * @author Jean-Philippe Steinmetz <rapidrests@gmail.com>
+ */
+export declare abstract class RecoverableBaseEntity extends BaseEntity {
+    /**
+     * Indicates if the document has been soft deleted.
+     */
+    deleted: boolean;
+    constructor(other?: Partial<RecoverableBaseEntity>);
+}

package/dist/types/models/RecoverableBaseMongoEntity.d.ts

@@ -0,0 +1,16 @@
+import { RecoverableBaseEntity } from "./RecoverableBaseEntity.js";
+/**
+ * The `RecoverableBaseMongoEntity` provides an entity base class for those classes wishing to implement
+ * soft delete capability. A soft delete means that a delete operation does not remove the entity
+ * from the database but instead simply marks it as deleted. To completely remove the entity from
+ * the database the user must explicitly specify the entity to be purged.
+ *
+ * @author Jean-Philippe Steinmetz <rapidrests@gmail.com>
+ */
+export declare abstract class RecoverableBaseMongoEntity extends RecoverableBaseEntity {
+    /**
+     * The internal unique identifier used by MongoDB.
+     */
+    _id?: any;
+    constructor(other?: Partial<RecoverableBaseMongoEntity>);
+}

package/dist/types/models/RepoUtils.d.ts

@@ -0,0 +1,154 @@
+import type { Repository } from "typeorm";
+import { MongoRepository } from "../database/MongoRepository.js";
+import { BaseEntity } from "../models/BaseEntity.js";
+import { SimpleEntity } from "../models/SimpleEntity.js";
+import { JWTUser } from "@rapidrest/core";
+import { Redis } from "ioredis";
+import { ObjectFactory } from "../ObjectFactory.js";
+import { NotificationUtils } from "../NotificationUtils.js";
+import { AccessControlList, ACLUtils } from "../security/index.js";
+import { ConnectionManager } from "../database/index.js";
+/**
+ * The available options used for `RepoUtils` operations.
+ */
+export interface RepoOperationOptions {
+    /** Set to `true` to ignore the ACL permissions check. */
+    ignoreACL?: boolean;
+    /** An additional list of channel names to send push notifications to. */
+    pushChannels?: string[];
+    /** Indicates if a telemetry event should be broadcast for the request. */
+    recordEvent?: boolean;
+    /** Set to `true` to not send a push notification. */
+    skipPush?: boolean;
+    /** The authenticated user making the request. */
+    user?: JWTUser;
+}
+/**
+ * The available options for the `RepoUtils.create()` operation.
+ */
+export interface RepoCreateOptions extends RepoOperationOptions {
+    /** The AccessControlList to use when creating a new object. */
+    acl?: AccessControlList;
+}
+/**
+ * The available options for the `RepoUtils.delete()` operation.
+ */
+export interface RepoDeleteOptions extends RepoOperationOptions {
+    /** The desired product uid of the resource to delete. */
+    productUid?: string;
+    /** Set to true to permanently remove the object from the database (if applicable). */
+    purge?: boolean;
+    /** The desired version number of the resource to delete. */
+    version?: number | string;
+}
+export interface RepoFindOptions extends RepoOperationOptions {
+    /** The total number of resources to retrieve. */
+    limit?: number;
+    /** The page number of the paginated results to retrieve. */
+    page?: number;
+    /** The desired product uid of the resources to retrieve. */
+    productUid?: string;
+    /** Set to `true` to skip retrieval from the cache. Default is `false`. */
+    skipCache?: boolean;
+    /** The desired version number of the resources to retrieve. */
+    version?: number | string;
+}
+/**
+ * The available options for the `RepoUtils.update()` operation.
+ */
+export interface RepoUpdateOptions<T extends BaseEntity | SimpleEntity> extends RepoOperationOptions {
+    /** The desired product uid of the resource to update. */
+    productUid?: string;
+    /** The desired version number of the resource to update. */
+    version?: number | string;
+}
+/**
+ * @author Jean-Philippe Steinmetz
+ */
+export declare class RepoUtils<T extends BaseEntity | SimpleEntity> {
+    protected aclUtils?: ACLUtils;
+    /** The redis client that will be used as a 2nd level cache for all cacheable models. */
+    protected cacheClient?: Redis;
+    protected config: any;
+    protected connectionManager?: ConnectionManager;
+    /** The unique identifier of the default ACL for the model type. */
+    defaultACLUid: string;
+    protected logger: any;
+    protected modelClass: any;
+    protected objectFactory?: ObjectFactory;
+    protected notificationUtils?: NotificationUtils;
+    /** The model class associated with the controller to perform operations against. */
+    repo?: Repository<T> | MongoRepository<T>;
+    protected trustedRoles: string[];
+    constructor(modelClass: any, repo?: Repository<T> | MongoRepository<T>);
+    protected init(): Promise<void>;
+    /**
+     * The base key used to get or set data in the cache.
+     */
+    get baseCacheKey(): string;
+    count(query: any, options?: RepoFindOptions): Promise<number>;
+    /**
+     * Stores a new record of the provided object in the datastore. Performs pre-processing, permission checks against
+     * the class ACL, cache seeding, telemetry recording and push notifications.
+     *
+     * @param obj The object to store.
+     * @param acl The ACL to use
+     */
+    create(obj: Partial<T>, options?: RepoCreateOptions): Promise<T>;
+    delete(uid: string, options: RepoDeleteOptions): Promise<void>;
+    /**
+     * Retrieves an array of objects from the datastore matching the given search query. This function will first
+     * attempt to look up the results in the cache. Also checks ACLs for READ permission.
+     *
+     * @param query The constructed search query to run.
+     * @param options The additional options to consider during the search.
+     */
+    find(query: any, options?: RepoFindOptions): Promise<Array<T>>;
+    /**
+     * Retrieves the object with the given id from either the cache or the database. If retrieving from the database
+     * the cache is populated to speed up subsequent requests.
+     *
+     * @param id The unique identifier of the object to retrieve.
+     * @param options The additional options to consider during the search.
+     */
+    findOne(id: string, options?: RepoFindOptions): Promise<T | undefined>;
+    /**
+     * Returns the default access control list governing the model type. Returning a value of `undefined` will grant
+     * full acccess to any user (including unauthenticated anonymous users).
+     */
+    getDefaultACL(): AccessControlList | undefined;
+    /**
+     * Hashes the given query object to a unique string.
+     * @param query The query object to hash.
+     */
+    hashQuery(query: any): string;
+    /**
+     * Returns the class type (constructor) for the given object. This uses the `_fqn` or `_type` property of `obj` to
+     * identify the class. If neither property is defined `modelClass` is assumed.
+     *
+     * @param obj The object whose class type to look up.
+     * @returns The class type (constructor) associated with the given object.
+     */
+    getClassType(obj: any): any;
+    /**
+     * Creates a new instance of obj scoped to the correct model class or sub-class.
+     */
+    instantiateObject(obj: any, clazz?: any): T;
+    /**
+     * Search for existing object based on passed in id and version and product uid.
+     *
+     * The result of this function is compatible with all `Repository.find()` functions.
+     */
+    searchIdQuery(id: string, version?: number | string, productUid?: string): any;
+    truncate(query: any, options: RepoFindOptions): Promise<void>;
+    update(obj: Partial<T>, existing: T, options?: RepoUpdateOptions<T>): Promise<T>;
+    /**
+     * Performs validation on the object(s) provided. This function first calls `ObjectUtils.validate()` to check
+     * any class level defined validation functions. Second, it scans for any properties with the `@Reference`
+     * decorator and attempts to verify that an existing object for the given reference ID is valid.
+     *
+     * @param objs The object(s) to validate.
+     * @param options The optional set of arguments that can be passed to perform additonal checks.
+     */
+    validate(objs: Partial<T> | Partial<T>[], options?: RepoOperationOptions): Promise<void>;
+}

package/dist/types/models/SimpleEntity.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Provides a simple base class for all entity's that will be persisted with TypeORM. Unlike `BaseEntity` this class
+ * does not provide optimistic locking or date created and modified tracking.
+ *
+ * @author Jean-Philippe Steinmetz <rapidrests@gmail.com>
+ */
+export declare abstract class SimpleEntity {
+    /**
+     * The universally unique identifier of the entity.
+     */
+    uid: string;
+    constructor(other?: Partial<SimpleEntity>);
+}
+export type PartialSimpleEntity<T extends SimpleEntity> = Partial<T> & Pick<T, "uid">;

package/dist/types/models/SimpleMongoEntity.d.ts

@@ -0,0 +1,15 @@
+import { ObjectId } from "mongodb";
+import { SimpleEntity } from "./SimpleEntity.js";
+/**
+ * Provides a simple base class for all entity's that will be persisted in a MongoDB database. Unlike
+ * `BaseMongoEntity` this class does not provide optimistic locking or date created and modified tracking.
+ *
+ * @author Jean-Philippe Steinmetz <rapidrests@gmail.com>
+ */
+export declare abstract class SimpleMongoEntity extends SimpleEntity {
+    /**
+     * The internal unique identifier used by MongoDB.
+     */
+    _id?: ObjectId;
+    constructor(other?: Partial<SimpleMongoEntity>);
+}

package/dist/types/models/StatusExtraData.d.ts

@@ -0,0 +1,6 @@
+export declare class StatusExtraData {
+    private _data;
+    get data(): any;
+    set data(data: any);
+    constructor(other: Partial<StatusExtraData>);
+}

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

@@ -0,0 +1,9 @@
+export * from "./BaseEntity.js";
+export * from "./BaseMongoEntity.js";
+export * from "./ModelUtils.js";
+export * from "./RecoverableBaseEntity.js";
+export * from "./RecoverableBaseMongoEntity.js";
+export * from "./RepoUtils.js";
+export * from "./SimpleEntity.js";
+export * from "./SimpleMongoEntity.js";
+export * from "./StatusExtraData.js";

package/dist/types/routes/AdminRoute.d.ts

@@ -0,0 +1,47 @@
+import { Redis } from "ioredis";
+import Transport from "winston-transport";
+/**
+ * Implements a Winston transport that pipes incoming log messages to a configured redis pubsub channel.
+ */
+export declare class RedisTransport extends Transport {
+    private channel;
+    private redis;
+    constructor(opts: any);
+    close(): void;
+    log(info: any, next: Function): any;
+}
+/**
+ * The `AdminRoute` provides a default `/admin` endpoint that gives trusted users the following abilities:
+ *
+ * * Clear cache via `GET /admin/clear-cache`
+ * * Live tail the service logs via `GET /admin/logs`
+ * * Retrieve service dependencies via `GET /admin/dependencies`
+ * * Retrieve service release notes via `GET /admin/release-notes`
+ * * Restart the service via `GET /admin/restart`
+ *
+ * @author Jean-Philippe Steinmetz
+ */
+export declare class AdminRoute {
+    /** A map of user uid's to active sockets. */
+    private activeSockets;
+    protected cacheClient?: Redis;
+    private cacheConnConfig;
+    private logger;
+    private logsConnConfig;
+    private redisClient?;
+    /** The underlying ReleaseNotes specification. */
+    private releaseNotes;
+    private serviceName?;
+    private trustedRoles;
+    /**
+     * Constructs a new `ReleaseNotesRoute` object with the specified defaults.
+     *
+     * @param releaseNotes The ReleaseNotes specification object to serve.
+     */
+    constructor(releaseNotes: string);
+    private init;
+    private clearCache;
+    private logs;
+    private get;
+    private restart;
+}

package/dist/types/routes/MetricsRoute.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Handles all REST API requests for the endpoint `/metrics'. This route handler produces Prometheus compatible metrics
+ * for use with a Prometheus based server.
+ *
+ * Services that wish to provide metrics to be exposed via this route can register them using the global registry
+ * from the provided `prom-client` dependency. See the `prom-client` documentation for more details.
+ */
+export declare class MetricsRoute {
+    private metricsConfig;
+    private registry;
+    private trustedRoles;
+    constructor();
+    private getMetrics;
+    private getSingleMetric;
+}