feathers-graph-populate/dist/index.d.mts

Add lightning fast, GraphQL-like populates to your FeathersJS API.

import { Params, HookContext, Application, Query, Service } from '@feathersjs/feathers';

type AnyData = Record<string, any>;
type SingleGraphPopulateParams = Params | ((params?: Params, context?: HookContext) => void | Params) | ((params?: Params, context?: HookContext) => void | Promise<Params>);
type GraphPopulateParams = SingleGraphPopulateParams | SingleGraphPopulateParams[];
interface PopulateObject<S = string> {
    service: S;
    nameAs: string;
    keyHere?: string;
    keyThere?: string;
    asArray?: boolean;
    requestPerItem?: boolean;
    catchOnError?: boolean;
    params?: GraphPopulateParams;
}
interface PopulateParams {
    name?: string;
    query?: NestedQuery;
}
type NestedQuery = Record<string, AnyData>;
type Populates<S = string> = Record<string, PopulateObject<S>>;
interface GraphPopulateHookOptions<S = string> {
    populates: Populates<S>;
    /**
     * @default: false
     */
    allowUnnamedQueryForExternal?: boolean;
}
interface PopulateHookOptions<S = string> {
    populates: Populates<S>;
    namedQueries?: AnyData;
    defaultQueryName?: string;
    /**
     * @default: false
     */
    allowUnnamedQueryForExternal?: boolean;
}
interface GetPopulateQueryOptions {
    context: HookContext;
    namedQueries: AnyData;
    defaultQueryName: string;
    /**
     * @default: false
     */
    allowUnnamedQueryForExternal?: boolean;
}
interface PopulateUtilOptions<S = string> {
    app: Application;
    params: Params;
    populates: Populates<S>;
}
type GraphPopulateHook = ((params?: Params, context?: HookContext) => void | Params) | ((params?: Params, context?: HookContext) => void | Promise<Params>);
interface InitOptions {
    allowUnnamedQueryForExternal?: boolean;
}
type Method = 'find' | 'get' | 'create' | 'update' | 'patch' | 'remove';
type Type = 'before' | 'after' | 'error';
type GraphPopulateHookMap = {
    [key in Method | 'all']?: SingleGraphPopulateParams[];
};
type GraphPopulateHooksObject = {
    [key in Type]?: GraphPopulateHookMap;
};
interface ShallowPopulateOptions {
    include: PopulateObject | PopulateObject[];
    catchOnError?: boolean;
}
interface ChainedParamsOptions {
    thisKey?: AnyData | undefined;
    skipWhenUndefined?: boolean;
}
interface CumulatedRequestResult {
    include: PopulateObject;
    params?: Params;
    response?: {
        data: AnyData[];
    } | AnyData[];
}

/**
 * Sets up the deepPopulate hook using the provided options.
 *  @param options
 *    @property populates - an object whose properties are named populates to pass to feathers-shallow-populate.
 *
 * The deepPopulate hook uses `feathers-shallow-populate` along with a lightweight,
 * GraphQL-like syntax to populate data between services.  It expects to find a query
 * object at `params.$populateParams.query`.
 */
declare function graphPopulate(options: GraphPopulateHookOptions): (context: HookContext) => Promise<HookContext>;

/**
 * $populateParams.name can be passed from the outside.
 * $populateParams.query can be directly used, internally.
 */
declare function populate(options: PopulateHookOptions): (context: HookContext) => Promise<HookContext>;

/**
 * getPopulateQuery is a helper utility for the populate hook, which performs the following:
 * 1. Security - it makes sure that external requests can only pass a $populateParams.name, since
 *    providing a $populateParams.query from an external source opens up too many potential data leaks.
 * 2. Consistency - it makes sure the the $populateParams.query is always available to the populate hook,
 *    whenever applicable.
 */
declare function getQuery(options: GetPopulateQueryOptions): Query;

/**
 * This is a utility (not a hook) which performs similar to the graph-populate hook.  It
 * is meant to be used INSIDE of a hook, because it requires the `context` object.
 * The difference is that when it puts its pants on in the morning, it makes gold records.
 * Just kidding, the real difference is that it is not a hook.  It can be used inside of
 * a hook to populate data a GraphQL-like query onto a record or array of records.
 */
declare function populateUtil(records: unknown[], options: PopulateUtilOptions): Promise<unknown[]>;

declare function shallowPopulate(options: Partial<ShallowPopulateOptions> & Pick<ShallowPopulateOptions, 'include'>): (context: HookContext) => Promise<HookContext>;

/**
 * paramsForServer('$populateParams')
 *
 * In the request, the provided keys will be prepended with an underscore to prevent
 * requiring to add them to the feathers whitelist.
 */
declare function paramsForServer(...whitelist: string[]): (context: HookContext) => void;

declare function paramsFromClient(...whitelist: string[]): (context: HookContext) => HookContext;

declare const definePopulates: <S = string>(populates: Populates<S>) => Populates<S>;

declare function initApp(options?: InitOptions): (app: Application) => void;

declare class GraphPopulateApplication {
    private _app;
    __hooks: any;
    hooks: (hooks: GraphPopulateHook | AnyData | unknown[]) => void;
    options?: InitOptions;
    constructor(app: Application, options?: InitOptions);
    withAppParams(params: SingleGraphPopulateParams | SingleGraphPopulateParams[], method: Method, service: Service<unknown>): SingleGraphPopulateParams[];
    get allowUnnamedQueryForExternal(): boolean | undefined;
}

export { type AnyData, type ChainedParamsOptions, type CumulatedRequestResult, type GetPopulateQueryOptions, GraphPopulateApplication, type GraphPopulateHook, type GraphPopulateHookMap, type GraphPopulateHookOptions, type GraphPopulateHooksObject, type GraphPopulateParams, type InitOptions, type Method, type NestedQuery, type PopulateHookOptions, type PopulateObject, type PopulateParams, type PopulateUtilOptions, type Populates, type ShallowPopulateOptions, type SingleGraphPopulateParams, type Type, initApp as default, definePopulates, getQuery, graphPopulate, paramsForServer, paramsFromClient, populate, populateUtil, shallowPopulate };