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

package/LICENSE.md

@@ -1,26 +1,24 @@
-# Graphile Sponsors-only Software
+# The MIT License (MIT)
 
-Copyright © 2022 Benjie Gillam. All rights reserved.
+Copyright © `2023` Benjie Gillam
 
-This package is _not_ (yet) open source software, it may only be used by
-graphile sponsors. for more information, please see https://grafast.org
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the “Software”), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
 
-This is explicitly pre-release software, it has not yet gone through rigorous
-testing and probably includes security and stability issues both known and
-unknown. Usage of this software is entirely at your own risk.
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
 
 THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 
 ---
 
-The contents of the `node_modules` directory are produced from external
-libraries; their license terms will likely differ from the terms above - you
-should review them also.
-
 Licenses of bundled dependencies (if any) are detailed in dist/LICENSES.txt

package/README.md

@@ -1,3 +1,140 @@
 # Gra*fast*
 
-Coming 2023! [Be notified](https://grafast.org)
+[![GitHub Sponsors](https://img.shields.io/github/sponsors/benjie?color=ff69b4&label=github%20sponsors)](https://github.com/sponsors/benjie)
+[![Patreon sponsor button](https://img.shields.io/badge/sponsor-via%20Patreon-orange.svg)](https://patreon.com/benjie)
+[![Discord chat room](https://img.shields.io/discord/489127045289476126.svg)](http://discord.gg/graphile)
+[![Follow](https://img.shields.io/badge/twitter-@GrafastHQ-blueviolet.svg)](https://twitter.com/GrafastHQ)
+
+_**The next-generation planning and execution engine for GraphQL**_
+
+**Documentation**: https://grafast.org/grafast/
+
+## About
+
+Gra*fast* understands GraphQL and (with your help) your business logic; this
+allows it to orchestrate a GraphQL request's data requirements in an extremely
+efficient manner, leading to excellent performance, reduced server load, and
+happier customers.
+
+This increased efficiency is achieved by leveraging the declarative nature of
+GraphQL and deeper integration with your existing Node.js or remote business
+logic via "plan resolvers" attached to the fields of your schema. These plan
+resolvers detail the abstract steps necessary to execute the given field, these
+steps are then combined with the steps from all other fields in the request into
+an operation plan. This operation plan can then be rewritten and optimized
+before execution, and can often be re-used for similar queries in the future.
+
+In addition to "plan resolvers," Gra*fast* is also backwards compatible with
+traditional resolvers - in fact most existing GraphQL.js schemas should already
+be executable via Gra*fast* (and doing so should result in a small speed
+improvement). Replace your resolvers with Gra*fast* plan resolvers to see the
+real efficiency gains!
+
+Gra*fast* schemas can be built using the same techniques other GraphQL.js
+schemas can be built - Gra*fast* schemas _are_ GraphQL.js schemas - for example
+schema-first, code-first or auto-generated. If you maintain a library that
+builds GraphQL schemas, get in touch - we'd love to help you integrate Gra*fast*
+with it!
+
+<!-- SPONSORS_BEGIN -->
+
+## Crowd-funded open-source software
+
+To help us develop this software sustainably under the MIT license, we ask all
+individuals and businesses that use it to help support its ongoing maintenance
+and development via sponsorship.
+
+### [Click here to find out more about sponsors and sponsorship.](https://www.graphile.org/sponsor/)
+
+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://qwick.com/"><img src="https://graphile.org/images/sponsors/qwick.png" width="90" height="90" alt="Qwick" /><br />Qwick</a> *</td>
+<td align="center"><a href="https://www.netflix.com/"><img src="https://graphile.org/images/sponsors/Netflix.png" width="90" height="90" alt="Netflix" /><br />Netflix</a> *</td>
+</tr><tr>
+<td align="center"><a href=""><img src="https://graphile.org/images/sponsors/chadf.png" width="90" height="90" alt="Chad Furman" /><br />Chad Furman</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://www.accenture.com/"><img src="https://graphile.org/images/sponsors/accenture.svg" width="90" height="90" alt="Accenture" /><br />Accenture</a> *</td>
+</tr></table>
+
+<em>\* Sponsors the entire Graphile suite</em>
+
+<!-- SPONSORS_END -->
+
+## Overview
+
+Gra*fast* is an alternative GraphQL execution engine for JavaScript; you can use
+it as a drop-in replacement for the "execute" method of GraphQL.js. Any GraphQL
+server that allows replacement of the `execute` method (which includes any
+server that fully supports [envelop][]) can support Gra*fast*.
+
+When Gra*fast* sees a GraphQL request for the first time it will "plan" the
+request: figuring out the data requirements, the steps that need to be taken,
+and how to write the results to the response. This "first draft" plan will be
+optimised and rewritten to give the best achievable performance (for example
+removing redundant or duplicate processing steps, rewriting and merging
+processing steps, etc). Finally, the plan will be executed, and the response
+returned to the client. Future requests that are compatible with this plan can
+be executed immediately without a need to re-plan.
+
+## Requirements
+
+Gra*fast* should work with any GraphQL.js schema that matches the following
+requirements:
+
+- GraphQL.js v16+
+- you must not override the default GraphQL field resolver (TODO: support this)
+- for every request:
+  - `context` must be an object (anything suitable to be used as the key to a
+    `WeakMap`); if you do not need a context then `{}` is perfectly acceptable
+  - `rootValue` must be an object or `null`/`undefined`
+- resolver limitations:
+  - only explicit field resolvers (baked into the GraphQL schema) are supported,
+    i.e. resolvers passed via `rootValue` are not (currently) supported
+  - our support for traditional GraphQL resolvers does not have full parity with
+    the fourth argument to `resolve` (aka `resolveInfo`) - in particular, the
+    `resolveInfo.path` property is not currently supported.
+
+If you find a GraphQL schema that matches these requirements and doesn't work
+with Gra*fast*, please file an issue.
+
+## Advice
+
+To reap the most benefit from using Gra*fast*, you want as little to change
+between executions as possible. In particular, this means you should:
+
+- **CRITICAL**: Cache (e.g. with a LRU cache) the parsed GraphQL document, so
+  the same AST can be reused over and over for the same document
+  - `grafserv` handles this for you
+  - Envelop users can use `@envelop/parser-cache` for this
+- Don't use `rootValue` (Do you really need it? Use `context` instead.)
+- Where possible, memoize the variables object (e.g. using a cache over
+  `canonicalJSONStringify(variables)`) so the same variables results in the same
+  object in memory
+- Cache (e.g. with a LRU cache) the GraphQL `context` object, so the same
+  context can be reused over and over for the same user
+  - This is less important - feel free to break it if you need to, for example
+    if you're still using DataLoaders during migration
+
+## Usage
+
+Where you would use `graphql` from the `graphql` module, use `grafast` instead:
+
+```diff
+-import { graphql } from "graphql";
++import { grafast as graphql } from "grafast";
+```
+
+Where you would use `execute` from the `graphql` module, use `grafast`'s
+`execute` instead:
+
+```diff
+-import { execute } from "graphql";
++import { execute } from "grafast";
+```
+
+## Full documentation
+
+https://grafast.org/grafast/

package/dist/LICENSES.txt

@@ -254,7 +254,7 @@ CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 
 
 --------------------------------------------------------------------------------
-tamedevil v0.0.0-alpha.3 - Benjie Gillam <benjie@jemjie.com>
+tamedevil v0.0.0-beta.1 - Benjie Gillam <benjie@jemjie.com>
 git+https://github.com/graphile/heart.git
 --------------------------------------------------------------------------------
 

package/dist/args.d.ts

@@ -1,3 +1,9 @@
 import type { ExecutionArgs } from "graphql";
-export declare function hookArgs(args: ExecutionArgs, resolvedPreset: GraphileConfig.ResolvedPreset, ctx: Partial<Grafast.RequestContext>): ExecutionArgs | PromiseLike<ExecutionArgs>;
+/**
+ * Applies Graphile Config hooks to your GraphQL request, e.g. to
+ * populate context or similar.
+ *
+ * @experimental
+ */
+export declare function hookArgs(rawArgs: ExecutionArgs, resolvedPreset: GraphileConfig.ResolvedPreset, ctx: Partial<Grafast.RequestContext>): Grafast.ExecutionArgs | PromiseLike<Grafast.ExecutionArgs>;
 //# sourceMappingURL=args.d.ts.map

package/dist/assert.d.ts

@@ -1,3 +1,5 @@
+/** Equivalent to `assert.ok(...)` */
 export declare function ok(val: any, message: string): asserts val;
+/** Equivalent to `assert.strictEqual(...)` */
 export declare function strictEqual<T>(actual: any, expected: T, message: string): asserts actual is T;
 //# sourceMappingURL=assert.d.ts.map

package/dist/bucket.d.ts

@@ -1,20 +1,85 @@
 import type { LayerPlan } from "./engine/LayerPlan";
 import type { MetaByMetaKey } from "./engine/OperationPlan";
 import type { ExecutionEventEmitter } from "./interfaces.js";
+/**
+ * @internal
+ */
 export interface RequestTools {
+    /** The `timeSource.now()` at which the request started executing */
     startTime: number;
+    /** The `timeSource.now()` at which the request should stop executing (if a timeout was configured) */
     stopTime: number | null;
     readonly eventEmitter: ExecutionEventEmitter | undefined;
-    metaByMetaKey: MetaByMetaKey;
+    /**
+     * If we're running inside GraphQL then we should not serialize scalars,
+     * otherwise we'll face the double-serialization problem.
+     */
     insideGraphQL: false;
 }
+/**
+ * A "bucket" is where the results from plans are stored so that other plans
+ * can retrieve them, it may take on different forms depending on the mode of
+ * execution. A "LayerPlan" is used to both identify the bucket and to specify
+ * why it exists and how it behaves.
+ *
+ * Every `ExecutableStep` belongs to exactly one LayerPlan (and thus bucket),
+ * specified by `plan.layerPlan`.
+ *
+ * @internal
+ */
 export interface Bucket {
+    /**
+     * The LayerPlan definition this bucket adheres to
+     */
     layerPlan: LayerPlan;
+    /**
+     * How many entries are there in the bucket?
+     */
     size: number;
+    /**
+     * The polymorphic path through which each of the entries (respectively) has
+     * travelled. This influences the steps that will be executed using the
+     * related inputs.
+     */
     polymorphicPathList: readonly (string | null)[];
+    /**
+     * These are the iterators the bucket (or its descendents, without crossing a
+     * stream/defer boundary) have created (if any). Each of these must either be
+     * processed via `processRoot`, or must be manually released (via
+     * `releaseUnusedIterators`) otherwise a memory leak could occur.
+     */
+    iterators: Array<Set<AsyncIterator<any> | Iterator<any>>>;
+    /**
+     * `metaByMetaKey` belongs to the bucket rather than the request context
+     * because mutations and subscriptions shouldn't re-use caches.
+     *
+     * TODO: `inheritMeta: boolean`?
+     */
+    metaByMetaKey: MetaByMetaKey;
+    /**
+     * Every entry in the store is a list with the same length as the bucket has
+     * `size`.
+     *
+     * The entry for '-1' is the request indexes, so we can associate the results
+     * back to the request that triggered them.
+     */
     store: Map<number, any[]>;
+    /**
+     * Set this true when the bucket is fully executed.
+     *
+     * Initialize it to false.
+     */
     isComplete: boolean;
+    /**
+     * If an error occurred at any stage we need to drop down to more careful
+     * (and slower) handling.
+     *
+     * Initialize it to false.
+     */
     hasErrors: boolean;
+    /**
+     * The child buckets of this bucket.
+     */
     children: {
         [layerPlanId: number]: {
             bucket: Bucket;

package/dist/constraints.d.ts

@@ -1,30 +1,61 @@
+/**
+ * Asserts that a value strictly matches.
+ */
 interface ValueConstraint {
     type: "value";
     path: (string | number)[];
     value: unknown;
 }
+/**
+ * Asserts that `(value === expectedValue)` is always equal to `pass`.
+ */
 interface EqualityConstraint {
     type: "equal";
     path: (string | number)[];
     expectedValue: unknown;
     pass: boolean;
 }
+/**
+ * Asserts that the property at the given path exists.
+ *
+ * Let `tail` be the last entry in `path`, and `rest` be the rest of `path`.
+ * The value at path `rest` must be an object, and that object must have an
+ * attribute `tail` which is not `undefined`.
+ */
 interface ExistsConstraint {
     type: "exists";
     path: (string | number)[];
     exists: boolean;
 }
+/**
+ * If `expectedLength` is null: asserts that there is no value at the given
+ * path.
+ *
+ * Otherwise: asserts that the value at the given path is an array containing
+ * `expectedLength` entries.
+ */
 interface LengthConstraint {
     type: "length";
     path: (string | number)[];
+    /**
+     * If this is null it implies that the array did not exist.
+     */
     expectedLength: number | null;
 }
+/**
+ * Checks if the object at the given path matches the `isEmpty` property
+ * (implying no keys). Objects are empty if and only if they exist and have no
+ * keys.
+ */
 interface IsEmptyConstraint {
     type: "isEmpty";
     path: (string | number)[];
     isEmpty: boolean;
 }
 export type Constraint = ValueConstraint | EqualityConstraint | ExistsConstraint | LengthConstraint | IsEmptyConstraint;
+/**
+ * Implements the `MatchesConstraints` algorithm.
+ */
 export declare function matchesConstraints(constraints: Constraint[], object: unknown): boolean;
 export {};
 //# sourceMappingURL=constraints.d.ts.map

package/dist/deferred.d.ts

@@ -1,6 +1,13 @@
+/**
+ * A promise that can be `.resolve()`-ed or `.reject()`-ed at a later time.
+ */
 export interface Deferred<T> extends PromiseLike<T> {
     resolve: (input: T | PromiseLike<T>) => void;
     reject: (error: Error) => void;
 }
+/**
+ * Returns a promise that can be `.resolve()`-ed or `.reject()`-ed at a later
+ * time.
+ */
 export declare function defer<T = void>(): Deferred<T>;
 //# sourceMappingURL=deferred.d.ts.map

package/dist/dev.d.ts

@@ -1,3 +1,6 @@
+/**
+ * @internal
+ */
 export declare const isDev: boolean;
 export declare function noop(): void;
 //# sourceMappingURL=dev.d.ts.map

package/dist/engine/LayerPlan.d.ts

@@ -1,38 +1,64 @@
 import type { Bucket } from "../bucket.js";
 import type { ExecutableStep, ModifierStep, UnbatchedExecutableStep } from "../step";
 import type { OperationPlan } from "./OperationPlan";
+/** Non-branching, non-deferred */
 export interface LayerPlanReasonRoot {
     type: "root";
 }
+/** Non-branching, non-deferred */
 export interface LayerPlanReasonNullableField {
     type: "nullableBoundary";
+    /**
+     * 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
+     * would be added to the LayerPlan.
+     *
+     * Also needed for execution (see `executeBucket`).
+     */
     parentStep: ExecutableStep;
 }
+/** Non-branching, non-deferred */
 export interface LayerPlanReasonListItem {
     type: "listItem";
+    /**
+     * 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
+     * added to the LayerPlan.
+     *
+     * Also needed for execution (see `executeBucket`).
+     */
     parentStep: ExecutableStep;
+    /** If this listItem is to be streamed, the configuration for that streaming */
     stream?: {
         initialCount: number;
         label?: string;
     };
 }
+/** Non-branching, deferred */
 export interface LayerPlanReasonSubscription {
     type: "subscription";
 }
+/** Non-branching, deferred */
 export interface LayerPlanReasonMutationField {
     type: "mutationField";
     mutationIndex: number;
 }
+/** Non-branching, deferred */
 export interface LayerPlanReasonDefer {
     type: "defer";
     label?: string;
 }
+/** Branching, non-deferred */
 export interface LayerPlanReasonPolymorphic {
     type: "polymorphic";
     typeNames: string[];
+    /**
+     * Needed for execution (see `executeBucket`).
+     */
     parentStep: ExecutableStep;
     polymorphicPaths: Set<string>;
 }
+/** Non-branching, non-deferred */
 export interface LayerPlanReasonSubroutine {
     type: "subroutine";
     parentStep: ExecutableStep;
@@ -45,38 +71,143 @@ export type HasParent<A extends LayerPlanReason> = A extends any ? A extends {
     parentStep: ExecutableStep;
 } ? A : never : never;
 export type LayerPlanReasonsWithParentStep = HasParent<LayerPlanReason>;
+/** @internal */
 export interface LayerPlanPhase {
+    /**
+     * If true, we should check before the layer plan executes to see if the
+     * execution has already timed out.
+     *
+     * @see {@link RequestTools.stopTime}
+     */
     checkTimeout: boolean;
+    /**
+     * A list of steps that can be ran in parallel at this point, since all
+     * their previous dependencies have already been satisfied.
+     */
     normalSteps: Array<{
         step: ExecutableStep;
     }> | undefined;
+    /**
+     * A list of 'isSyncAndSafe' steps with unbatchedExecute methods that can be
+     * ran once the `normalSteps` have completed; they must only depend on steps
+     * that have already been executed before them (including previous
+     * unbatchedSyncAndSafeSteps in the same list).
+     */
     unbatchedSyncAndSafeSteps: Array<{
         step: UnbatchedExecutableStep;
+        /**
+         * Store the result of the step here if you want - useful to avoid lookups
+         * and when there's no storage. HIGHLY VOLATILE, will not survive a tick!
+         */
         scratchpad: any;
     }> | undefined;
+    /**
+     * Optimization - a digest of all steps in normalSteps and unbatchedSyncAndSafeSteps
+     *
+     * @internal
+     */
     _allSteps: ExecutableStep[];
 }
+/**
+ * A LayerPlan represents (via "reason") either the root (root), when something
+ * happens at a later time (mutationField, defer), when plurality changes
+ * (list, stream, subscription, polymorphic), or when a subprocess needs to be
+ * computed (subroutine).
+ *
+ * Layer plans belong to an operation plan.
+ *
+ * Every layer plan (except for the root layer plan) has exactly one parent
+ * layer plan.
+ *
+ * Every layer plan is caused by a parent step.
+ *
+ * The LayerPlan of a step influences:
+ *
+ * 1. how steps are deduplicated
+ * 2. the order in which the steps are executed
+ * 3. where the result of executing the step is stored
+ * 4. when the step 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.
+ *
+ */
 export declare class LayerPlan<TReason extends LayerPlanReason = LayerPlanReason> {
     readonly operationPlan: OperationPlan;
     parentLayerPlan: LayerPlan | null;
     readonly reason: TReason;
     id: number;
+    /**
+     * Every layer plan has a "root step" that shapes the value the layer
+     * returns. Note that this step may be dependent on other steps included in
+     * the LayerPlan, or could be provided externally.
+     *
+     * The root step is different for different layer step reasons:
+     *
+     * - root: the `operationPlan.rootValue`
+     * - listItem: the `__ItemStep`
+     * - stream: also the `__ItemStep`
+     * - subscription: also the `__ItemStep`
+     * - mutationField: the result plan of the mutation field
+     * - defer: the parent layer's rootStep (defer always results in an object, unless an error occurs)
+     * - polymorphic: the plan for the particular type
+     * - subroutine: the result (returned) plan of the subroutine
+     *
+     * @internal
+     */
     readonly rootStep: ExecutableStep | null;
+    /**
+     * Which plans the results for which are available in a parent bucket need to
+     * be "copied across" to this bucket because plans in this bucket still
+     * reference them?
+     *
+     * @internal
+     */
     copyStepIds: number[];
+    /** @internal */
     children: LayerPlan[];
+    /** @internal */
     steps: ExecutableStep[];
+    /** @internal */
     pendingSteps: ExecutableStep[];
+    /**
+     * Describes the order in which the steps within this LayerPlan are executed.
+     *
+     * Special attention must be paid to steps that have side effects.
+     *
+     * @internal
+     */
     phases: Array<LayerPlanPhase>;
+    /**
+     * The list of layerPlans that steps added to this LayerPlan may depend upon.
+     * Note this includes self, so it has one more entry than `depth`.
+     *
+     * ```
+     * this.ancestry[this.depth] === this;
+     * ```
+     *
+     * @internal
+     */
     ancestry: LayerPlan[];
+    /** How "deep" this layer plan is (how many ancestors it has). The root layer plan has a depth of 0. */
     depth: number;
+    /** The depth at which a "defer boundary" occurs (OperationPlan.getPeers cannot pass a defer boundary), or 0. */
     deferBoundaryDepth: number;
+    /**
+     * An optimization for OperationPlan.getPeers; this tracks the steps in this
+     * layer plan, grouped by their step class.
+     */
     stepsByConstructor: Map<Function, Set<ExecutableStep>>;
     constructor(operationPlan: OperationPlan, parentLayerPlan: LayerPlan | null, reason: TReason);
     toString(): string;
     print(depth?: number): string;
     setRootStep($root: ExecutableStep): void;
+    /** @internal Use plan.getStep(id) instead. */
     getStep(id: number, requestingStep: ExecutableStep): ExecutableStep;
+    /** @internal */
     _addStep(step: ExecutableStep): number;
+    /** @internal */
     _addModifierStep(step: ModifierStep<any>): string;
     finalize(): void;
     newBucket(parentBucket: Bucket): Bucket | null;