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

package/dist/utils.d.ts

@@ -4,30 +4,65 @@ import type { Deferred } from "./deferred.js";
 import type { OperationPlan } from "./engine/OperationPlan.js";
 import type { BaseGraphQLArguments, GrafastFieldConfig, GrafastInputFieldConfig, InputStep, OutputPlanForType } from "./interfaces.js";
 import type { ExecutableStep, ModifierStep } from "./step.js";
+/**
+ * The parent object is used as the key in `GetValueStepId()`; for root level
+ * fields it's possible that the parent will be null/undefined (in all other
+ * cases it will be an object), so we need a value that can be the key in a
+ * WeakMap to represent the root.
+ */
 export declare const ROOT_VALUE_OBJECT: any;
 export declare function assertNullPrototype(object: Record<string, unknown>, description: string): void;
+/**
+ * Specifically allows for the `defaultValue` to be undefined, but otherwise
+ * defers to {@link rawValueToValueNode}
+ */
 export declare function defaultValueToValueNode(type: GraphQLInputType, defaultValue: unknown): ConstValueNode | undefined;
 export declare function isPromise<T>(t: T | Promise<T>): t is Promise<T>;
+/**
+ * Is "thenable".
+ */
 export declare function isPromiseLike<T>(t: T | Promise<T> | PromiseLike<T>): t is PromiseLike<T>;
+/**
+ * Is a promise that can be externally resolved.
+ */
 export declare function isDeferred<T>(t: T | Promise<T> | Deferred<T>): t is Deferred<T>;
+/**
+ * Returns true if array1 and array2 have the same length, and every pair of
+ * values within them pass the `comparator` check (which defaults to `===`).
+ */
 export declare function arraysMatch<T>(array1: ReadonlyArray<T>, array2: ReadonlyArray<T>, comparator?: (val1: T, val2: T) => boolean): boolean;
 export type ObjectTypeFields<TContext extends Grafast.Context, TParentStep extends ExecutableStep> = {
     [key: string]: GrafastFieldConfig<GraphQLOutputType, TContext, TParentStep, any, any>;
 };
 export type ObjectTypeSpec<TContext extends Grafast.Context, TParentStep extends ExecutableStep, TFields extends ObjectTypeFields<TContext, TParentStep>> = Omit<GraphQLObjectTypeConfig<any, TContext>, "fields"> & {
     fields: TFields | (() => TFields);
+    assertStep?: TParentStep extends ExecutableStep ? ((step: ExecutableStep) => asserts step is TParentStep) | {
+        new (...args: any[]): TParentStep;
+    } : null;
 };
-export declare function objectSpec<TContext extends Grafast.Context, TParentStep extends ExecutableStep, TFields extends ObjectTypeFields<TContext, TParentStep>>(spec: ObjectTypeSpec<TContext, TParentStep, TFields>, Step: ((step: ExecutableStep) => asserts step is ExecutableStep) | {
-    new (...args: any[]): TParentStep;
-} | null): GraphQLObjectTypeConfig<any, TContext>;
+/**
+ * Saves us having to write `extensions: {grafast: {...}}` everywhere.
+ */
+export declare function objectSpec<TContext extends Grafast.Context, TParentStep extends ExecutableStep, TFields extends ObjectTypeFields<TContext, TParentStep>>(spec: ObjectTypeSpec<TContext, TParentStep, TFields>): GraphQLObjectTypeConfig<any, TContext>;
 export type GrafastObjectType<TContext extends Grafast.Context, TParentStep extends ExecutableStep, TFields extends ObjectTypeFields<TContext, TParentStep>> = graphql.GraphQLObjectType<TParentStep extends ExecutableStep<infer U> ? U : never, TContext> & {
     TParentStep: TParentStep;
     TFields: TFields;
 };
-export declare function newObjectTypeBuilder<TContext extends Grafast.Context, TParentStep extends ExecutableStep>(Step: {
+/**
+ * @remarks This is a mess because the first two generics need to be specified manually, but the latter one we want inferred.
+ */
+export declare function newObjectTypeBuilder<TContext extends Grafast.Context, TParentStep extends ExecutableStep>(assertStep: TParentStep extends ExecutableStep ? ((step: ExecutableStep) => asserts step is TParentStep) | {
     new (...args: any[]): TParentStep;
-}): <TFields extends ObjectTypeFields<TContext, TParentStep>>(spec: ObjectTypeSpec<TContext, TParentStep, TFields>) => GrafastObjectType<TContext, TParentStep, TFields>;
+} : never): <TFields extends ObjectTypeFields<TContext, TParentStep>>(spec: ObjectTypeSpec<TContext, TParentStep, TFields>) => GrafastObjectType<TContext, TParentStep, TFields>;
+/**
+ * Saves us having to write `extensions: {grafast: {...}}` everywhere.
+ */
 export declare function objectFieldSpec<TContext extends Grafast.Context, TSource extends ExecutableStep, TResult extends ExecutableStep = ExecutableStep, TArgs extends BaseGraphQLArguments = BaseGraphQLArguments>(grafastSpec: GrafastFieldConfig<GraphQLOutputType, TContext, TSource, TResult, TArgs>, path: string): GraphQLFieldConfig<any, TContext, TArgs>;
+/**
+ * "Constrainted identity function" for field configs.
+ *
+ * @see {@link https://kentcdodds.com/blog/how-to-write-a-constrained-identity-function-in-typescript}
+ */
 export declare function newGrafastFieldConfigBuilder<TContext extends Grafast.Context, TParentStep extends ExecutableStep>(): <TType extends GraphQLOutputType, TFieldStep extends OutputPlanForType<TType>, TArgs extends BaseGraphQLArguments>(config: GrafastFieldConfig<TType, TContext, TParentStep, TFieldStep, TArgs>) => typeof config;
 export type GrafastInputFieldConfigMap<TContext extends Grafast.Context, TParentStep extends ModifierStep<any>> = {
     [key: string]: GrafastInputFieldConfig<GraphQLInputType, TContext, TParentStep, any, any>;
@@ -41,6 +76,9 @@ export type GrafastInputObjectType<TContext extends Grafast.Context, TParentStep
     TFields: TFields;
 };
 export declare function newInputObjectTypeBuilder<TContext extends Grafast.Context, TParentStep extends ModifierStep<any>>(): <TFields extends GrafastInputFieldConfigMap<TContext, TParentStep>>(spec: InputObjectTypeSpec<TContext, TParentStep, TFields>) => GrafastInputObjectType<TContext, TParentStep, TFields>;
+/**
+ * Saves us having to write `extensions: {grafast: {...}}` everywhere.
+ */
 export declare function inputObjectFieldSpec<TContext extends Grafast.Context, TParent extends ModifierStep<any>, TResult extends ModifierStep<TParent> = ModifierStep<TParent>, TInput extends InputStep = InputStep>(grafastSpec: GrafastInputFieldConfig<GraphQLInputType, TContext, TParent, TResult, TInput>, path: string): GraphQLInputFieldConfig;
 declare module "graphql" {
     interface GraphQLEnumType {
@@ -48,17 +86,87 @@ declare module "graphql" {
     }
 }
 declare const $$valueConfigByValue: unique symbol;
+/**
+ * This would be equivalent to `enumType._valueLookup.get(outputValue)` except
+ * that's not a public API so we have to do a bit of heavy lifting here. Since
+ * it is heavy lifting, we cache the result, but we don't know when enumType
+ * will go away so we use a weakmap.
+ */
 export declare function getEnumValueConfig(enumType: graphql.GraphQLEnumType, outputValue: string): GraphQLEnumValueConfig | undefined;
+/**
+ * It's a peculiarity of V8 that `{}` is twice as fast as
+ * `Object.create(null)`, but `Object.create(sharedNull)` is the same speed as
+ * `{}`. Hat tip to `@purge` for bringing this to my attention.
+ *
+ * @internal
+ */
 export declare const sharedNull: any;
+/**
+ * Prints out the stack trace to the current position with a message; useful
+ * for debugging which code path has hit this line.
+ *
+ * @internal
+ */
 export declare function stack(message: string, length?: number): void;
+/**
+ * Ridiculously, this is faster than `new Array(length).fill(fill)`
+ *
+ * @internal
+ */
 export declare function arrayOfLength(length: number, fill?: any): any[];
+/**
+ * Builds an array of length `length` calling `fill` for each entry in the
+ * list and storing the result.
+ *
+ * @internal
+ */
 export declare function arrayOfLengthCb(length: number, fill: () => any): any[];
+/**
+ * Given a FieldNode, recursively walks and finds all the variable references,
+ * returning a list of the (unique) variable names used.
+ */
 export declare function findVariableNamesUsed(operationPlan: OperationPlan, field: FieldNode): string[];
 export declare function isTypePlanned(schema: GraphQLSchema, namedType: GraphQLNamedType): boolean;
 export declare function stepADependsOnStepB(stepA: ExecutableStep, stepB: ExecutableStep): boolean;
+/**
+ * Returns true if stepA is allowed to depend on stepB, false otherwise. (This
+ * mostly relates to heirarchy.)
+ */
 export declare function stepAMayDependOnStepB($a: ExecutableStep, $b: ExecutableStep): boolean;
+/**
+ * For a regular GraphQL query with no `@stream`/`@defer`, the entire result is
+ * calculated and then the output is generated and sent to the client at once.
+ * Thus you can think of this as every plan is in the same "phase".
+ *
+ * However, if you introduce a `@stream`/`@defer` selection, then the steps
+ * inside that selection should run _later_ than the steps in the parent
+ * selection - they should run in two different phases. Similar is true for
+ * subscriptions.
+ *
+ * When optimizing your plans, if you are not careful you may end up pushing
+ * what should be later work into the earlier phase, resulting in the initial
+ * payload being delayed whilst things that should have been deferred are being
+ * calculated. Thus, you should generally check that two plans are in the same phase
+ * before you try and merge them.
+ *
+ * This is not a strict rule, though, because sometimes it makes more sense to
+ * push work into the parent phase because it would be faster overall to do
+ * that work there, and would not significantly delay the initial payload's
+ * execution time - for example it's unlikely that it would make sense to defer
+ * selecting an additional boolean column from a database table even if the
+ * operation indicates that's what you should do.
+ *
+ * As a step class author, it's your responsiblity to figure out the right
+ * approach. Once you have, you can use this function to help you, should you
+ * need it.
+ */
 export declare function stepsAreInSamePhase(ancestor: ExecutableStep, descendent: ExecutableStep): boolean;
 export declare const canonicalJSONStringify: (o: object) => string;
 export declare function assertNotAsync(fn: any, name: string): void;
+export declare function hasItemPlan(step: ExecutableStep & {
+    itemPlan?: ($item: ExecutableStep) => ExecutableStep;
+}): step is ExecutableStep & {
+    itemPlan: ($item: ExecutableStep) => ExecutableStep;
+};
 export {};
 //# sourceMappingURL=utils.d.ts.map

package/dist/version.d.ts

@@ -0,0 +1,2 @@
+export declare const version = "0.0.1-beta.2";
+//# sourceMappingURL=version.d.ts.map

package/fwd/graphql/index.d.ts

@@ -0,0 +1 @@
+export * from "graphql";

package/fwd/graphql/index.js

@@ -0,0 +1 @@
+module.exports = require("graphql");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "grafast",
-  "version": "0.0.1-alpha.9",
+  "version": "0.0.1-beta.2",
   "description": "Cutting edge GraphQL planning and execution engine",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -14,6 +14,11 @@
       "types": "./dist/envelop.d.ts",
       "node": "./dist/envelop.js",
       "default": "./dist/envelop.js"
+    },
+    "./graphql": {
+      "types": "./fwd/graphql/index.d.ts",
+      "node": "./fwd/graphql/index.js",
+      "default": "./fwd/graphql/index.js"
     }
   },
   "repository": {
@@ -36,7 +41,7 @@
     "graphite"
   ],
   "author": "Benjie Gillam <code@benjiegillam.com>",
-  "license": "SEE LICENSE IN LICENSE.md",
+  "license": "MIT",
   "bugs": {
     "url": "https://github.com/graphile/heart/issues"
   },
@@ -45,14 +50,16 @@
     "node": ">=14.17"
   },
   "dependencies": {
-    "@graphile/lru": "^5.0.0-alpha.2",
+    "@graphile/lru": "^5.0.0-beta.1",
     "debug": "^4.3.3",
-    "tamedevil": "^0.0.0-alpha.3"
+    "graphql": "^16.1.0-experimental-stream-defer.6",
+    "tamedevil": "^0.0.0-beta.1"
   },
   "peerDependencies": {
     "@envelop/core": "^3.0.4",
-    "graphile-config": "^0.0.1-alpha.4",
-    "graphql": "^16.1.0-experimental-stream-defer.6"
+    "graphile-config": "^0.0.1-beta.1",
+    "graphql": "^16.1.0-experimental-stream-defer.6",
+    "tamedevil": "^0.0.0-beta.1"
   },
   "peerDependenciesMeta": {
     "@envelop/core": {
@@ -63,6 +70,7 @@
     }
   },
   "files": [
+    "fwd",
     "dist"
   ],
   "publishConfig": {