@vsaas/loopback-datasource-juggler 10.0.0

package/types/kv-model.d.ts

@@ -0,0 +1,201 @@
+// Copyright IBM Corp. 2018. All Rights Reserved.
+// Node module: loopback-datasource-juggler
+// This file is licensed under the MIT License.
+// License text available at https://opensource.org/licenses/MIT
+
+import { Callback, Options, PromiseOrVoid } from './common';
+import { ModelBase, ModelData } from './model';
+
+/**
+ * Data object for KV models
+ */
+export type KVData<T extends ModelBase = ModelBase> = ModelData<T>;
+
+/**
+ * Key/Value model. Strictly speaking, KeyValueModel is not a class
+ * but a mixin into existing model classes
+ */
+export declare class KeyValueModel extends ModelBase {
+  /**
+   * Return the value associated with a given key.
+   *
+   * @param {string} key Key to use when searching the database.
+   * @options {Object} options
+   * @callback {Function} callback
+   * @param {Error} err Error object.
+   * @param {any} result Value associated with the given key.
+   * @promise
+   *
+   * @header KeyValueModel.get(key, cb)
+   */
+  static get(key: string, options?: Options, callback?: Callback<KVData>): PromiseOrVoid<KVData>;
+
+  /**
+   * Persist a value and associate it with the given key.
+   *
+   * @param {string} key Key to associate with the given value.
+   * @param {any} value Value to persist.
+   * @options {Number|Object} options Optional settings for the key-value
+   *   pair. If a Number is provided, it is set as the TTL (time to live) in ms
+   *   (milliseconds) for the key-value pair.
+   * @property {Number} ttl TTL for the key-value pair in ms.
+   * @callback {Function} callback
+   * @param {Error} err Error object.
+   * @promise
+   *
+   * @header KeyValueModel.set(key, value, cb)
+   */
+  static set(
+    key: string,
+    value: KVData,
+    options?: Options,
+    callback?: Callback<void>,
+  ): PromiseOrVoid<void>;
+
+  /**
+   * Delete the key-value pair associated to the given key.
+   *
+   * @param {string} key Key to use when searching the database.
+   * @options {Object} options
+   * @callback {Function} callback
+   * @param {Error} err Error object.
+   * @param {*} result Value associated with the given key.
+   * @promise
+   */
+  static delete(key: string, options?: Options, callback?: Callback<void>): PromiseOrVoid<void>;
+
+  /**
+   * Delete all keys (and values) associated to the current model.
+   *
+   * @options {Object} options Unused ATM, placeholder for future options.
+   * @callback {Function} callback
+   * @param {Error} err Error object.
+   * @promise
+   */
+  static deleteAll(options?: Options, callback?: Callback<void>): PromiseOrVoid<void>;
+
+  /**
+   * Set the TTL (time to live) in ms (milliseconds) for a given key. TTL is the
+   * remaining time before a key-value pair is discarded from the database.
+   *
+   * @param {string} key Key to use when searching the database.
+   * @param {Number} ttl TTL in ms to set for the key.
+   * @options {Object} options
+   * @callback {Function} callback
+   * @param {Error} err Error object.
+   * @promise
+   *
+   * @header KeyValueModel.expire(key, ttl, cb)
+   */
+  static expire(
+    key: string,
+    ttl: number,
+    options?: Options,
+    callback?: Callback<void>,
+  ): PromiseOrVoid<void>;
+
+  /**
+   * Return the TTL (time to live) for a given key. TTL is the remaining time
+   * before a key-value pair is discarded from the database.
+   *
+   * @param {string} key Key to use when searching the database.
+   * @options {Object} options
+   * @callback {Function} callback
+   * @param {Error} error
+   * @param {Number} ttl Expiration time for the key-value pair. `undefined` if
+   *   TTL was not initially set.
+   * @promise
+   *
+   * @header KeyValueModel.ttl(key, cb)
+   */
+  static ttl(key: string, options?: Options, callback?: Callback<number>): PromiseOrVoid<number>;
+
+  /**
+   * Return all keys in the database.
+   *
+   * **WARNING**: This method is not suitable for large data sets as all
+   * key-values pairs are loaded into memory at once. For large data sets,
+   * use `iterateKeys()` instead.
+   *
+   * @param {Object} filter An optional filter object with the following
+   * @param {string} filter.match Glob string used to filter returned
+   *   keys (i.e. `userid.*`). All connectors are required to support `*` and
+   *   `?`, but may also support additional special characters specific to the
+   *   database.
+   * @param {Object} options
+   * @callback {Function} callback
+   * @promise
+   *
+   * @header KeyValueModel.keys(filter, cb)
+   */
+  static keys(
+    filter?: KVFilter,
+    options?: Options,
+    callback?: Callback<string[]>,
+  ): PromiseOrVoid<string[]>;
+
+  /**
+   * Asynchronously iterate all keys in the database. Similar to `.keys()` but
+   * instead allows for iteration over large data sets without having to load
+   * everything into memory at once.
+   *
+   * Callback example:
+   * ```js
+   * // Given a model named `Color` with two keys `red` and `blue`
+   * var iterator = Color.iterateKeys();
+   * it.next(function(err, key) {
+   *   // key contains `red`
+   *   it.next(function(err, key) {
+   *     // key contains `blue`
+   *   });
+   * });
+   * ```
+   *
+   * Promise example:
+   * ```js
+   * // Given a model named `Color` with two keys `red` and `blue`
+   * var iterator = Color.iterateKeys();
+   * Promise.resolve().then(function() {
+   *   return it.next();
+   * })
+   * .then(function(key) {
+   *   // key contains `red`
+   *   return it.next();
+   * });
+   * .then(function(key) {
+   *   // key contains `blue`
+   * });
+   * ```
+   *
+   * @param {Object} filter An optional filter object with the following
+   * @param {string} filter.match
+   * @param {Object} options
+   * @returns {AsyncKeyIterator} An Object implementing `next(cb) -> Promise`
+   *   function that can be used to iterate all keys.
+   *
+   * @header KeyValueModel.iterateKeys(filter)
+   */
+  static iterateKeys(filter?: KVFilter, options?: Options): AsyncKeyIterator;
+}
+
+export type KVFilter = {
+  /**
+   * Glob string to use to filter returned keys (i.e. `userid.*`). All connectors
+   * are required to support `*` and `?`. They may also support additional special
+   * characters that are specific to the backing database.
+   */
+  match: string;
+};
+
+/**
+ * Async iterator to return keys one by one. The value will be undefined if there is
+ * no more keys
+ */
+export interface AsyncKeyIterator {
+  /**
+   * Try to fetch the next key
+   * @param callback Callback function. If not provided, the return value will be
+   * a promise
+   */
+  next(callback?: Callback<string | undefined>): PromiseOrVoid<string | undefined>;
+}

package/types/model.d.ts

@@ -0,0 +1,368 @@
+// Copyright IBM Corp. 2018,2019. All Rights Reserved.
+// Node module: loopback-datasource-juggler
+// This file is licensed under the MIT License.
+// License text available at https://opensource.org/licenses/MIT
+
+import { EventEmitter } from 'events';
+import { AnyObject, Options } from './common';
+import { DataSource } from './datasource';
+import { Listener, OperationHookContext } from './observer-mixin';
+
+/**
+ * Property types
+ */
+export type PropertyType = string | Function | { [property: string]: PropertyType };
+
+/**
+ * Property definition
+ */
+export interface PropertyDefinition extends AnyObject {
+  type?: PropertyType;
+  id?: boolean | number;
+}
+
+/**
+ * Schema definition
+ */
+export interface Schema {
+  name: string;
+  properties: ModelProperties;
+  settings?: ModelSettings;
+}
+
+/**
+ * ID definition
+ */
+export interface IdDefinition {
+  name: string;
+  id: number;
+  property: AnyObject;
+}
+
+/**
+ * Index definition
+ */
+export interface IndexDefinition extends AnyObject {}
+
+/**
+ * Column metadata
+ */
+export interface ColumnMetadata extends AnyObject {
+  name: string;
+}
+
+/**
+ * Definition of model properties, for example
+ * ```ts
+ * {
+ *   name: {type: String, required: true},
+ * }
+ * ```
+ */
+export interface ModelProperties {
+  [name: string]: PropertyDefinition;
+}
+
+/**
+ * Model settings, for example
+ * ```ts
+ * {
+ *   strict: true,
+ * }
+ * ```
+ */
+export interface ModelSettings extends AnyObject {
+  strict?: boolean;
+  forceId?: boolean;
+}
+
+/**
+ * Model definition
+ */
+export declare class ModelDefinition extends EventEmitter implements Schema {
+  name: string;
+  properties: ModelProperties;
+  rawProperties: AnyObject;
+  settings?: ModelSettings;
+  relations?: AnyObject[];
+
+  constructor(
+    modelBuilder: ModelBuilder | null | undefined,
+    name: string,
+    properties?: ModelProperties,
+    settings?: ModelSettings,
+  );
+  constructor(modelBuilder: ModelBuilder | null | undefined, schema: Schema);
+
+  tableName(connectorType: string): string;
+  columnName(connectorType: string, propertyName: string): string;
+  columnNames(connectorType: string): string[];
+  columnMetadata(connectorType: string, propertyName: string): ColumnMetadata;
+
+  ids(): IdDefinition[];
+  idName(): string;
+  idNames(): string[];
+
+  defineProperty(propertyName: string, propertyDefinition: PropertyDefinition): void;
+  indexes(): { [name: string]: IndexDefinition };
+  build(forceRebuild?: boolean): AnyObject;
+  toJSON(forceRebuild?: boolean): AnyObject;
+}
+
+/**
+ * Base class for LoopBack 3.x models
+ */
+export declare class ModelBase {
+  static dataSource?: DataSource;
+  static modelName: string;
+  static definition: ModelDefinition;
+  static readonly base: typeof ModelBase;
+
+  /**
+   * Extend the model with the specified model, properties, and other settings.
+   * For example, to extend an existing model:
+   *
+   * ```js
+   * const Customer = User.extend('Customer', {
+   *   accountId: String,
+   *   vip: Boolean
+   * });
+   * ```
+   *
+   * @param className Name of the new model being defined.
+   * @param subClassProperties child model properties, added to base model
+   *   properties.
+   * @param subClassSettings child model settings such as relations and acls,
+   *   merged with base model settings.
+   */
+  static extend<ChildModel extends typeof ModelBase = typeof ModelBase>(
+    modelName: string,
+    properties?: ModelProperties,
+    settings?: ModelSettings,
+  ): ChildModel;
+
+  /**
+   * Attach the model class to a data source
+   * @param ds The data source
+   */
+  static attachTo(ds: DataSource): void;
+
+  /**
+   * Get model property type.
+   * @param {string} propName Property name
+   * @returns {string} Name of property type
+   */
+  static getPropertyType(propName: string): string | null;
+
+  /**
+   * Checks if property is hidden.
+   * @param {string} propertyName Property name
+   * @returns {Boolean} true or false if hidden or not.
+   */
+  static isHiddenProperty(propertyName: string): boolean;
+
+  /**
+   * Checks if property is protected.
+   * @param {string} propertyName Property name
+   * @returns  {Boolean} true or false if protected or not.
+   */
+  static isProtectedProperty(propertyName: string): boolean;
+
+  /**
+   * Gets properties defined with 'updateOnly' flag set to true from the model.
+   * This flag is also set to true internally for the id property, if this
+   * property is generated and IdInjection is true.
+   * @returns {updateOnlyProps} List of properties with updateOnly set to true.
+   */
+  static getUpdateOnlyProperties(): string[];
+
+  /**
+   * Constructor for ModelBase
+   *
+   * NOTE: We have to use `constructor(...args: any[]);` so that it can be used
+   * for `return class extends superClass`.
+   *
+   * @param {AnyObject} data Initial object data
+   * @param {Options} options An object to control the instantiation
+   */
+  constructor(...args: any[]);
+  // constructor(data: AnyObject, options?: Options);
+
+  /**
+   * Convert the model instance to a plain json object
+   */
+  toJSON(): AnyObject;
+
+  /**
+   * Populate properties from a JSON object
+   * @param obj The source object
+   */
+  fromObject(obj: AnyObject): void;
+
+  /**
+   * Convert model instance to a plain JSON object.
+   * Returns a canonical object representation (no getters and setters).
+   *
+   * @param options Options for the conversion
+   * @property {boolean} onlySchema Restrict properties to dataSource only.
+   * Default is false.  If true, the function returns only properties defined
+   * in the schema;  Otherwise it returns all enumerable properties.
+   * @property {boolean} removeHidden Boolean flag as part of the transformation.
+   * If true, then hidden properties should not be brought out.
+   * @property {boolean} removeProtected Boolean flag as part of the transformation.
+   * If true, then protected properties should not be brought out.
+   * @returns {object} returns Plain JSON object
+   */
+  toObject(options?: Options): AnyObject;
+
+  /**
+   * Define a property on the model.
+   * @param {string} prop Property name
+   * @param definition Various property configuration
+   */
+  defineProperty(propertyName: string, definition: Partial<PropertyDefinition>): void;
+
+  getDataSource(): DataSource;
+
+  /**
+   *
+   * @param {string} anotherClass could be string or class. Name of the class
+   * or the class itself
+   * @param {Object} options An object to control the instantiation
+   * @returns {ModelClass}
+   */
+  static mixin(anotherClass: string | ModelBaseClass | object, options?: Options): ModelBaseClass;
+
+  // ObserverMixin members are added as static methods, this is difficult to
+  // describe in TypeScript in a way that's easy to use by consumers.
+  // As a workaround, we include a copy of ObserverMixin members here.
+  //
+  // Ideally, we want to describe the context argument as
+  // `OperationHookContext<this>`. Unfortunately, that's not supported by
+  // TypeScript for static members. A nice workaround is described in
+  // https://github.com/microsoft/TypeScript/issues/5863#issuecomment-410887254
+  // - Describe the context using a generic argument `T`.
+  // - Use `this: T` argument to let the compiler infer what's the target
+  //   model class we are going to observe.
+
+  /**
+   * Register an asynchronous observer for the given operation (event).
+   *
+   * Example:
+   *
+   * Registers a `before save` observer for a given model.
+   *
+   * ```javascript
+   * MyModel.observe('before save', function filterProperties(ctx, next) {
+   *   if (ctx.options && ctx.options.skipPropertyFilter) return next();
+   *     if (ctx.instance) {
+   *       FILTERED_PROPERTIES.forEach(function(p) {
+   *       ctx.instance.unsetAttribute(p);
+   *     });
+   *   } else {
+   *     FILTERED_PROPERTIES.forEach(function(p) {
+   *       delete ctx.data[p];
+   *     });
+   *   }
+   *   next();
+   * });
+   * ```
+   *
+   * @param {String} operation The operation name.
+   * @callback {function} listener The listener function. It will be invoked with
+   * `this` set to the model constructor, e.g. `User`.
+   * @end
+   */
+  static observe<T extends typeof ModelBase>(
+    this: T,
+    operation: string,
+    listener: Listener<OperationHookContext<T>>,
+  ): void;
+
+  /**
+   * Unregister an asynchronous observer for the given operation (event).
+   *
+   * Example:
+   *
+   * ```javascript
+   * MyModel.removeObserver('before save', function removedObserver(ctx, next) {
+   *   // some logic user want to apply to the removed observer...
+   *   next();
+   * });
+   * ```
+   *
+   * @param {String} operation The operation name.
+   * @callback {function} listener The listener function.
+   * @end
+   */
+  static removeObserver<T extends typeof ModelBase>(
+    this: T,
+    operation: string,
+    listener: Listener<OperationHookContext<T>>,
+  ): Listener<OperationHookContext<T>> | undefined;
+
+  /**
+   * Unregister all asynchronous observers for the given operation (event).
+   *
+   * Example:
+   *
+   * Remove all observers connected to the `before save` operation.
+   *
+   * ```javascript
+   * MyModel.clearObservers('before save');
+   * ```
+   *
+   * @param {String} operation The operation name.
+   * @end
+   */
+  static clearObservers(operation: string): void;
+}
+
+export type ModelBaseClass = typeof ModelBase;
+
+export declare class ModelBuilder extends EventEmitter {
+  static defaultInstance: ModelBuilder;
+
+  models: { [name: string]: ModelBaseClass };
+  definitions: { [name: string]: ModelDefinition };
+  settings: ModelSettings;
+
+  defaultModelBaseClass: typeof ModelBase;
+
+  getModel(name: string, forceCreate?: boolean): ModelBaseClass;
+
+  getModelDefinition(name: string): ModelDefinition | undefined;
+
+  define(
+    className: string,
+    properties?: ModelProperties,
+    settings?: ModelSettings,
+    parent?: ModelBaseClass,
+  ): ModelBaseClass;
+
+  defineProperty(modelName: string, propertyName: string, propertyDefinition: AnyObject): void;
+
+  defineValueType(type: string, aliases?: string[]): void;
+
+  extendModel(modelName: string, properties: AnyObject): void;
+
+  getSchemaName(name?: string): string;
+
+  resolveType(type: any): any;
+
+  buildModels(schemas: AnyObject, createModel?: Function): { [name: string]: ModelBaseClass };
+
+  buildModelFromInstance(name: string, json: AnyObject, options: Options): ModelBaseClass;
+}
+
+/**
+ * An extension of the built-in Partial<T> type which allows partial values
+ * in deeply nested properties too.
+ */
+export type DeepPartial<T> = { [P in keyof T]?: DeepPartial<T[P]> };
+
+/**
+ * Union export type for model instance or plain object representing the model
+ * instance
+ */
+export type ModelData<T extends ModelBase = ModelBase> = T | DeepPartial<T>;