grafast 0.1.1-beta.21 → 0.1.1-beta.23

package/README.md

@@ -50,11 +50,7 @@ And please give some love to our featured sponsors 🤩:
 
 <table><tr>
 <td align="center"><a href="https://www.the-guild.dev/"><img src="https://graphile.org/images/sponsors/theguild.png" width="90" height="90" alt="The Guild" /><br />The Guild</a> *</td>
-<td align="center"><a href="https://dovetailapp.com/"><img src="https://graphile.org/images/sponsors/dovetail.png" width="90" height="90" alt="Dovetail" /><br />Dovetail</a> *</td>
-<td align="center"><a href="https://stellate.co/"><img src="https://graphile.org/images/sponsors/Stellate.png" width="90" height="90" alt="Stellate" /><br />Stellate</a> *</td>
 <td align="center"><a href="https://gosteelhead.com/"><img src="https://graphile.org/images/sponsors/steelhead.svg" width="90" height="90" alt="Steelhead" /><br />Steelhead</a> *</td>
-</tr><tr>
-<td align="center"><a href=""><img src="https://graphile.org/images/sponsors/latchbio.jpg" width="90" height="90" alt="LatchBio" /><br />LatchBio</a> *</td>
 </tr></table>
 
 <em>\* Sponsors the entire Graphile suite</em>

package/dist/args.js

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.hookArgs = hookArgs;
-const interfaces_js_1 = require("./interfaces.js");
+const constants_js_1 = require("./constants.js");
 const middleware_js_1 = require("./middleware.js");
 const utils_js_1 = require("./utils.js");
 const EMPTY_OBJECT = Object.freeze(Object.create(null));
@@ -35,10 +35,10 @@ function hookArgs(rawArgs, legacyResolvedPreset, legacyCtx) {
     }
     const args = rawArgs;
     // Assert that args haven't already been hooked
-    if (args[interfaces_js_1.$$hooked]) {
+    if (args[constants_js_1.$$hooked]) {
         throw new Error("Must not call hookArgs twice!");
     }
-    args[interfaces_js_1.$$hooked] = true;
+    args[constants_js_1.$$hooked] = true;
     if (middleware != null) {
         return middleware.run("prepareArgs", { args }, finalizeWithEvent);
     }

package/dist/constants.d.ts

@@ -0,0 +1,79 @@
+export declare const $$hooked: unique symbol;
+export declare const $$grafastContext: unique symbol;
+export declare const $$planResults: unique symbol;
+export declare const $$id: unique symbol;
+/** Return the value verbatim, don't execute */
+export declare const $$verbatim: unique symbol;
+/**
+ * If we're sure the data is the right shape and valid, we can set this key and
+ * it can be returned directly
+ */
+export declare const $$bypassGraphQL: unique symbol;
+export declare const $$data: unique symbol;
+/**
+ * For attaching additional metadata to the GraphQL execution result, for
+ * example details of the plan or SQL queries or similar that were executed.
+ */
+export declare const $$extensions: unique symbol;
+/**
+ * Set this key on a type if that type's serialization is idempotent (that is
+ * to say `serialize(serialize(thing)) === serialize(thing)`). This means we
+ * don't have to "roll-back" serialization if we need to fallback to graphql-js
+ * execution.
+ */
+export declare const $$idempotent: unique symbol;
+/**
+ * The event emitter used for outputting execution events.
+ */
+export declare const $$eventEmitter: unique symbol;
+/**
+ * Used to indicate that an array has more results available via a stream.
+ */
+export declare const $$streamMore: unique symbol;
+export declare const $$proxy: unique symbol;
+/**
+ * If an error has this property set then it's safe to send through to the user
+ * without being masked.
+ */
+export declare const $$safeError: unique symbol;
+/** The layerPlan used as a subroutine for this step */
+export declare const $$subroutine: unique symbol;
+/** For tracking the timeout a TimeoutError happened from */
+export declare const $$timeout: unique symbol;
+/** For tracking _when_ the timeout happened (because once the JIT has warmed it might not need so long) */
+export declare const $$ts: unique symbol;
+export declare const $$queryCache: unique symbol;
+/**
+ * We store the cache directly onto the GraphQLSchema so that it gets garbage
+ * collected along with the schema when it's not needed any more. To do so, we
+ * attach it using this symbol.
+ */
+export declare const $$cacheByOperation: unique symbol;
+export declare const $$contextPlanCache: unique symbol;
+/**
+ * A bitwise number representing a number of flags:
+ *
+ * - 0: normal execution value
+ * - 1: errored (trappable)
+ * - 2: null (trappable)
+ * - 4: inhibited (trappable)
+ * - 8: disabled due to polymorphism (untrappable)
+ * - 16: stopped (untrappable) - e.g. due to fatal (unrecoverable) error
+ * - 32: ...
+ */
+export type ExecutionEntryFlags = number & {
+    readonly tsBrand?: unique symbol;
+};
+export declare const NO_FLAGS: ExecutionEntryFlags;
+export declare const FLAG_ERROR: ExecutionEntryFlags;
+export declare const FLAG_NULL: ExecutionEntryFlags;
+export declare const FLAG_INHIBITED: ExecutionEntryFlags;
+export declare const FLAG_POLY_SKIPPED: ExecutionEntryFlags;
+export declare const FLAG_STOPPED: ExecutionEntryFlags;
+export declare const ALL_FLAGS: ExecutionEntryFlags;
+/** By default, accept null values as an input */
+export declare const DEFAULT_ACCEPT_FLAGS: ExecutionEntryFlags;
+export declare const TRAPPABLE_FLAGS: ExecutionEntryFlags;
+export declare const DEFAULT_FORBIDDEN_FLAGS: ExecutionEntryFlags;
+export declare const FORBIDDEN_BY_NULLABLE_BOUNDARY_FLAGS: ExecutionEntryFlags;
+//# sourceMappingURL=constants.d.ts.map

package/dist/constants.js

@@ -0,0 +1,79 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FORBIDDEN_BY_NULLABLE_BOUNDARY_FLAGS = exports.DEFAULT_FORBIDDEN_FLAGS = exports.TRAPPABLE_FLAGS = exports.DEFAULT_ACCEPT_FLAGS = exports.ALL_FLAGS = exports.FLAG_STOPPED = exports.FLAG_POLY_SKIPPED = exports.FLAG_INHIBITED = exports.FLAG_NULL = exports.FLAG_ERROR = exports.NO_FLAGS = exports.$$contextPlanCache = exports.$$cacheByOperation = exports.$$queryCache = exports.$$deepDepSkip = exports.$$ts = exports.$$timeout = exports.$$subroutine = exports.$$safeError = exports.$$proxy = exports.$$streamMore = exports.$$eventEmitter = exports.$$idempotent = exports.$$extensions = exports.$$data = exports.$$bypassGraphQL = exports.$$verbatim = exports.$$id = exports.$$planResults = exports.$$grafastContext = exports.$$hooked = void 0;
+exports.$$hooked = Symbol("hookArgsApplied");
+exports.$$grafastContext = Symbol("context");
+exports.$$planResults = Symbol("planResults");
+exports.$$id = Symbol("id");
+/** Return the value verbatim, don't execute */
+exports.$$verbatim = Symbol("verbatim");
+/**
+ * If we're sure the data is the right shape and valid, we can set this key and
+ * it can be returned directly
+ */
+exports.$$bypassGraphQL = Symbol("bypassGraphQL");
+exports.$$data = Symbol("data");
+/**
+ * For attaching additional metadata to the GraphQL execution result, for
+ * example details of the plan or SQL queries or similar that were executed.
+ */
+exports.$$extensions = Symbol("extensions");
+/**
+ * Set this key on a type if that type's serialization is idempotent (that is
+ * to say `serialize(serialize(thing)) === serialize(thing)`). This means we
+ * don't have to "roll-back" serialization if we need to fallback to graphql-js
+ * execution.
+ */
+exports.$$idempotent = Symbol("idempotent");
+/**
+ * The event emitter used for outputting execution events.
+ */
+exports.$$eventEmitter = Symbol("executionEventEmitter");
+/**
+ * Used to indicate that an array has more results available via a stream.
+ */
+exports.$$streamMore = Symbol("streamMore");
+exports.$$proxy = Symbol("proxy");
+/**
+ * If an error has this property set then it's safe to send through to the user
+ * without being masked.
+ */
+exports.$$safeError = Symbol("safeError");
+/** The layerPlan used as a subroutine for this step */
+exports.$$subroutine = Symbol("subroutine");
+/** For tracking the timeout a TimeoutError happened from */
+exports.$$timeout = Symbol("timeout");
+/** For tracking _when_ the timeout happened (because once the JIT has warmed it might not need so long) */
+exports.$$ts = Symbol("timestamp");
+/**
+ * @internal
+ */
+exports.$$deepDepSkip = Symbol("deepDepSkip_experimental");
+exports.$$queryCache = Symbol("queryCache");
+/**
+ * We store the cache directly onto the GraphQLSchema so that it gets garbage
+ * collected along with the schema when it's not needed any more. To do so, we
+ * attach it using this symbol.
+ */
+exports.$$cacheByOperation = Symbol("cacheByOperation");
+exports.$$contextPlanCache = Symbol("contextPlanCache");
+function flag(f) {
+    return f;
+}
+exports.NO_FLAGS = flag(0); // 0
+exports.FLAG_ERROR = flag(1 << 0); // 1
+exports.FLAG_NULL = flag(1 << 1); // 2
+exports.FLAG_INHIBITED = flag(1 << 2); // 4
+exports.FLAG_POLY_SKIPPED = flag(1 << 3); // 8
+exports.FLAG_STOPPED = flag(1 << 4); // 16
+exports.ALL_FLAGS = flag(exports.FLAG_ERROR | exports.FLAG_NULL | exports.FLAG_INHIBITED | exports.FLAG_POLY_SKIPPED | exports.FLAG_STOPPED);
+/** By default, accept null values as an input */
+exports.DEFAULT_ACCEPT_FLAGS = flag(exports.FLAG_NULL);
+exports.TRAPPABLE_FLAGS = flag(exports.FLAG_ERROR | exports.FLAG_NULL | exports.FLAG_INHIBITED);
+exports.DEFAULT_FORBIDDEN_FLAGS = flag(exports.ALL_FLAGS & ~exports.DEFAULT_ACCEPT_FLAGS);
+exports.FORBIDDEN_BY_NULLABLE_BOUNDARY_FLAGS = flag(exports.FLAG_NULL | exports.FLAG_POLY_SKIPPED);
+// TODO: make `FORBIDDEN_BY_NULLABLE_BOUNDARY_FLAGS = flag(FLAG_ERROR | FLAG_NULL | FLAG_POLY_SKIPPED | FLAG_INHIBITED | FLAG_STOPPED);`
+// Currently this isn't enabled because the bucket has to exist for the output
+// plan to throw the error; really the root should be evaluated before
+// descending into the output plan rather than as part of descending?
+//# sourceMappingURL=constants.js.map

package/dist/engine/LayerPlan.d.ts

@@ -1,5 +1,6 @@
 import type { Bucket } from "../bucket.js";
 import type { Step } from "../step";
+import type { __ValueStep } from "../steps/index.js";
 import type { OperationPlan } from "./OperationPlan";
 /** Non-branching, non-deferred */
 export interface LayerPlanReasonRoot {
@@ -8,6 +9,7 @@ export interface LayerPlanReasonRoot {
 /** Non-branching, non-deferred */
 export interface LayerPlanReasonNullableField {
     type: "nullableBoundary";
+    parentLayerPlan: LayerPlan;
     /**
      * Can be used such that the same LayerPlan can be used for two selection
      * sets for the same parent plan. In this case an additional output plan
@@ -25,6 +27,7 @@ export interface LayerPlanReasonListItemStream {
 /** Non-branching, non-deferred */
 export interface LayerPlanReasonListItem {
     type: "listItem";
+    parentLayerPlan: LayerPlan;
     /**
      * Can be used such that the same LayerPlan can be used for two lists for
      * the same parent plan. In this case an additional output plan would be
@@ -41,36 +44,82 @@ export interface LayerPlanReasonListItem {
 /** Non-branching, deferred */
 export interface LayerPlanReasonSubscription {
     type: "subscription";
+    parentLayerPlan: LayerPlan;
 }
 /** Non-branching, deferred */
 export interface LayerPlanReasonMutationField {
     type: "mutationField";
+    parentLayerPlan: LayerPlan;
     mutationIndex: number;
 }
 /** Non-branching, deferred */
 export interface LayerPlanReasonDefer {
     type: "defer";
+    parentLayerPlan: LayerPlan;
     label?: string;
 }
-/** Branching, non-deferred */
+/**
+ * Non-branching, non-deferred
+ *
+ * A polymorphic bucket indicates a transition between values of unknown type
+ * and values of a known polymorphic type. This is predicated based on the
+ * given typename - before the typename is known, we must run all steps for all
+ * types, but once the type is known we can be more selective about which steps
+ * to run.
+ *
+ * When a polymorphic type is met, there will always be a polymorphic layer
+ * plan, even if all steps within it run for all types. This is necessary to
+ * advance the `polymorphicPathList` index for the relevant indicies.
+ */
 export interface LayerPlanReasonPolymorphic {
     type: "polymorphic";
+    parentLayerPlan: LayerPlan;
     typeNames: string[];
     /**
-     * Needed for execution (see `executeBucket`).
+     * Stores the __typename, needed for execution (see `executeBucket`).
      */
-    parentStep: Step;
+    parentStep: Step<string | null>;
     polymorphicPaths: Set<string>;
 }
+/**
+ * Branching, non-deferred
+ *
+ * A polymorphicPartition bucket accepts a subset of types and contains only
+ * steps relevant to those types; it's a way to avoid having to do a lot of
+ * filtering of values being passed into steps' execute methods by
+ * pre-filtering the values.
+ */
+export interface LayerPlanReasonPolymorphicPartition {
+    type: "polymorphicPartition";
+    parentLayerPlan: LayerPlan<LayerPlanReasonPolymorphic>;
+    typeNames: string[];
+    polymorphicPaths: ReadonlySet<string>;
+}
 /** Non-branching, non-deferred */
 export interface LayerPlanReasonSubroutine {
     type: "subroutine";
+    parentLayerPlan: LayerPlan;
     parentStep: Step;
 }
-export declare function isBranchingLayerPlan(layerPlan: LayerPlan): boolean;
+/**
+ * Anti-branching, non-deferred
+ *
+ * A "combined" layer plan exists to re-combine values from multiple layer
+ * plans together again, to allow future steps to be more efficient. It's
+ * typically relevant when polymorphism has occurred and has caused branching,
+ * the combined layer plan allows the values to be recombined before branching
+ * again, such that L layers of polymorphism, where there are P different
+ * polymorphic branches at each layer, results in P*L branches rather than P^L
+ * branches - i.e. it scales linary with number of layers rather than
+ * exponentially.
+ */
+export interface LayerPlanReasonCombined {
+    type: "combined";
+    parentLayerPlans: ReadonlyArray<LayerPlan>;
+}
+export declare function hasParentLayerPlan(reason: LayerPlanReason): reason is Exclude<LayerPlanReason, LayerPlanReasonRoot | LayerPlanReasonCombined>;
 export declare function isDeferredLayerPlan(layerPlan: LayerPlan): boolean;
-export declare function isPolymorphicLayerPlan(layerPlan: LayerPlan): boolean;
-export type LayerPlanReason = LayerPlanReasonRoot | LayerPlanReasonNullableField | LayerPlanReasonListItem | LayerPlanReasonSubscription | LayerPlanReasonMutationField | LayerPlanReasonDefer | LayerPlanReasonPolymorphic | LayerPlanReasonSubroutine;
+export type LayerPlanReason = LayerPlanReasonRoot | LayerPlanReasonNullableField | LayerPlanReasonListItem | LayerPlanReasonSubscription | LayerPlanReasonMutationField | LayerPlanReasonDefer | LayerPlanReasonPolymorphic | LayerPlanReasonPolymorphicPartition | LayerPlanReasonCombined | LayerPlanReasonSubroutine;
 export type HasParent<A extends LayerPlanReason> = A extends any ? A extends {
     parentStep: Step;
 } ? A : never : never;
@@ -102,7 +151,6 @@ export type LayerPlanReasonsWithParentStep = HasParent<LayerPlanReason>;
  */
 export declare class LayerPlan<TReason extends LayerPlanReason = LayerPlanReason> {
     readonly operationPlan: OperationPlan;
-    parentLayerPlan: LayerPlan | null;
     readonly reason: TReason;
     id: number;
     /** How "deep" this layer plan is (how many ancestors it has). The root layer plan has a depth of 0. */
@@ -114,12 +162,27 @@ export declare class LayerPlan<TReason extends LayerPlanReason = LayerPlanReason
      * layer plan, grouped by their step class.
      */
     stepsByConstructor: Map<Function, Set<Step>>;
-    constructor(operationPlan: OperationPlan, parentLayerPlan: LayerPlan | null, reason: TReason);
+    /**
+     * Populated during `finalize`, this will be empty except for phase
+     * transition layer plans (defer/stream) wherein it will contain a list of
+     * "unreachable" layer plan IDs relevant to the "combined" layer plans trying
+     * to refer to parent layer plans which are outside of this incremental
+     * boundary (e.g. if two lists both stream, we might combine those, but at
+     * runtime only one will be populated so we can't wait for the other to
+     * complete otherwise nothing will happen).
+     */
+    outOfBoundsLayerPlanIds: Set<number>;
+    constructor(operationPlan: OperationPlan, reason: TReason);
     toString(): string;
     print(depth?: number): string;
     _hasSetRootStep: boolean;
     setRootStep($root: Step): void;
     finalize(): void;
     newBucket(parentBucket: Bucket): Bucket | null;
+    newCombinedBucket(finalParentBucket: Pick<Bucket, "sharedState">): Bucket | null;
+    addCombo(sources: ReadonlyArray<{
+        layerPlan: LayerPlan;
+        step: Step;
+    }>, $target: __ValueStep<any>): void;
 }
 //# sourceMappingURL=LayerPlan.d.ts.map