mingo/types/core.d.ts

MongoDB query language for in-memory objects

import { Iterator } from "./lazy";
import type { WindowOperatorInput } from "./operators/window/_internal";
import { Any, AnyObject, Callback, HashFunction, Predicate } from "./types";
/**
 * Resolves the given string to a Collection.
 * This is useful for operators that require a second collection to use such as $lookup and $out.
 * The collection is not cached and will be resolved each time it is used.
 */
export type CollectionResolver = (name: string) => AnyObject[];
/** Specification for collation options */
export interface CollationSpec {
    readonly locale: string;
    readonly caseLevel?: boolean;
    readonly caseFirst?: "upper" | "lower" | "off";
    readonly strength?: 1 | 2 | 3;
    readonly numericOrdering?: boolean;
    readonly alternate?: string;
    readonly maxVariable?: never;
    readonly backwards?: never;
}
/**
 * JSON schema validator
 */
export type JsonSchemaValidator = (schema: AnyObject) => Predicate<AnyObject>;
/**
 * Enum representing the processing modes for handling input and output documents.
 * This determines whether cloning is applied to maintain immutability or ensure
 * distinct object references.
 */
export declare enum ProcessingMode {
    /** Do not clone inputs or outputs. Resulting documents may share references. This is the default mode. */
    CLONE_OFF = 0,
    /** Clone input documents to maintain immutability of the original input. */
    CLONE_INPUT = 1,
    /** Clone output documents to ensure distinct objects without shared references. */
    CLONE_OUTPUT = 2,
    /** Clone both input and output documents. Combines `CLONE_INPUT` and `CLONE_OUTPUT`.*/
    CLONE_ALL = 3
}
/**
 * Generic options interface passed down to all operators
 */
export interface Options {
    /** The key that is used to lookup the ID value of a document. @default "_id". */
    readonly idKey: string;
    /** The collation specification for string sorting operations. */
    readonly collation?: CollationSpec;
    /** Determines how to treat inputs and outputs. @default ProcessingMode.CLONE_OFF. */
    readonly processingMode: ProcessingMode;
    /** Enforces strict MongoDB compatibilty. See README. @default true. */
    readonly useStrictMode: boolean;
    /** Enable or disable custom script execution using `$where`, `$accumulator`, and `$function` operators. @default true. */
    readonly scriptEnabled: boolean;
    /**
     * Enable or disable falling back to the global context for operators. @default true.
     * @deprecated Will be removed in 7.0.0.
     */
    readonly useGlobalContext: boolean;
    /** Hash function to replace the Effective Java default implementation. */
    readonly hashFunction?: HashFunction;
    /** Function to resolve strings to arrays for use with operators that reference other collections such as; `$lookup`, `$out` and `$merge`. */
    readonly collectionResolver?: CollectionResolver;
    /** JSON schema validator to use with the '$jsonSchema' operator. Required in order to use the operator. */
    readonly jsonSchemaValidator?: JsonSchemaValidator;
    /** Global variables. */
    readonly variables?: Readonly<AnyObject>;
    /** Extra references to operators to be used for processing. */
    readonly context: Context;
}
interface LocalData {
    /** The groupId computed for a group of documents. */
    readonly groupId?: Any;
    /** Local user-defind variables. */
    readonly variables?: AnyObject;
    /** The current timestamp */
    readonly now?: number;
}
/** Custom type to facilitate type checking for global options */
export declare class ComputeOptions implements Options {
    #private;
    private constructor();
    /**
     * Initialize new ComputeOptions.
     * @returns {ComputeOptions}
     */
    static init(options: Options, root?: Any, local?: LocalData): ComputeOptions;
    /**
     * Updates the internal state.
     *
     * @param root The new root context for this object.
     * @param local The new local state to merge into current if it exists.
     * @returns
     */
    update(root?: Any, local?: LocalData): ComputeOptions;
    getOptions(): Options;
    get root(): unknown;
    get local(): LocalData;
    get idKey(): string;
    get collation(): CollationSpec;
    get processingMode(): ProcessingMode;
    get useStrictMode(): boolean;
    get scriptEnabled(): boolean;
    get useGlobalContext(): boolean;
    get hashFunction(): HashFunction;
    get collectionResolver(): CollectionResolver;
    get jsonSchemaValidator(): JsonSchemaValidator;
    get variables(): Readonly<AnyObject>;
    get context(): Context;
}
/**
 * Creates an Option from another where required keys are initialized.
 * @param options Options
 */
export declare function initOptions(options?: Partial<Options>): Options;
/**
 * Supported cloning modes.
 * - "deep": Performs a recursive deep clone of the object.
 * - "copy": Performs a shallow copy of the object.
 * - "none": No cloning. Uses the value as given.
 */
export type CloneMode = "deep" | "copy" | "none";
export interface UpdateOptions {
    /** Specifies whether to deep clone values to persist in the internal store. @default "copy". */
    readonly cloneMode?: CloneMode;
    /** Options to use for processing queries. Unless overriden 'useStrictMode' is false.  */
    readonly queryOptions?: Partial<Options>;
}
/**
 * The different groups of operators
 */
export declare enum OpType {
    ACCUMULATOR = "accumulator",
    EXPRESSION = "expression",
    PIPELINE = "pipeline",
    PROJECTION = "projection",
    QUERY = "query",
    WINDOW = "window"
}
/** @deprecated use {@link OpType} */
export type OperatorType = OpType;
export type AccumulatorOperator<R = Any> = (collection: Any[], expr: Any, options: Options) => R;
export type ExpressionOperator<R = Any> = (obj: AnyObject, expr: Any, options: Options) => R;
export type PipelineOperator = (collection: Iterator, expr: Any, options: Options) => Iterator;
export type ProjectionOperator = (obj: AnyObject, expr: Any, selector: string, options: Options) => Any;
export type QueryOperator = (selector: string, value: Any, options: Options) => (obj: AnyObject) => boolean;
export type WindowOperator = (obj: AnyObject, array: AnyObject[], expr: WindowOperatorInput, options: Options) => Any;
/** Interface for update operators */
export type UpdateOperator = (obj: AnyObject, expr: AnyObject, arrayFilters: AnyObject[], options: UpdateOptions) => string[];
type Operator = AccumulatorOperator | ExpressionOperator | PipelineOperator | ProjectionOperator | QueryOperator | WindowOperator;
type AccumulatorOps = Record<string, AccumulatorOperator>;
type ExpressionOps = Record<string, ExpressionOperator>;
type ProjectionOps = Record<string, ProjectionOperator>;
type QueryOps = Record<string, QueryOperator>;
type PipelineOps = Record<string, PipelineOperator>;
type WindowOps = Record<string, WindowOperator>;
export declare class Context {
    #private;
    private constructor();
    static init(ops?: {
        accumulator?: AccumulatorOps;
        expression?: ExpressionOps;
        pipeline?: PipelineOps;
        projection?: ProjectionOps;
        query?: QueryOps;
        window?: WindowOps;
    }): Context;
    static from(ctx?: Context): Context;
    static merge(first: Context, second: Context): Context;
    private addOperators;
    getOperator(type: OpType, name: string): Callback | null;
    addAccumulatorOps(ops: AccumulatorOps): Context;
    addExpressionOps(ops: ExpressionOps): Context;
    addQueryOps(ops: QueryOps): Context;
    addPipelineOps(ops: PipelineOps): Context;
    addProjectionOps(ops: ProjectionOps): Context;
    addWindowOps(ops: WindowOps): Context;
}
/**
 * Registers a set of operators for a specific operator type.
 *
 * This function validates the provided operators to ensure that each operator
 * name is valid and its corresponding function is a valid operator function.
 * It also ensures that an operator cannot be redefined once it has been registered.
 *
 * @param type - The type of operators to register (e.g., aggregation, query, etc.).
 * @param operators - A record of operator names and their corresponding functions.
 *
 * @throws Will throw an error if:
 * - An operator name is invalid.
 * - An operator function is not valid.
 * - An operator with the same name is already registered for the given type
 *   and the function differs from the existing one.
 *
 * @deprecated use {@link Context} to manage new operators. Will be removed in 7.0.0.
 */
export declare function useOperators(type: OpType, operators: Record<string, Operator>): void;
/**
 * Returns the operator function or undefined if it is not found
 * @param type Type of operator
 * @param name Name of the operator
 * @param options
 * @deprecated use {@link Context.getOperator} instead. Will be removed in 7.0.0.
 */
export declare function getOperator(type: OpType, name: string, options: Pick<Options, "useGlobalContext" | "context">): Operator;
/**
 * Computes the value of the expression on the object for the given operator
 *
 * @param obj the current object from the collection
 * @param expr the expression for the given field
 * @param operator the operator to resolve the field with
 * @param options {Object} extra options
 * @returns {*}
 */
export declare function computeValue(obj: Any, expr: Any, operator: string | null, options?: Options): Any;
/**
 * Redact an object
 * @param  {Object} obj The object to redact
 * @param  {*} expr The redact expression
 * @param  {*} options  Options for value
 * @return {*} returns the result of the redacted object
 */
export declare function redact(obj: AnyObject, expr: Any, options: ComputeOptions): Any;
export {};