@distilled.cloud/core 1.0.0-rc.3 → 1.0.0-rc.5

package/lib/codegen/graphql.d.ts

@@ -0,0 +1,201 @@
+/**
+ * Shared GraphQL → Smithy 2.0 converter (dev-time only).
+ *
+ * A GraphQL endpoint has no per-operation URLs, no path/query/header bindings
+ * and no response shapes to speak of: there is one POST, one request envelope
+ * (`{ query, operationName, variables }`) and one response envelope
+ * (`{ data, errors }`). What varies per operation is the *document* — which
+ * root field is called, which variables it takes, and which selection set
+ * comes back. This module turns an introspection schema into a Smithy model
+ * carrying exactly that:
+ *
+ *   • operation      → `smithy.api#http` (POST <endpoint>) + the op shape
+ *   • input struct   → `<traits.operation>` { query, operationName, type } —
+ *                      the baked GraphQL document for the op
+ *   • output struct  → `<traits.responsePath>` ("account.byId") — the path
+ *                      under `data` the protocol unwraps
+ *   • nullability    → `<traits.nullable>` on members,
+ *                      `<traits.nullableItems>` on list shapes (GraphQL
+ *                      nullability is not Smithy optionality: a selected
+ *                      field is always *delivered*, it just may be `null`)
+ *   • bare results   → `<traits.payload>` on the sole `result` member when
+ *                      the leaf returns a list/scalar (the response IS that
+ *                      value)
+ *   • connections    → `smithy.api#paginated` when a root field looks like a
+ *                      Relay connection (see {@link RelayOptions})
+ *
+ * Trait *ids* are caller-supplied so each SDK keeps its own vocabulary
+ * namespace; the generator side maps them back to that SDK's trait module.
+ *
+ * ─── Operation discovery ────────────────────────────────────────────────────
+ * Most schemas put operations directly on Query/Mutation, but some namespace
+ * them behind objects whose fields are the real operations (`account.byId`).
+ * `maxNamespaceDepth` bounds how far that expansion goes; set it to 1 for a
+ * flat schema. Selection sets are expanded to `maxDepth` levels, cycles
+ * short-circuit, and fields that themselves take arguments are not selected
+ * (we have no value to pass them).
+ *
+ * Originally distilled v0's `core/scripts/generate-graphql.ts`, generalized
+ * out of packages/expo-eas.
+ */
+export type TypeKind = "SCALAR" | "OBJECT" | "INTERFACE" | "UNION" | "ENUM" | "INPUT_OBJECT" | "LIST" | "NON_NULL";
+export interface TypeRef {
+    kind: TypeKind;
+    name?: string | null;
+    ofType?: TypeRef | null;
+}
+export interface InputValue {
+    name: string;
+    description?: string | null;
+    type: TypeRef;
+    defaultValue?: string | null;
+}
+export interface Field {
+    name: string;
+    description?: string | null;
+    args: InputValue[];
+    type: TypeRef;
+    isDeprecated?: boolean;
+}
+export interface IntrospectionType {
+    kind: TypeKind;
+    name: string;
+    description?: string | null;
+    fields?: Field[] | null;
+    inputFields?: InputValue[] | null;
+    enumValues?: Array<{
+        name: string;
+        isDeprecated?: boolean;
+    }> | null;
+    possibleTypes?: TypeRef[] | null;
+}
+export interface IntrospectionSchema {
+    queryType: {
+        name: string;
+    };
+    mutationType?: {
+        name: string;
+    } | null;
+    subscriptionType?: {
+        name: string;
+    } | null;
+    types: IntrospectionType[];
+}
+/**
+ * Pull the `__schema` out of an introspection response, accepting either the
+ * bare schema, `{ __schema }`, or a full `{ data: { __schema } }` envelope —
+ * all three are shipped by real mirrors.
+ */
+export declare const readIntrospection: (json: unknown) => IntrospectionSchema;
+export declare const PRELUDE: {
+    readonly String: "smithy.api#String";
+    readonly Boolean: "smithy.api#Boolean";
+    readonly Integer: "smithy.api#Integer";
+    readonly Long: "smithy.api#Long";
+    readonly Double: "smithy.api#Double";
+    readonly Timestamp: "smithy.api#Timestamp";
+    readonly Document: "smithy.api#Document";
+};
+/**
+ * The Smithy trait ids this converter stamps. Each SDK owns its own trait
+ * namespace (`com.expo.graphql#operation`, `com.railway.graphql#operation`,
+ * …) and maps them back to its trait module in its `generate.ts`.
+ */
+export interface GraphQLTraitIds {
+    /** On the input struct: the baked `{ query, operationName, type }`. */
+    readonly operation: string;
+    /** On the output struct: the dotted path under `data` to unwrap. */
+    readonly responsePath: string;
+    /** On members: the GraphQL type was nullable. */
+    readonly nullable: string;
+    /** On list shapes: the GraphQL *element* type was nullable. */
+    readonly nullableItems: string;
+    /** On the sole `result` member: the response IS this value. */
+    readonly payload: string;
+}
+/**
+ * Relay connection detection. A root field paginates when its return type
+ * looks like a connection (an `edges` list of objects with a `node`, plus a
+ * `pageInfo`) AND it accepts the forward-pagination arguments.
+ *
+ * The emitted `smithy.api#paginated` trait drives `.pages()` / `.items()` in
+ * the generated SDK; `items` deliberately points *through* the edges
+ * (`edges.node`) so `.items()` streams nodes rather than edge wrappers.
+ */
+export interface RelayOptions {
+    /** Cursor argument fed the previous page's `endCursor`. Default `"after"`. */
+    readonly after?: string;
+    /** Page-size argument. Default `"first"`. */
+    readonly first?: string;
+    /** Connection field holding the edge list. Default `"edges"`. */
+    readonly edges?: string;
+    /** Edge field holding the item. Default `"node"`. */
+    readonly node?: string;
+    /** Connection field holding the cursor/termination block. Default `"pageInfo"`. */
+    readonly pageInfo?: string;
+    /** `pageInfo` field holding the next cursor. Default `"endCursor"`. */
+    readonly endCursor?: string;
+    /** `pageInfo` field saying whether more pages exist. Default `"hasNextPage"`. */
+    readonly hasNextPage?: string;
+    /** Pagination mode written into the trait. Default `"relay"`. */
+    readonly mode?: string;
+}
+export interface GraphQLConvertOptions {
+    /** The introspection schema (see {@link readIntrospection}). */
+    readonly schema: IntrospectionSchema;
+    /** Smithy namespace for every generated shape, e.g. `"com.railway.api"`. */
+    readonly namespace: string;
+    /** Local name of the service shape, e.g. `"Railway"`. */
+    readonly serviceName: string;
+    /** `smithy.api#title` on the service shape. */
+    readonly serviceTitle: string;
+    /** `smithy.api#documentation` on the service shape. */
+    readonly serviceDocumentation?: string;
+    /** Service `version` field. Default `"1.0"`. */
+    readonly serviceVersion?: string;
+    /** HTTP path every operation POSTs to, e.g. `"/graphql/v2"`. */
+    readonly endpoint: string;
+    /** Trait ids to stamp (see {@link GraphQLTraitIds}). */
+    readonly traits: GraphQLTraitIds;
+    /** How many levels of selection set to expand. Default `3`. */
+    readonly maxDepth?: number;
+    /**
+     * How many namespace objects an operation may sit behind. `1` means the
+     * schema is flat (every operation is a direct Query/Mutation field).
+     * Default `3`.
+     */
+    readonly maxNamespaceDepth?: number;
+    /** Skip `@deprecated` root fields and namespace subfields. Default `true`. */
+    readonly skipDeprecated?: boolean;
+    /** Drop root fields by name (placeholders like `_doNotUse`). */
+    readonly skipRootField?: (name: string) => boolean;
+    /**
+     * Custom (non-builtin) scalar name → Smithy prelude target. Unmapped
+     * customs fall back to `smithy.api#Document` so nothing hard-fails, but
+     * mapping them keeps the generated types honest.
+     */
+    readonly customScalars?: Record<string, string>;
+    /** Relay connection pagination. Omit (or `false`) to emit no `paginated`. */
+    readonly relay?: RelayOptions | false;
+}
+export interface GraphQLConvertResult {
+    /** The Smithy 2.0 model, ready to `JSON.stringify`. */
+    readonly model: {
+        smithy: "2.0";
+        metadata: Record<string, unknown>;
+        shapes: Record<string, any>;
+    };
+    readonly converted: number;
+    readonly failed: number;
+    readonly paginated: number;
+    readonly shapeCount: number;
+}
+/**
+ * Turn a GraphQL introspection schema into a Smithy 2.0 model.
+ *
+ * Subscriptions are ignored: they are a streaming transport, not a
+ * `POST /graphql` request/response pair, and nothing in the generated SDK
+ * could speak them.
+ */
+export declare const convertGraphQLToSmithy: (options: GraphQLConvertOptions) => GraphQLConvertResult;
+//# sourceMappingURL=graphql.d.ts.map

package/lib/codegen/graphql.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graphql.d.ts","sourceRoot":"","sources":["../../src/codegen/graphql.ts"],"names":[],"mappings":"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"}