grafast 0.0.1-alpha.9 → 0.0.1-beta.2

package/dist/steps/{deepEval.d.ts → applyTransforms.d.ts}

@@ -4,16 +4,29 @@ import type { GrafastError } from "../error.js";
 import type { ExecutionExtra, GrafastResultsList, GrafastValuesList } from "../interfaces.js";
 import type { ListCapableStep } from "../step.js";
 import { ExecutableStep } from "../step.js";
-export declare class DeepEvalStep extends ExecutableStep {
+/**
+ * @internal
+ */
+export declare class ApplyTransformsStep extends ExecutableStep {
     static $$export: {
         moduleName: string;
         exportName: string;
     };
     isSyncAndSafe: boolean;
+    /** Set during query planning.  */
     itemStepId: number;
+    /**
+     * @internal
+     */
     subroutineLayer: LayerPlan<LayerPlanReasonSubroutine>;
     constructor(listPlan: ListCapableStep<any, any>);
     execute(_count: number, values: [GrafastValuesList<any[] | null | undefined | GrafastError>], extra: ExecutionExtra): Promise<GrafastResultsList<any[]>>;
 }
-export declare function deepEval($step: ExecutableStep): ExecutableStep<any>;
-//# sourceMappingURL=deepEval.d.ts.map
+/**
+ * If you want to use a step that might represent a list and you need all of
+ * the `listItem` transforms to have already taken place (e.g. you're going to
+ * send the result to an external service) rather than processing them through
+ * the GraphQL response, then you may need to call `applyTransforms` on it.
+ */
+export declare function applyTransforms($step: ExecutableStep): ExecutableStep<any>;
+//# sourceMappingURL=applyTransforms.d.ts.map

package/dist/steps/connection.d.ts

@@ -2,13 +2,27 @@ import type { ExecutionExtra, GrafastResultsList, InputStep } from "../interface
 import type { ExecutableStep } from "../step.js";
 import { UnbatchedExecutableStep } from "../step.js";
 type ParametersExceptFirst<F> = F extends (arg0: any, ...rest: infer R) => any ? R : never[];
+/**
+ * Describes what a plan needs to implement in order to be suitable for
+ * supplying what the `PageInfo` type requires.
+ */
 export interface PageInfoCapableStep extends ExecutableStep {
     hasNextPage(): ExecutableStep<boolean>;
     hasPreviousPage(): ExecutableStep<boolean>;
     startCursor(): ExecutableStep<string | null>;
     endCursor(): ExecutableStep<string | null>;
 }
+export declare function assertPageInfoCapableStep($step: ExecutableStep | PageInfoCapableStep): asserts $step is PageInfoCapableStep;
+/**
+ * Describes what a plan needs to implement in order to be suitable for
+ * supplying what a ConnectionStep requires.
+ */
 export interface ConnectionCapableStep<TItemStep extends ExecutableStep, TCursorStep extends ExecutableStep> extends ExecutableStep<ReadonlyArray<TItemStep extends ExecutableStep<infer U> ? U : any>> {
+    /**
+     * Clone the plan; it's recommended that you add `$connection` as a
+     * dependency so that you can abort execution early in the case of errors
+     * (e.g. if the cursors cannot be parsed).
+     */
     connectionClone($connection: ConnectionStep<TItemStep, TCursorStep, any, any>, ...args: any[]): ConnectionCapableStep<TItemStep, TCursorStep>;
     pageInfo($connection: ConnectionStep<TItemStep, TCursorStep, ConnectionCapableStep<TItemStep, TCursorStep>, any>): PageInfoCapableStep;
     setFirst($plan: InputStep): void;
@@ -18,6 +32,10 @@ export interface ConnectionCapableStep<TItemStep extends ExecutableStep, TCursor
     setBefore($plan: TCursorStep): void;
     setAfter($plan: TCursorStep): void;
 }
+/**
+ * Handles GraphQL cursor pagination in a standard and consistent way
+ * indepdenent of data source.
+ */
 export declare class ConnectionStep<TItemStep extends ExecutableStep, TCursorStep extends ExecutableStep, TStep extends ConnectionCapableStep<TItemStep, TCursorStep>, TNodeStep extends ExecutableStep = ExecutableStep> extends UnbatchedExecutableStep<unknown> {
     readonly itemPlan?: (($item: TItemStep) => TNodeStep) | undefined;
     readonly cursorPlan?: (($item: TItemStep) => ExecutableStep<string | null> | undefined) | undefined;
@@ -44,9 +62,35 @@ export declare class ConnectionStep<TItemStep extends ExecutableStep, TCursorSte
     setBefore($beforePlan: InputStep): void;
     getAfter(): TCursorStep | null;
     setAfter($afterPlan: InputStep): void;
+    /**
+     * This should not be called after the arguments have been finalized.
+     */
     getSubplan(): TStep;
+    /**
+     * This represents the entire collection with conditions and ordering
+     * applied, but without any pagination constraints (before, after, first,
+     * last, offset) applied. It's useful for the following:
+     *
+     * - performing aggregates e.g. totalCount across the entire collection
+     * - determining fields for pageInfo, e.g. is there a next/previous page
+     *
+     * This cannot be called before the arguments have been finalized.
+     */
     cloneSubplanWithoutPagination(...args: ParametersExceptFirst<TStep["connectionClone"]>): TStep;
+    /**
+     * This represents a single page from the collection - not only have
+     * conditions and ordering been applied but we've also applied the pagination
+     * constraints (before, after, first, last, offset). It's useful for
+     * returning the actual edges and nodes of the connection.
+     *
+     * This cannot be called before the arguments have been finalized.
+     */
     cloneSubplanWithPagination(...args: ParametersExceptFirst<TStep["connectionClone"]> | []): TStep;
+    /**
+     * Subplans may call this from their `setBefore`/`setAfter`/etc plans in order
+     * to add a dependency to us, which is typically useful for adding validation
+     * functions so that they are thrown "earlier", avoiding error bubbling.
+     */
     addValidation(callback: () => ExecutableStep): void;
     edges(): ExecutableStep;
     nodes(): TStep | import("./listTransform.js").__ListTransformStep<any, any, any, any>;
@@ -59,6 +103,7 @@ export interface EdgeCapableStep<TNodeStep extends ExecutableStep> extends Execu
     node(): TNodeStep;
     cursor(): ExecutableStep<string | null>;
 }
+export declare function assertEdgeCapableStep<TNodeStep extends ExecutableStep>($step: ExecutableStep | EdgeCapableStep<TNodeStep>): asserts $step is EdgeCapableStep<TNodeStep>;
 export declare class EdgeStep<TItemStep extends ExecutableStep, TCursorStep extends ExecutableStep, TStep extends ConnectionCapableStep<TItemStep, TCursorStep>, TNodeStep extends ExecutableStep = ExecutableStep> extends UnbatchedExecutableStep implements EdgeCapableStep<TNodeStep> {
     private skipCursor;
     static $$export: {
@@ -79,6 +124,10 @@ export declare class EdgeStep<TItemStep extends ExecutableStep, TCursorStep exte
     deduplicatedWith(replacement: EdgeStep<any, any, any, any>): void;
     unbatchedExecute(_extra: ExecutionExtra, record: any, cursor: any): any;
 }
+/**
+ * Wraps a collection fetch to provide the utilities for working with GraphQL
+ * cursor connections.
+ */
 export declare function connection<TItemStep extends ExecutableStep, TCursorStep extends ExecutableStep, TStep extends ConnectionCapableStep<TItemStep, TCursorStep>, TNodeStep extends ExecutableStep = ExecutableStep>(step: TStep, itemPlan?: ($item: TItemStep) => TNodeStep, cursorPlan?: ($item: TItemStep) => ExecutableStep<string | null>): ConnectionStep<TItemStep, TCursorStep, TStep, TNodeStep>;
 export {};
 //# sourceMappingURL=connection.d.ts.map

package/dist/steps/constant.d.ts

@@ -1,13 +1,17 @@
 import type { GrafastResultsList } from "../interfaces.js";
 import { UnbatchedExecutableStep } from "../step.js";
+/**
+ * Converts a constant value (e.g. a string/number/etc) into a plan
+ */
 export declare class ConstantStep<TData> extends UnbatchedExecutableStep<TData> {
     readonly data: TData;
+    readonly isSensitive: boolean;
     static $$export: {
         moduleName: string;
         exportName: string;
     };
     isSyncAndSafe: boolean;
-    constructor(data: TData);
+    constructor(data: TData, isSensitive?: boolean);
     toStringMeta(): string;
     deduplicate(peers: readonly ConstantStep<any>[]): ConstantStep<any>[];
     execute(count: number): GrafastResultsList<TData>;
@@ -18,6 +22,10 @@ export declare class ConstantStep<TData> extends UnbatchedExecutableStep<TData>
     isNull(): boolean;
     isUndefined(): boolean;
 }
-export declare function constant(strings: TemplateStringsArray & [string]): ConstantStep<string>;
-export declare function constant<TData>(data: TData): ConstantStep<TData>;
+/**
+ * Call this as a template string or as a function. Only intended for handling
+ * scalar values, not arrays/objects/etc.
+ */
+export declare function constant<const TString extends string>(strings: TemplateStringsArray & [TString]): ConstantStep<TString>;
+export declare function constant<TData>(data: TData, isSecret?: boolean): ConstantStep<TData>;
 //# sourceMappingURL=constant.d.ts.map

package/dist/steps/each.d.ts

@@ -2,5 +2,8 @@ import type { ExecutableStep, ListCapableStep } from "../step.js";
 import { __ItemStep } from "./__item.js";
 import type { ConnectionCapableStep } from "./connection.js";
 import type { __ListTransformStep } from "./listTransform.js";
+/**
+ * Transforms a list by wrapping each element in the list with the given mapper.
+ */
 export declare function each<TListStep extends ExecutableStep<readonly any[]> & Partial<ConnectionCapableStep<any, any>>, TResultItemStep extends ExecutableStep>(listStep: TListStep, mapper: (itemPlan: TListStep extends ListCapableStep<any, any> ? ReturnType<TListStep["listItem"]> : __ItemStep<any>) => TResultItemStep): __ListTransformStep<any, any, any, any>;
 //# sourceMappingURL=each.d.ts.map

package/dist/steps/filter.d.ts

@@ -2,5 +2,9 @@ import type { ExecutableStep, ListCapableStep } from "../step.js";
 import type { __ItemStep } from "./__item.js";
 import type { __ListTransformStep, ListTransformItemPlanCallback } from "./listTransform.js";
 export type FilterPlanMemo = unknown[];
+/**
+ * Filters a list plan to only include entries for which the `filterCallback`
+ * plan results in a truthy value.
+ */
 export declare function filter<TListStep extends ExecutableStep<readonly any[]>, TItemStep extends ExecutableStep<boolean>>(listStep: TListStep, filterCallback: ListTransformItemPlanCallback<TListStep, TItemStep>): __ListTransformStep<TListStep, TItemStep, FilterPlanMemo, TListStep extends ListCapableStep<any, any> ? ReturnType<TListStep["listItem"]> : __ItemStep<any>>;
 //# sourceMappingURL=filter.d.ts.map

package/dist/steps/first.d.ts

@@ -14,5 +14,9 @@ export declare class FirstStep<TData> extends UnbatchedExecutableStep<TData> {
     deduplicate(peers: FirstStep<TData>[]): FirstStep<TData>[];
     optimize(): ExecutableStep<any> | this;
 }
+/**
+ * A plan that resolves to the first entry in the list returned by the given
+ * plan.
+ */
 export declare function first<TData>(plan: ExecutableStep<ReadonlyArray<TData>>): FirstStep<TData>;
 //# sourceMappingURL=first.d.ts.map

package/dist/steps/graphqlResolver.d.ts

@@ -4,6 +4,12 @@ import type { ExecutionExtra, GrafastResultsList, GrafastResultStreamList, Grafa
 import type { PolymorphicStep } from "../step.js";
 import { ExecutableStep, UnbatchedExecutableStep } from "../step.js";
 type ResolveInfoBase = Omit<GraphQLResolveInfo, "path" | "rootValue" | "variableValues">;
+/**
+ * Calls the given GraphQL resolver for each input - emulates GraphQL
+ * resolution.
+ *
+ * @internal
+ */
 export declare class GraphQLResolverStep extends UnbatchedExecutableStep {
     private resolver;
     private subscriber;
@@ -20,6 +26,7 @@ export declare class GraphQLResolverStep extends UnbatchedExecutableStep {
     private contextDep;
     private variableValuesDep;
     private rootValueDep;
+    /** root fields can have null parent */
     private isNotRoot;
     constructor(resolver: (GraphQLFieldResolver<any, any> & {
         displayName?: string;
@@ -32,6 +39,7 @@ export declare class GraphQLResolverStep extends UnbatchedExecutableStep {
     unbatchedStream(_extra: ExecutionExtra, source: any, args: any, context: any, variableValues: any, rootValue: any): any;
     stream(count: number, values: ReadonlyArray<GrafastValuesList<any>>, extra: ExecutionExtra): Promise<GrafastResultStreamList<any>>;
 }
+/** @internal */
 export declare class GraphQLItemHandler extends ExecutableStep implements PolymorphicStep {
     static $$export: {
         moduleName: string;
@@ -43,6 +51,10 @@ export declare class GraphQLItemHandler extends ExecutableStep implements Polymo
     constructor($parent: ExecutableStep, nullableType: GraphQLNullableType & GraphQLOutputType);
     planForType(): this;
     listItem($item: __ItemStep<any>): GraphQLItemHandler;
+    /**
+     * Akin to graphql-js' completeAbstractValue... but just the typeName
+     * resolution part.
+     */
     private figureOutTheTypeOf;
     private actuallyWrapData;
     private polymorphicWrapData;
@@ -54,6 +66,12 @@ export declare class GraphQLItemHandler extends ExecutableStep implements Polymo
     execute(_count: number, values: [GrafastValuesList<any>]): GrafastResultsList<any>;
 }
 export declare function graphqlItemHandler($item: ExecutableStep, nullableType: GraphQLNullableType & GraphQLOutputType): GraphQLItemHandler;
+/**
+ * Emulates what GraphQL does when calling a resolver, including handling of
+ * polymorphism.
+ *
+ * @internal
+ */
 export declare function graphqlResolver(resolver: GraphQLFieldResolver<any, any> | null | undefined, subscriber: GraphQLFieldResolver<any, any> | null | undefined, $step: ExecutableStep, $args: ObjectStep, resolveInfoBase: ResolveInfoBase): ExecutableStep;
 export {};
 //# sourceMappingURL=graphqlResolver.d.ts.map

package/dist/steps/groupBy.d.ts

@@ -1,5 +1,11 @@
 import type { ExecutableStep } from "../step.js";
 import type { __ListTransformStep, ListTransformItemPlanCallback } from "./listTransform.js";
 export type GroupByPlanMemo = Map<unknown, unknown[]>;
+/**
+ * Takes a single dimensional list plan and a mapper that returns a grouping
+ * key. Returns a plan that results in a Map where the keys are the grouping
+ * keys and the values are lists of the original entries that match these
+ * grouping keys.
+ */
 export declare function groupBy<TListStep extends ExecutableStep<readonly any[]>, TItemStep extends ExecutableStep<number>>(listStep: TListStep, mapper: ListTransformItemPlanCallback<TListStep, TItemStep>): __ListTransformStep<TListStep, TItemStep, GroupByPlanMemo, any>;
 //# sourceMappingURL=groupBy.d.ts.map

package/dist/steps/index.d.ts

@@ -2,9 +2,13 @@ import type { OperationPlan } from "../index.js";
 import type { __ValueStep } from "./__value.js";
 export declare function operationPlan(): OperationPlan;
 export declare function context<TContext extends Grafast.Context = Grafast.Context>(): __ValueStep<TContext>;
+/**
+ * Turns on debug mode, calls the callback, and then turns debug mode back off
+ * again.
+ */
 export declare function debugPlans<T>(callback: () => T): T;
 export { access, AccessStep } from "./access.js";
-export { connection, ConnectionCapableStep, ConnectionStep, EdgeCapableStep, EdgeStep, PageInfoCapableStep, } from "./connection.js";
+export { assertEdgeCapableStep, assertPageInfoCapableStep, connection, ConnectionCapableStep, ConnectionStep, EdgeCapableStep, EdgeStep, PageInfoCapableStep, } from "./connection.js";
 export { constant, ConstantStep } from "./constant.js";
 export { each } from "./each.js";
 export { error, ErrorStep } from "./error.js";
@@ -28,7 +32,7 @@ export { __InputStaticLeafStep } from "./__inputStaticLeaf.js";
 export { __ItemStep } from "./__item.js";
 export { __TrackedValueStep, __TrackedValueStepWithDollars, } from "./__trackedValue.js";
 export { __ValueStep } from "./__value.js";
-export { deepEval, DeepEvalStep } from "./deepEval.js";
+export { applyTransforms, ApplyTransformsStep } from "./applyTransforms.js";
 export { GraphQLItemHandler, graphqlItemHandler, graphqlResolver, GraphQLResolverStep, } from "./graphqlResolver.js";
 export { LoadedRecordStep, loadMany, LoadManyCallback, loadManyCallback, loadOne, LoadOneCallback, loadOneCallback, LoadOptions, LoadStep, } from "./load.js";
 export { proxy, ProxyStep } from "./proxy.js";

package/dist/steps/lambda.d.ts

@@ -1,6 +1,9 @@
 import type { ExecutionExtra, PromiseOrDirect, UnwrapPlanTuple } from "../interfaces.js";
 import type { ExecutableStep } from "../step.js";
 import { UnbatchedExecutableStep } from "../step.js";
+/**
+ * Calls the given lambda function for each tuple
+ */
 export declare class LambdaStep<TIn, TOut> extends UnbatchedExecutableStep<TOut> {
     private fn;
     static $$export: {
@@ -15,6 +18,11 @@ export declare class LambdaStep<TIn, TOut> extends UnbatchedExecutableStep<TOut>
     deduplicate(peers: LambdaStep<any, any>[]): LambdaStep<TIn, TOut>[];
     unbatchedExecute(_extra: ExecutionExtra, value: TIn): PromiseOrDirect<TOut>;
 }
+/**
+ * A plan that takes the input `$plan` and feeds each value through the `fn`
+ * callback. Note: if you need to pass more than one value, pass a `ListStep`
+ * as the `$plan` argument.
+ */
 declare function lambda<const TIn extends readonly ExecutableStep[], TOut>(plans: TIn, fn: (value: UnwrapPlanTuple<TIn>) => PromiseOrDirect<TOut>, isSyncAndSafe?: boolean): LambdaStep<UnwrapPlanTuple<TIn>, TOut>;
 declare function lambda<const TIn, TOut>($plan: ExecutableStep<TIn> | null | undefined, fn: (value: TIn) => PromiseOrDirect<TOut>, isSyncAndSafe?: boolean): LambdaStep<TIn, TOut>;
 export { lambda };

package/dist/steps/last.d.ts

@@ -13,5 +13,9 @@ export declare class LastStep<TData> extends UnbatchedExecutableStep<TData> {
     deduplicate(peers: LastStep<TData>[]): LastStep<TData>[];
     optimize(): ExecutableStep<any> | this;
 }
+/**
+ * A plan that resolves to the last entry in the list returned by the given
+ * plan.
+ */
 export declare function last<TData>(plan: ExecutableStep<ReadonlyArray<TData>>): LastStep<TData>;
 //# sourceMappingURL=last.d.ts.map

package/dist/steps/list.d.ts

@@ -16,7 +16,14 @@ export declare class ListStep<const TPlanTuple extends readonly ExecutableStep[]
     unbatchedExecute(_extra: ExecutionExtra, ...values: any[]): UnwrapPlanTuple<TPlanTuple>;
     deduplicate(peers: ListStep<TPlanTuple>[]): ListStep<TPlanTuple>[];
     optimize(opts: StepOptimizeOptions): this | ConstantStep<any[]>;
+    /**
+     * Get the original plan at the given index back again.
+     */
     at<TIndex extends keyof TPlanTuple>(index: TIndex): TPlanTuple[TIndex];
 }
+/**
+ * Takes a list of plans and turns it into a single plan that represents the
+ * list of their values.
+ */
 export declare function list<const TPlanTuple extends readonly ExecutableStep[]>(list: TPlanTuple): ListStep<TPlanTuple>;
 //# sourceMappingURL=list.d.ts.map

package/dist/steps/listTransform.d.ts

@@ -19,6 +19,15 @@ export interface ListTransformOptions<TListStep extends ExecutableStep<readonly
     optimize?: (this: __ListTransformStep<TListStep, TDepsStep, TMemo, TItemStep>) => ExecutableStep;
     connectionClone?: ConnectionCapableStep<TListStep, any>["connectionClone"];
 }
+/**
+ * **Experimental.**
+ *
+ * A "special" plan that has custom handling in Grafast. Used for turning lists
+ * into other things (or maybe more lists!).
+ *
+ * It's recommended that you don't use this directly, please use one of the
+ * functions that uses this under the hood such as `filter()`.
+ */
 export declare class __ListTransformStep<TListStep extends ExecutableStep<readonly any[]> = ExecutableStep<readonly any[]>, TDepsStep extends ExecutableStep = ExecutableStep, TMemo = any, TItemStep extends ExecutableStep | undefined = ExecutableStep | undefined> extends ExecutableStep<TMemo> {
     static $$export: {
         moduleName: string;
@@ -33,7 +42,11 @@ export declare class __ListTransformStep<TListStep extends ExecutableStep<readon
     listItem?: (itemPlan: __ItemStep<this>) => TItemStep;
     private meta;
     connectionClone?: ConnectionCapableStep<TListStep, any>["connectionClone"];
+    /** Set during query planning.  */
     itemStepId: number;
+    /**
+     * @internal
+     */
     subroutineLayer: LayerPlan<LayerPlanReasonSubroutine>;
     constructor(options: ListTransformOptions<TListStep, TDepsStep, TMemo, TItemStep>);
     toStringMeta(): string | null;
@@ -44,5 +57,13 @@ export declare class __ListTransformStep<TListStep extends ExecutableStep<readon
     optimize(): ExecutableStep;
     execute(_count: number, values: [GrafastValuesList<any[] | null | undefined | GrafastError>], extra: ExecutionExtra): Promise<GrafastResultsList<TMemo>>;
 }
+/**
+ * **Experimental.**
+ *
+ * A "special" plan that has custom handling in Grafast. Used for turning lists
+ * into other things (or maybe more lists!).
+ *
+ * {@page ~grafast/steps/listTransform.md}
+ */
 export declare function listTransform<TListStep extends ExecutableStep<readonly any[]>, TDepsStep extends ExecutableStep, TMemo, TItemStep extends ExecutableStep | undefined = undefined>(options: ListTransformOptions<TListStep, TDepsStep, TMemo, TItemStep>): __ListTransformStep<TListStep, TDepsStep, TMemo, TItemStep>;
 //# sourceMappingURL=listTransform.d.ts.map

package/dist/steps/listen.d.ts

@@ -2,6 +2,11 @@ import type { GrafastResultStreamList, GrafastSubscriber, GrafastValuesList } fr
 import type { StreamableStep } from "../step.js";
 import { ExecutableStep } from "../step.js";
 import type { __ItemStep } from "./__item.js";
+/**
+ * Subscribes to the given `pubsubOrPlan` to get realtime updates on a given
+ * topic (`topicOrPlan`), mapping the resulting event via the `itemPlan`
+ * callback.
+ */
 export declare class ListenStep<TTopics extends {
     [topic: string]: any;
 }, TTopic extends keyof TTopics, TPayloadStep extends ExecutableStep> extends ExecutableStep<TTopics[TTopic]> implements StreamableStep<TTopics[TTopic]> {
@@ -11,7 +16,13 @@ export declare class ListenStep<TTopics extends {
         exportName: string;
     };
     isSyncAndSafe: boolean;
+    /**
+     * The id for the PostgreSQL context plan.
+     */
     private pubsubDep;
+    /**
+     * The plan that will tell us which topic we're subscribing to.
+     */
     private topicDep;
     constructor(pubsubOrPlan: ExecutableStep<GrafastSubscriber<TTopics> | null> | GrafastSubscriber<TTopics> | null, topicOrPlan: ExecutableStep<TTopic> | string, itemPlan?: (itemPlan: __ItemStep<TTopics[TTopic]>) => TPayloadStep);
     execute(): never;
@@ -20,6 +31,11 @@ export declare class ListenStep<TTopics extends {
         GrafastValuesList<TTopic>
     ]): GrafastResultStreamList<TTopics[TTopic]>;
 }
+/**
+ * Subscribes to the given `pubsubOrPlan` to get realtime updates on a given
+ * topic (`topicOrPlan`), mapping the resulting event via the `itemPlan`
+ * callback.
+ */
 export declare function listen<TTopics extends {
     [topic: string]: any;
 }, TTopic extends keyof TTopics, TPayloadStep extends ExecutableStep>(pubsubOrPlan: ExecutableStep<GrafastSubscriber<TTopics> | null> | GrafastSubscriber<TTopics> | null, topicOrPlan: ExecutableStep<TTopic> | string, itemPlan?: (itemPlan: __ItemStep<TTopics[TTopic]>) => TPayloadStep): ListenStep<TTopics, TTopic, TPayloadStep>;

package/dist/steps/load.d.ts

@@ -11,8 +11,21 @@ type LoadCallback<TSpec, TItem, TData extends TItem | ReadonlyArray<TItem>, TPar
 };
 export type LoadOneCallback<TSpec, TItem, TParams extends Record<string, any>> = LoadCallback<TSpec, TItem, TItem, TParams>;
 export type LoadManyCallback<TSpec, TItem, TParams extends Record<string, any>> = LoadCallback<TSpec, TItem, ReadonlyArray<TItem>, TParams>;
+/**
+ * A TypeScript Identity Function to help you strongly type your
+ * LoadOneCallback.
+ */
 export declare function loadOneCallback<TSpec, TItem, TParams extends Record<string, any>>(callback: LoadOneCallback<TSpec, TItem, TParams>): LoadOneCallback<TSpec, TItem, TParams>;
+/**
+ * A TypeScript Identity Function to help you strongly type your
+ * LoadManyCallback.
+ */
 export declare function loadManyCallback<TSpec, TItem, TParams extends Record<string, any>>(callback: LoadManyCallback<TSpec, TItem, TParams>): LoadManyCallback<TSpec, TItem, TParams>;
+/**
+ * You shouldn't create instances of this yourself - use `loadOne` or `loadMany` instead.
+ *
+ * @internal
+ */
 export declare class LoadedRecordStep<TItem, TParams extends Record<string, any>> extends ExecutableStep<TItem> {
     private isSingle;
     private sourceDescription;

package/dist/steps/node.d.ts

@@ -1,10 +1,14 @@
 import type { GraphQLObjectType } from "graphql";
-import type { ExecutionExtra, NodeIdCodec, NodeIdHandler, PolymorphicData } from "../interfaces.js";
+import type { ExecutionExtra, NodeIdHandler, PolymorphicData } from "../interfaces.js";
 import type { ExecutableStep, PolymorphicStep } from "../step.js";
 import { UnbatchedExecutableStep } from "../step.js";
-export declare class NodeStep<TCodecs extends {
-    [key: string]: NodeIdCodec<any>;
-}> extends UnbatchedExecutableStep implements PolymorphicStep {
+/**
+ * A plan to get a Node by it's global object identifier (string). Accepts an
+ * object specifying the supported codecs, an object map detailing the
+ * typeNames supported and their details (codec to use, how to find the record,
+ * etc), and finally the Node id string plan.
+ */
+export declare class NodeStep extends UnbatchedExecutableStep implements PolymorphicStep {
     private possibleTypes;
     static $$export: {
         moduleName: string;
@@ -13,17 +17,21 @@ export declare class NodeStep<TCodecs extends {
     isSyncAndSafe: boolean;
     allowMultipleOptimizations: boolean;
     private specPlanDep;
-    constructor(codecs: TCodecs, possibleTypes: {
-        [typeName: string]: NodeIdHandler<TCodecs>;
+    constructor(possibleTypes: {
+        [typeName: string]: NodeIdHandler;
     }, $id: ExecutableStep<string>);
     planForType(type: GraphQLObjectType): ExecutableStep;
     private getTypeNameFromSpecifier;
     unbatchedExecute: (_extra: ExecutionExtra, specifier: any) => PolymorphicData<string, ReadonlyArray<any>> | null;
 }
-export declare function node<TCodecs extends {
-    [key: string]: NodeIdCodec<any>;
-}>(codecs: TCodecs, possibleTypes: {
-    [typeName: string]: NodeIdHandler<TCodecs>;
-}, $id: ExecutableStep<string>): NodeStep<TCodecs>;
-export declare function specFromNodeId(codec: NodeIdCodec<any>, handler: NodeIdHandler<any>, $id: ExecutableStep<string>): any;
+/**
+ * A plan to get a Node by it's global object identifier (string). Accepts an
+ * object specifying the supported codecs, an object map detailing the
+ * typeNames supported and their details (codec to use, how to find the record,
+ * etc), and finally the Node id string plan.
+ */
+export declare function node(possibleTypes: {
+    [typeName: string]: NodeIdHandler;
+}, $id: ExecutableStep<string>): NodeStep;
+export declare function specFromNodeId(handler: NodeIdHandler<any>, $id: ExecutableStep<string>): any;
 //# sourceMappingURL=node.d.ts.map

package/dist/steps/object.d.ts

@@ -20,6 +20,10 @@ export interface ObjectPlanMeta<TPlans extends {
 }> {
     results: Results<TPlans>;
 }
+/**
+ * A plan that represents an object using the keys given and the values being
+ * the results of the associated plans.
+ */
 export declare class ObjectStep<TPlans extends {
     [key: string]: ExecutableStep;
 } = {
@@ -34,6 +38,10 @@ export declare class ObjectStep<TPlans extends {
     private keys;
     optimizeMetaKey: string;
     constructor(obj: TPlans);
+    /**
+     * This key doesn't get typed, but it can be added later which can be quite
+     * handy.
+     */
     set<TKey extends keyof TPlans>(key: TKey, plan: TPlans[TKey]): void;
     getStepForKey<TKey extends keyof TPlans>(key: TKey, allowMissing?: boolean): TKey extends keyof TPlans ? TPlans[TKey] : null;
     toStringMeta(): string;
@@ -43,8 +51,15 @@ export declare class ObjectStep<TPlans extends {
     unbatchedExecute(_extra: ExecutionExtra, ..._values: any[]): any;
     deduplicate(peers: ObjectStep<any>[]): ObjectStep<TPlans>[];
     optimize(opts: StepOptimizeOptions): this | ConstantStep<any>;
+    /**
+     * Get the original plan with the given key back again.
+     */
     get<TKey extends keyof TPlans>(key: TKey): TPlans[TKey];
 }
+/**
+ * A plan that represents an object using the keys given and the values being
+ * the results of the associated plans.
+ */
 export declare function object<TPlans extends {
     [key: string]: ExecutableStep;
 }>(obj: TPlans): ObjectStep<TPlans>;

package/dist/steps/partitionByIndex.d.ts

@@ -1,4 +1,39 @@
 import type { ExecutableStep } from "../step.js";
 import type { __ListTransformStep, ListTransformItemPlanCallback } from "./listTransform.js";
+/**
+ * Takes a single dimensional list plan and a mapper that calculates a
+ * (potentially duplicate) target index for each entry in the list. Returns a
+ * plan that results in a two dimensional list of the items in the original
+ * list partitioned (grouped) by their target index.
+ *
+ * If your datasource returns indexes that are 1-indexed then you may pass `1`
+ * as the third argument and we'll account for this.
+ *
+ * @example For this data:
+ *
+ * ```jsonc
+ * [
+ *   {"array_idx": 1, "id": "b0b00000-0000-0000-0000-000000000b0b", "username": "Bob"},
+ *   {"array_idx": 2, "id": "a11ce000-0000-0000-0000-0000000a11ce", "username": "Alice"}],
+ *   {"array_idx": 2, "id": "cec111a0-0000-0000-0000-00000cec111a", "username": "Cecilia"}],
+ * ]
+ * ```
+ *
+ * partitioning by the array_idx (which is 1-indexed), would result in:
+ *
+ * ```jsonc
+ * [
+ *   [
+ *     {"array_idx": 1, "id": "b0b00000-0000-0000-0000-000000000b0b", "username": "Bob"},
+ *   ],
+ *   [
+ *     {"array_idx": 2, "id": "a11ce000-0000-0000-0000-0000000a11ce", "username": "Alice"}],
+ *     {"array_idx": 2, "id": "cec111a0-0000-0000-0000-00000cec111a", "username": "Cecilia"}],
+ *   ],
+ * ]
+ * ```
+ *
+ * Beware: the target indexes should not contain gaps.
+ */
 export declare function partitionByIndex<TListStep extends ExecutableStep<readonly any[]>, TItemStep extends ExecutableStep<number>>(listStep: TListStep, mapper: ListTransformItemPlanCallback<TListStep, TItemStep>, startIndex?: 0 | 1): __ListTransformStep<TListStep, TItemStep, unknown[][], any>;
 //# sourceMappingURL=partitionByIndex.d.ts.map

package/dist/steps/proxy.d.ts

@@ -3,6 +3,11 @@ import type { ExecutionExtra } from "../interfaces.js";
 import { $$proxy } from "../interfaces.js";
 import type { ExecutableStep } from "../step.js";
 import { UnbatchedExecutableStep } from "../step.js";
+/**
+ * @experimental
+ *
+ * Never build this class directly.
+ */
 export declare class ProxyStep<T> extends UnbatchedExecutableStep<T> {
     static $$export: {
         moduleName: string;
@@ -22,6 +27,12 @@ declare module "../step.js" {
         [$$proxy]?: any;
     }
 }
+/**
+ * @experimental
+ *
+ * This could change at any time, may impact performance, and just, generally,
+ * needs more work. You shouldn't need this in the vast majority of cases.
+ */
 export declare function proxy<TData, TStep extends ExecutableStep<TData>>($step: TStep, $actualDep?: ExecutableStep): TStep & {
     addDependency(step: ExecutableStep): number;
 };

package/dist/steps/remapKeys.d.ts

@@ -4,6 +4,10 @@ import { UnbatchedExecutableStep } from "../step.js";
 export type ActualKeyByDesiredKey = {
     [desiredKey: string]: string;
 };
+/**
+ * A plan that returns an object resulting from extracting the given
+ * `actualKey` from the input and storing it as the `desiredKey` in the output.
+ */
 export declare class RemapKeysStep extends UnbatchedExecutableStep {
     private actualKeyByDesiredKey;
     static $$export: {
@@ -21,6 +25,10 @@ export declare class RemapKeysStep extends UnbatchedExecutableStep {
     unbatchedExecute(_extra: ExecutionExtra, value: any): any;
     deduplicate(peers: RemapKeysStep[]): RemapKeysStep[];
 }
+/**
+ * A plan that returns an object resulting from extracting the given
+ * `actualKey` from the input and storing it as the `desiredKey` in the output.
+ */
 export declare function remapKeys($step: ExecutableStep, actualKeyByDesiredKey: {
     [desiredKey: string]: string;
 }): RemapKeysStep;

package/dist/steps/reverse.d.ts

@@ -1,7 +1,13 @@
 import type { ExecutionExtra, GrafastResultsList, GrafastValuesList } from "../interfaces.js";
 import type { ExecutableStep } from "../step.js";
 import { UnbatchedExecutableStep } from "../step.js";
+/**
+ * Returns a reversed copy of the list.
+ */
 export declare function reverseArray<TData = any>(list: readonly TData[]): TData[];
+/**
+ * Reverses a list.
+ */
 export declare class ReverseStep<TData> extends UnbatchedExecutableStep<readonly TData[]> {
     static $$export: {
         moduleName: string;
@@ -14,5 +20,8 @@ export declare class ReverseStep<TData> extends UnbatchedExecutableStep<readonly
     unbatchedExecute(_extra: ExecutionExtra, arr: TData[]): TData[];
     deduplicate(peers: ReverseStep<TData>[]): ReverseStep<TData>[];
 }
+/**
+ * Reverses a list.
+ */
 export declare function reverse<TData>(plan: ExecutableStep<readonly TData[]>): ReverseStep<TData>;
 //# sourceMappingURL=reverse.d.ts.map

package/dist/subscribe.d.ts

@@ -1,4 +1,8 @@
 import type { AsyncExecutionResult, ExecutionArgs, ExecutionResult } from "graphql";
 import type { PromiseOrValue } from "graphql/jsutils/PromiseOrValue";
+/**
+ * Use this instead of GraphQL.js' subscribe method and we'll automatically
+ * run grafastPrepare for you and handle the result.
+ */
 export declare function subscribe(args: ExecutionArgs, resolvedPreset?: GraphileConfig.ResolvedPreset, outputDataAsString?: boolean): PromiseOrValue<AsyncGenerator<ExecutionResult | AsyncExecutionResult, void, void> | ExecutionResult>;
 //# sourceMappingURL=subscribe.d.ts.map