packages/db/src/process.ts
/**
* @category Primary
* @packageDocumentation
*/
import { logger } from "@truffle/db/logger";
const debug = logger("db:process");
import type * as graphql from "graphql";
import type * as Meta from "./meta";
import * as System from "./system";
import type {
Collections,
CollectionName,
Input,
Resource,
IdObject
} from "./resources";
/**
* @hidden
*/
export type Process<
T = any,
R extends RequestType | undefined = undefined
> = Meta.Process.Process<Collections, T, R>;
/**
* @hidden
*/
export type Processor<
A extends unknown[],
T = any,
R extends RequestType | undefined = undefined
> = Meta.Process.Processor<Collections, A, T, R>;
/**
* @hidden
*/
export type RequestType = Meta.Process.RequestType<Collections>;
/**
* @hidden
*/
export type QueryName<
N extends CollectionName = CollectionName
> = Meta.Process.QueryName<Collections, N>;
/**
* @hidden
*/
export type Query<Q extends QueryName = QueryName> = Meta.Process.Query<
Collections,
Q
>;
/**
* @hidden
*/
export type MutationName<
N extends CollectionName = CollectionName
> = Meta.Process.MutationName<Collections, N>;
/**
* @hidden
*/
export type Mutation<
M extends MutationName = MutationName
> = Meta.Process.Mutation<Collections, M>;
/**
* @hidden
*/
export type ProcessRequest<
R extends RequestType | undefined
> = Meta.Process.ProcessRequest<Collections, R>;
/**
* @hidden
*/
export type ProcessorRunner = Meta.Process.ProcessorRunner<Collections>;
export namespace ResourceProcessors {
/**
* `resources.load`
*
* Loads resource inputs and processes into
* corresponding [[IdObject | IdObjects]].
*
* The resulting array will always have the same length as the inputs, with
* each result corresponding to the input at the same index. Invalid inputs
* correspond to `null` resource results.
*
* **Note**: This function returns a generator. For `async` behavior, use
* with a [[Meta.Process.ProcessorRunner | ProcessorRunner]] such as
* that returned by [[Run.forDb]] or [[Project.run]].
*
* @example
* ```typescript
* import { connect, Resources, Process } from "@truffle/db";
*
* const db = connect({
* // ...
* });
*
* const { Run, resources } = Process;
*
* const { run } = Run.forDb(db);
*
* const sources: (
* | Resources.IdObject<"sources">
* | null
* )[] = await run(resources.load, "sources", [
* { sourcePath: "...", contents: "..." }
* ]);
* ```
*/
export type Load = <N extends CollectionName>(
collectionName: N,
inputs: (Input<N> | undefined)[]
) => Process<(IdObject<N> | undefined)[]>;
/**
* `resources.get`
*
* Retrieves full or partial representations of a resource given its ID.
* Parameter `document` is a GraphQL DocumentNode that defines a fragment
* on the resource object type, to control which fields are returned.
*
* **Note**: This function returns a generator. For `async` behavior, use
* with a [[Meta.Process.ProcessorRunner | ProcessorRunner]] such as
* that returned by [[Run.forDb]] or [[Project.run]].
*
* @example
* ```typescript
* import gql from "graphql-tag";
* import { connect, Process } from "@truffle/db";
*
* const db = connect({
* // ...
* });
*
* const { Run, resources } = Process;
*
* const { run } = Run.forDb(db);
*
* const { contents } = await run(resources.get, "sources", "0x...", gql`
* fragment Contents on Source {
* contents
* }
* `);
* ```
*/
export type Get = <N extends CollectionName>(
collectionName: N,
id: string,
document: graphql.DocumentNode
) => Process<Resource<N> | undefined>;
/**
* `resources.find`
*
* Retrieves full or partial representations of all resources in a list of
* given IDs.
* Parameter `document` is a GraphQL DocumentNode that defines a fragment
* on the resource object type, to control which fields are returned.
*
* The resulting array will always have the same length as the provided IDs,
* with each result corresponding to the ID at the same index. Unknown IDs
* will have `null` entries in the resulting array.
*
* **Note**: This function returns a generator. For `async` behavior, use
* with a [[Meta.Process.ProcessorRunner | ProcessorRunner]] such as
* that returned by [[Run.forDb]] or [[Project.run]].
*
* @example
* ```typescript
* import gql from "graphql-tag";
* import { connect, Process } from "@truffle/db";
*
* const db = connect({
* // ...
* });
*
* const { Run, resources } = Process;
*
* const { run } = Run.forDb(db);
*
* const sources: (
* | Pick<Resources.Resource<"sources">, "contents">
* | null
* )[] = await run(resources.find, "sources", ["0x...", "0x..."], gql`
* fragment Contents on Source {
* contents
* }
* `);
* ```
*/
export type Find = <N extends CollectionName>(
collectionName: N,
ids: (string | undefined)[],
document: graphql.DocumentNode
) => Process<(Resource<N> | undefined)[]>;
/**
* `resources.all`
*
* Retrieves full or partial representations of all known resources for a
* given collection name.
* Parameter `document` is a GraphQL DocumentNode that defines a fragment
* on the resource object type, to control which fields are returned.
*
* **Note**: This function returns a generator. For `async` behavior, use
* with a [[Meta.Process.ProcessorRunner | ProcessorRunner]] such as
* that returned by [[Run.forDb]] or [[Project.run]].
*
* @example
* ```typescript
* import gql from "graphql-tag";
* import { connect, Resources, Process } from "@truffle/db";
*
* const db = connect({
* // ...
* });
*
* const { Run, resources } = Process;
*
* const { run } = Run.forDb(db);
*
* const sources: Pick<
* Resources.Resource<"sources">,
* "contents"
* >[] = await run(resources.all, "sources", gql`
* fragment Contents on Source {
* contents
* }
* `);
* ```
*/
export type All = <N extends CollectionName>(
collectionName: N,
document: graphql.DocumentNode
) => Process<Resource<N>[]>;
}
/**
* Programmatic interfaces for reading/writing resources.
*
* **Note**: These functions return generators. For `async` behavior, use
* with a [[Meta.Process.ProcessorRunner | ProcessorRunner]] such as
* that returned by [[Run.forDb]] or [[Project.run]].
*
* For full documentation, please see [[ResourceProcessors]] or links to
* specific function types below.
*
* @example
* ```typescript
* import { Process } from "@truffle/db";
* const { resources } = Process;
* ```
*/
export const resources: {
load: ResourceProcessors.Load;
get: ResourceProcessors.Get;
find: ResourceProcessors.Find;
all: ResourceProcessors.All;
} = System.resources;
export namespace Run {
export const forDb = System.forDb;
}