grafast 0.1.1-beta.2 → 0.1.1-beta.21

package/dist/step.d.ts

@@ -1,88 +1,21 @@
 import type { GraphQLObjectType } from "graphql";
 import type { LayerPlan, LayerPlanReasonSubroutine } from "./engine/LayerPlan.js";
 import type { OperationPlan } from "./engine/OperationPlan.js";
-import type { ExecutionExtra, GrafastResultsList, GrafastResultStreamList, GrafastValuesList, JSONValue, PromiseOrDirect, StepOptimizeOptions, StepOptions } from "./interfaces.js";
+import type { AddDependencyOptions, DependencyOptions, ExecutionDetails, ExecutionEntryFlags, ExecutionResults, GrafastResultsList, JSONValue, PromiseOrDirect, StepOptimizeOptions, UnbatchedExecutionExtra } from "./interfaces.js";
 import { $$subroutine } from "./interfaces.js";
-import type { __ItemStep } from "./steps/index.js";
-/**
- * @internal
- */
-export declare const $$deepDepSkip: unique symbol;
-/**
- * This indicates that a step never executes (e.g. __ItemStep and __ValueStep)
- * and thus when executed skips direct to reallyCompletedStep.
- *
- * @internal
- */
-export declare const $$noExec: unique symbol;
-declare function reallyAssertFinalized(plan: BaseStep): void;
+import type { __FlagStep, __ItemStep } from "./steps/index.js";
+declare function reallyAssertFinalized(plan: Step): void;
 export declare const assertFinalized: typeof reallyAssertFinalized;
 /**
- * The base abstract plan type; you should not extend this directly - instead
- * use an ExecutableStep (for use when planning output fields) or a
- * ModifierStep (for use when planning arguments/input fields).
- *
- * @remarks
- *
- * Though it might seem that ModifierStep should be used for all inputs
- * (arguments, input objects), this is not the case. When planning an output
- * field, all inputs to it (including arguments, parent plan, context, etc)
- * should be other executable plans. The only time that ModifierStep is used is
- * when writing specific plans as part of the argument or input field
- * definitions themself; even in these cases the inputs to these plan resolvers
- * will be ExecutablePlans.
+ * Executable plans are the plans associated with leaves on the GraphQL tree,
+ * they must be able to execute to return values.
  */
-export declare abstract class BaseStep {
-    /**
-     * This identifies the "bucket" into which this plan's results will be stored.
-     * New buckets are introduced when you cross boundaries that may change the
-     * number of results in the bucket, or where control over execution is desired.
-     *
-     * - Lists / list items (generally multiplies up)
-     * - Polymorphism - different entries may go into different buckets
-     * - Mutations - early termination is likely
-     * - Defer boundaries - don't execute this stuff until later
-     * - null boundaries - if a null is met, no need to continue execution
-     *
-     * This bucket influences:
-     *
-     * 1. how plans are deduplicated
-     * 2. the order in which the plans are executed
-     * 3. where the result of executing the plan is stored
-     * 4. when the plan execution cache is allowed to be GC'd
-     *
-     * NOTE: `__ListTransformStep`'s effectively have a temporary bucket inside
-     * them (built on the `__Item`) that's thrown away once the transform is
-     * complete.
-     *
-     * @internal
-     */
-    readonly layerPlan: LayerPlan;
+export declare class Step<TData = any> {
     readonly operationPlan: OperationPlan;
     [$$subroutine]: LayerPlan<LayerPlanReasonSubroutine> | null;
     isArgumentsFinalized: boolean;
     isFinalized: boolean;
     debug: boolean;
-    /**
-     * Set this true for plans that implement mutations; this will prevent them
-     * from being tree-shaken.
-     */
-    hasSideEffects: boolean;
-    constructor();
-    toString(): string;
-    /**
-     * This metadata will be merged into toString when referencing this plan.
-     */
-    toStringMeta(): string | null;
-    planJSONExtra(): Record<string, JSONValue | undefined> | undefined;
-    finalize(): void;
-    destroy(): void;
-}
-/**
- * Executable plans are the plans associated with leaves on the GraphQL tree,
- * they must be able to execute to return values.
- */
-export declare class ExecutableStep<TData = any> extends BaseStep {
     static $$export: any;
     /**
      * Setting this true is a performance optimisation, but it comes with strong
@@ -95,7 +28,7 @@ export declare class ExecutableStep<TData = any> extends BaseStep {
      * - The `execute` method must be a regular (not async) function
      * - The `execute` method must NEVER return a promise
      * - The values within the list returned from `execute` must NEVER include
-     *   promises or GrafastError objects
+     *   promises or FlaggedValue objects
      * - The result of calling `execute` should not differ after a
      *   `step.hasSideEffects` has executed (i.e. it should be pure, only
      *   dependent on its deps and use no external state)
@@ -108,23 +41,15 @@ export declare class ExecutableStep<TData = any> extends BaseStep {
      */
     isSyncAndSafe: boolean;
     /**
-     * The plan this plan will need data from in order to execute.
-     * @internal
+     * (default = ALL_FLAGS & ~FLAG_NULL)
      */
-    readonly dependencies: ReadonlyArray<ExecutableStep>;
+    protected readonly defaultForbiddenFlags: ExecutionEntryFlags;
     /**
-     * Just for mermaid
-     * @internal
+     * The plan this plan will need data from in order to execute.
      */
-    readonly dependents: ReadonlyArray<{
-        step: ExecutableStep;
-        dependencyIndex: number;
-    }>;
+    protected readonly dependencies: ReadonlyArray<Step>;
     /**
-     * We reserve the right to change our mind as to whether this is a string or
-     * number.
-     *
-     * @internal
+     * Unique identifier for this step within the plan.
      */
     readonly id: number;
     /**
@@ -139,19 +64,6 @@ export declare class ExecutableStep<TData = any> extends BaseStep {
      * AccessStep).
      */
     allowMultipleOptimizations: boolean;
-    /** @internal */
-    _stepOptions: StepOptions;
-    /** @internal */
-    polymorphicPaths: ReadonlySet<string> | null;
-    /**
-     * True if this needs to be permanently stored; for example:
-     *
-     * - Is the dep of another LayerPlan
-     * - Is used in an OutputPlan
-     *
-     * @internal
-     */
-    store: boolean;
     /**
      * Set the metaKey so `execute` will be passed a meta object to use.
      * Depending on what you set it to, you can share execution meta between
@@ -164,19 +76,70 @@ export declare class ExecutableStep<TData = any> extends BaseStep {
      * Like `metaKey` but for the optimize phase
      */
     optimizeMetaKey: number | string | symbol | undefined;
+    /**
+     * If the peerKey of two steps do not match, then they are definitely not
+     * peers. Use this to reduce the load on deduplicate by more quickly
+     * eradicating definitely-not-peers.
+     *
+     * Note: we may well change this to be a function in future, so it's advised
+     * that you don't use this unless you're working inside the graphile/crystal
+     * core codebase.
+     *
+     * @experimental
+     */
+    peerKey: string | null;
+    /**
+     * Set this true for plans that implement mutations; this will prevent them
+     * from being tree-shaken.
+     */
+    hasSideEffects: boolean;
     constructor();
+    /**
+     * Generally you should only use this once the dependencies of a step are
+     * established, if you use it beforehand and it returns `true` then adding a
+     * non-unary dependency later will result in an error.
+     */
+    getAndFreezeIsUnary(): boolean;
     protected withMyLayerPlan<T>(callback: () => T): T;
-    protected getStep(id: number): ExecutableStep;
-    getDep(depId: number): ExecutableStep;
+    /** @experimental */
+    withLayerPlan<T>(callback: () => T): T;
+    protected getStep(id: number): Step;
+    protected getDepOptions<TStep extends Step = Step>(depId: number): DependencyOptions<TStep>;
+    protected getDep<TStep extends Step = Step>(_depId: number): TStep | __FlagStep<TStep>;
+    protected getDep<TStep extends Step = Step>(_depId: number, throwOnFlagged: true): TStep;
+    protected maybeGetDep<TStep extends Step = Step>(depId: number | null | undefined): TStep | __FlagStep<TStep> | null;
+    protected maybeGetDep<TStep extends Step = Step>(depId: number | null | undefined, throwOnFlagged: true): TStep | null;
+    protected getDepOrConstant<TData = any>(_depId: number | null, _fallback: TData): Step<TData>;
     /**
      * Like getDep, except it skips over __ItemStep and similar steps to get to
      * where the parent really is.
      *
      * @experimental
      */
-    protected getDepDeep(depId: number): ExecutableStep;
+    protected getDepDeep(depId: number): Step;
+    /**
+     * Cache a generated step by a given identifier (cacheKey) such that we don't
+     * need to regenerate it on future calls, significantly reducing the load on
+     * deduplication later.
+     *
+     * @experimental
+     */
+    protected cacheStep<T extends Step>(actionKey: string, cacheKey: symbol | string | number, cb: () => T): T;
     toString(): string;
-    protected addDependency(step: ExecutableStep, skipDeduplication?: boolean): number;
+    /**
+     * This metadata will be merged into toString when referencing this plan.
+     */
+    toStringMeta(): string | null;
+    planJSONExtra(): Record<string, JSONValue | undefined> | undefined;
+    protected canAddDependency(step: Step): boolean;
+    protected addDependency(stepOrOptions: Step | AddDependencyOptions): number;
+    /**
+     * Adds "unary" dependencies; in `execute({count, values})` you'll receive a
+     * `values[index]` (where `index` is the return value of this function) with
+     * `isBatch = false` so you can use the `values[index].value` property
+     * directly.
+     */
+    protected addUnaryDependency(stepOrOptions: Step | AddDependencyOptions): number;
     /**
      * Given a list of "peer" steps, return a list of these `peers` that are
      * equivalent to this step.
@@ -187,27 +150,34 @@ export declare class ExecutableStep<TData = any> extends BaseStep {
      * If you need to transform the peer to be equivalent you should do so via
      * the `deduplicatedWith` callback later.
      */
-    deduplicate?(_peers: readonly ExecutableStep[]): readonly ExecutableStep[];
+    deduplicate?(_peers: readonly Step[]): readonly Step[];
     /**
      * If this plan is replaced via deduplication, this method gives it a chance
      * to hand over its responsibilities to its replacement.
      */
-    deduplicatedWith?(replacement: ExecutableStep): void;
+    deduplicatedWith?(replacement: Step): void;
     /**
      * Our chance to optimise the plan (which could go as far as to inline the
      * plan into the parent plan).
      */
-    optimize?(_options: StepOptimizeOptions): ExecutableStep;
+    optimize?(_options: StepOptimizeOptions): Step;
     finalize(): void;
     /**
-     * This function will be called with a `values` list: an array of entries for
-     * each incoming grafast object, where each entry in the array is a list of
-     * the values retrieved from executing the plans in `this.dependencies` for
-     * that grafast object.
+     * This function will be called with 'execution details', an object containing:
      *
-     * It must return a list with the same length as `values`, where each value
-     * in the list relates to the result of executing this plan for the
-     * corresponding entry in the `values` list.
+     * - `count`: the number of entries in the batch that's being executed
+     * - `values`: a tuple representing the runtime values of the steps
+     *   dependencies; each value in the tuple is an object, either a batch object
+     *   containing a list of size `count` containing the values, or a unary
+     *   object containing the single value common to all entries.
+     * - `indexMap`: helper function to map over each index from `0` to `count-1`,
+     *   returning the resulting array.
+     * - `indexForEach`: as `indexMap`, but without the array result.
+     * - `meta`: [experimental]
+     *
+     * `execute` must return a list with `count` entries, where each value in the
+     * list relates to the result of executing this plan for the corresponding
+     * entry in each of the entries in the `values` tuple.
      *
      * IMPORTANT: it is up to the execute function to cache/memoize results as
      * appropriate for performance, this can be done via the `meta` object.
@@ -217,81 +187,57 @@ export declare class ExecutableStep<TData = any> extends BaseStep {
      * add attributes to meta for each purpose (e.g. use `meta.cache` for
      * memoizing results) so that you can expand your usage of meta in future.
      */
-    execute(count: number, values: ReadonlyArray<GrafastValuesList<any>>, extra: ExecutionExtra): PromiseOrDirect<GrafastResultsList<TData>>;
+    execute(details: ExecutionDetails): ExecutionResults<TData>;
     destroy(): void;
 }
-export declare abstract class UnbatchedExecutableStep<TData = any> extends ExecutableStep<TData> {
+export declare abstract class UnbatchedStep<TData = any> extends Step<TData> {
     static $$export: {
         moduleName: string;
         exportName: string;
     };
     finalize(): void;
-    execute(count: number, values: ReadonlyArray<GrafastValuesList<any>>, extra: ExecutionExtra): PromiseOrDirect<GrafastResultsList<TData>>;
-    abstract unbatchedExecute(extra: ExecutionExtra, ...tuple: any[]): PromiseOrDirect<TData>;
+    execute({ indexMap, values, extra, }: ExecutionDetails): PromiseOrDirect<GrafastResultsList<TData>>;
+    abstract unbatchedExecute(extra: UnbatchedExecutionExtra, ...tuple: any[]): PromiseOrDirect<TData>;
 }
-export declare function isExecutableStep<TData = any>(step: unknown): step is ExecutableStep<TData>;
-export declare function assertExecutableStep<TData>(step: BaseStep): asserts step is ExecutableStep<TData>;
-export declare function isUnbatchedExecutableStep<TData = any>(step: unknown): step is UnbatchedExecutableStep<TData>;
+export declare function isStep<TData = any>(step: unknown): step is Step<TData>;
+export declare function assertStep<TData>(step: unknown): asserts step is Step<TData>;
+export declare function isUnbatchedStep<TData = any>(step: unknown): step is UnbatchedStep<TData>;
 export type ObjectLikeStep<TData extends {
-    [key: string]: ExecutableStep;
+    [key: string]: Step;
 } = {
-    [key: string]: ExecutableStep;
-}> = ExecutableStep<{
-    [key in keyof TData]: TData[key] extends ExecutableStep<infer U> ? U : never;
+    [key: string]: Step;
+}> = Step<{
+    [key in keyof TData]: TData[key] extends Step<infer U> ? U : never;
 }> & {
-    get<TKey extends keyof TData>(key: TKey): ExecutableStep<TData[TKey]>;
+    get<TKey extends keyof TData>(key: TKey): Step<TData[TKey]>;
 };
 export declare function isObjectLikeStep<TData extends {
-    [key: string]: ExecutableStep;
+    [key: string]: Step;
 } = {
-    [key: string]: ExecutableStep;
-}>(plan: ExecutableStep): plan is ObjectLikeStep<TData>;
-export type ListLikeStep<TData extends [...ExecutableStep[]] = [...ExecutableStep[]]> = ExecutableStep<{
-    [key in keyof TData]: TData[key] extends ExecutableStep<infer U> ? U : never;
+    [key: string]: Step;
+}>(plan: Step): plan is ObjectLikeStep<TData>;
+export type ListLikeStep<TData extends [...Step[]] = [...Step[]]> = Step<{
+    [key in keyof TData]: TData[key] extends Step<infer U> ? U : never;
 }> & {
-    at<TKey extends keyof TData>(key: TKey): ExecutableStep<TData[TKey]>;
-};
-export declare function isListLikeStep<TData extends [...ExecutableStep[]] = [...ExecutableStep[]]>(plan: ExecutableStep): plan is ListLikeStep<TData>;
-export type StreamableStep<TData> = ExecutableStep<ReadonlyArray<TData>> & {
-    /**
-     * If this plan supports streaming then it should implement this method. It's
-     * basically the same as `execute` except it returns a list of result streams
-     * rather than a list of results.
-     */
-    stream(count: number, values: ReadonlyArray<GrafastValuesList<any>>, extra: ExecutionExtra, streamOptions: {
-        initialCount: number;
-    }): PromiseOrDirect<GrafastResultStreamList<TData>>;
+    at<TKey extends keyof TData>(key: TKey): Step<TData[TKey]>;
 };
-export declare function isStreamableStep<TData>(plan: ExecutableStep<ReadonlyArray<TData>>): plan is StreamableStep<TData>;
-export type PolymorphicStep = ExecutableStep & {
-    planForType(objectType: GraphQLObjectType): ExecutableStep;
+export declare function isListLikeStep<TData extends [...Step[]] = [...Step[]]>(plan: Step): plan is ListLikeStep<TData>;
+export type PolymorphicStep = Step & {
+    planForType(objectType: GraphQLObjectType): Step;
 };
-export declare function isPolymorphicStep(s: ExecutableStep): s is PolymorphicStep;
-/**
- * Modifier plans modify their parent plan (which may be another ModifierStep
- * or an ExecutableStep). First they gather all the requirements from their
- * children (if any) being applied to them, then they apply themselves to their
- * parent plan. This application is done through the `apply()` method.
- *
- * Modifier plans do not use dependencies.
- */
-export declare abstract class ModifierStep<TParentStep extends BaseStep = BaseStep> extends BaseStep {
-    protected readonly $parent: TParentStep;
-    static $$export: any;
-    readonly id: string;
-    constructor($parent: TParentStep);
-    toString(): string;
-    /**
-     * In this method, you should apply the changes to your `this.$parent` plan
-     */
-    abstract apply(): void;
-}
-export declare function isModifierStep<TParentStep extends ExecutableStep | ModifierStep<any>>(plan: BaseStep): plan is ModifierStep<TParentStep>;
-export declare function assertModifierStep<TParentStep extends ExecutableStep | ModifierStep<any>>(plan: BaseStep, pathDescription: string): asserts plan is ModifierStep<TParentStep>;
-export interface ListCapableStep<TOutputData, TItemStep extends ExecutableStep<TOutputData> = ExecutableStep<TOutputData>> extends ExecutableStep<ReadonlyArray<any>> {
+export declare function isPolymorphicStep(s: Step): s is PolymorphicStep;
+export interface ListCapableStep<TOutputData, TItemStep extends Step<TOutputData> = Step<TOutputData>> extends Step<ReadonlyArray<any>> {
     listItem(itemPlan: __ItemStep<this>): TItemStep;
 }
-export declare function isListCapableStep<TData, TItemStep extends ExecutableStep<TData>>(plan: ExecutableStep<ReadonlyArray<TData>>): plan is ListCapableStep<TData, TItemStep>;
-export declare function assertListCapableStep<TData, TItemStep extends ExecutableStep<TData>>(plan: ExecutableStep<ReadonlyArray<TData>>, pathDescription: string): asserts plan is ListCapableStep<TData, TItemStep>;
-export {};
+export declare function isListCapableStep<TData, TItemStep extends Step<TData>>(plan: Step<ReadonlyArray<TData>>): plan is ListCapableStep<TData, TItemStep>;
+export declare function assertListCapableStep<TData, TItemStep extends Step<TData>>(plan: Step<ReadonlyArray<TData>>, pathDescription: string): asserts plan is ListCapableStep<TData, TItemStep>;
+export { 
+/** @deprecated Use ExecutableStep instead */
+Step as ExecutableStep, 
+/** @deprecated Use UnbatchedStep instead */
+UnbatchedStep as UnbatchedExecutableStep, };
+/** @deprecated Use isStep instead */
+export declare const isExecutableStep: typeof isStep;
+/** @deprecated Use isStep instead */
+export declare function assertExecutableStep<TData>(step: unknown): asserts step is Step<TData>;
 //# sourceMappingURL=step.d.ts.map