stash-graphql-client 0.0.0-stage → 0.31.2

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export { createStash } from "./client.ts";
+export type { StashClient } from "./client.ts";
+export { StashError } from "./transport.ts";
+export type { StashOptions, Subscription, SubscriptionClient } from "./transport.ts";
+export type { GraphQLRequest } from "./request.ts";
+export type { Args, Field, Fields, Fragment, ObjectName, Result, RootField, Selection, SubscriptionField, } from "./types.ts";
+export { STASH_VERSION } from "./generated/roots.ts";
+export type * from "./generated/schema.ts";

package/dist/index.js

@@ -0,0 +1,3 @@
+export { createStash } from "./client.js";
+export { StashError } from "./transport.js";
+export { STASH_VERSION } from "./generated/roots.js";

package/dist/request.d.ts

@@ -0,0 +1,23 @@
+export type OperationKind = "query" | "mutation" | "subscription";
+export interface GraphQLRequest {
+    query: string;
+    variables: Record<string, unknown>;
+}
+type FieldCall = (args?: unknown, select?: unknown) => FieldCall;
+/**
+ * The fields of any object type: reading `fields.name` selects that field, and calling it adds
+ * arguments and a nested selection. It needs no schema, because the types already check usage.
+ */
+export declare const fields: unknown;
+/** Selects a field; also called by the client for root fields. */
+export declare function field(name: string, args?: unknown, select?: unknown): FieldCall;
+/**
+ * Builds one GraphQL request from selected root fields. Root arguments become variables; with
+ * several root fields they are prefixed with the result key so they can't collide. `upload`
+ * tells whether the variables may contain files.
+ */
+export declare function buildRequest(kind: OperationKind, select: unknown): {
+    request: GraphQLRequest;
+    upload: boolean;
+};
+export {};

package/dist/request.js

@@ -0,0 +1,131 @@
+import { ROOTS } from "./generated/roots.js";
+/** What each selected value stands for; the values themselves are opaque to callers. */
+const nodes = new WeakMap();
+/**
+ * The fields of any object type: reading `fields.name` selects that field, and calling it adds
+ * arguments and a nested selection. It needs no schema, because the types already check usage.
+ */
+export const fields = new Proxy({}, {
+    get: (_, key) => typeof key !== "string"
+        ? undefined
+        : key === "$on"
+            ? on
+            : key === "$pick"
+                ? pick
+                : field(key),
+});
+/** Selects a field; also called by the client for root fields. */
+export function field(name, args, select) {
+    const call = (first, second) => isCallback(first)
+        ? field(name, undefined, first(fields))
+        : field(name, first, isCallback(second) ? second(fields) : undefined);
+    nodes.set(call, { kind: "field", name, args, select });
+    return call;
+}
+function pick(...names) {
+    return Object.fromEntries(names.map((name) => [name, field(name)]));
+}
+function on(type, select) {
+    const fragment = {};
+    nodes.set(fragment, { kind: "fragment", type, select: select(fields) });
+    return { [`... on ${type}`]: fragment };
+}
+/**
+ * Builds one GraphQL request from selected root fields. Root arguments become variables; with
+ * several root fields they are prefixed with the result key so they can't collide. `upload`
+ * tells whether the variables may contain files.
+ */
+export function buildRequest(kind, select) {
+    const definitions = [];
+    const variables = {};
+    let upload = false;
+    const selected = entries(select);
+    const roots = selected.map(([key, value]) => {
+        const node = fieldNode(key, value);
+        const root = ROOTS[node.name];
+        if (root?.[0] !== kind)
+            throw new Error(`${node.name} is not a ${kind} field`);
+        const [, types, files] = root;
+        upload ||= files === true;
+        const calls = [];
+        for (const [name, argument] of entries(node.args ?? {})) {
+            // undefined means "not passed"; null is a meaningful value and is sent as is.
+            if (argument === undefined)
+                continue;
+            const type = types[name];
+            if (type === undefined)
+                throw new Error(`Unknown argument ${name} on ${node.name}`);
+            const variable = selected.length === 1 ? name : `${key}_${name}`;
+            definitions.push(`$${variable}:${type}`);
+            calls.push(`${name}:$${variable}`);
+            variables[variable] = argument;
+        }
+        return selectField(key, node, calls);
+    });
+    if (roots.length === 0)
+        throw new Error("An operation must select at least one field");
+    if (kind === "subscription" && roots.length > 1) {
+        throw new Error("A subscription must have exactly one root field");
+    }
+    const header = definitions.length > 0 ? `(${definitions.join(",")})` : "";
+    const request = { query: `${kind}${header}{${roots.join(" ")}}`, variables };
+    return { request, upload };
+}
+function selectionSet(select) {
+    if (select === undefined)
+        return "";
+    const parts = [];
+    for (const [key, value] of entries(select)) {
+        const node = isObject(value) ? nodes.get(value) : undefined;
+        if (node?.kind === "fragment") {
+            // __typename is needed to tell union members apart.
+            if (!parts.includes("__typename"))
+                parts.push("__typename");
+            parts.push(`... on ${graphqlName(node.type)}${selectionSet(node.select)}`);
+        }
+        else {
+            const selected = fieldNode(key, value);
+            parts.push(selectField(key, selected, literals(selected.args)));
+        }
+    }
+    if (parts.length === 0)
+        throw new Error("A selection must select at least one field");
+    return `{${parts.join(" ")}}`;
+}
+function selectField(key, node, args) {
+    const alias = key === node.name ? "" : `${graphqlName(key)}:`;
+    const call = args.length > 0 ? `(${args.join(",")})` : "";
+    return `${alias}${graphqlName(node.name)}${call}${selectionSet(node.select)}`;
+}
+/** Nested arguments are scalars (checked by the generator), so JSON is valid GraphQL syntax. */
+function literals(args) {
+    return entries(args ?? {})
+        .filter(([, argument]) => argument !== undefined)
+        .map(([key, argument]) => `${graphqlName(key)}:${literal(argument)}`);
+}
+function literal(value) {
+    return Array.isArray(value) ? `[${value.map(literal).join(",")}]` : JSON.stringify(value);
+}
+function fieldNode(key, value) {
+    const node = isObject(value) ? nodes.get(value) : undefined;
+    if (node?.kind !== "field")
+        throw new Error(`${key} is not a selected field`);
+    return node;
+}
+/** Keys end up in the document, so only GraphQL names are allowed. */
+function graphqlName(value) {
+    if (!/^[_A-Za-z][_0-9A-Za-z]*$/.test(value))
+        throw new Error(`Invalid GraphQL name: ${value}`);
+    return value;
+}
+function entries(value) {
+    if (!isObject(value))
+        throw new Error("A selection must be an object");
+    return Object.entries(value);
+}
+function isObject(value) {
+    return (typeof value === "object" && value !== null) || typeof value === "function";
+}
+function isCallback(value) {
+    return typeof value === "function";
+}

package/dist/transport.d.ts

@@ -0,0 +1,40 @@
+import type { GraphQLRequest } from "./request.ts";
+/** A running subscription; `return()`, or leaving a `for await` loop, unsubscribes. */
+export interface Subscription<T> extends AsyncIterableIterator<T> {
+    return(): Promise<IteratorResult<T, undefined>>;
+}
+/** Anything with the `iterate` method of a `graphql-ws` client. */
+export interface SubscriptionClient {
+    iterate(request: GraphQLRequest): AsyncIterableIterator<unknown>;
+}
+export interface StashOptions {
+    /** GraphQL endpoint, e.g. `http://localhost:9999/graphql`. */
+    endpoint: string;
+    /** Sent as the `ApiKey` header. */
+    apiKey?: string | undefined;
+    /** Extra request headers. */
+    headers?: Record<string, string> | undefined;
+    /** Custom fetch, e.g. to add timeouts or for tests. */
+    fetch?: ((input: string, init: RequestInit) => Promise<Response>) | undefined;
+    /** Custom `graphql-ws` client for subscriptions; by default one is created on first use. */
+    subscriptions?: SubscriptionClient | undefined;
+}
+/** Thrown for non-2xx responses and GraphQL errors. */
+export declare class StashError extends Error {
+    readonly status: number;
+    readonly errors: readonly {
+        message: string;
+    }[];
+    /** The `data` of a partial result: GraphQL can return data next to errors. */
+    readonly data: Record<string, unknown> | undefined;
+    constructor(message: string, status: number, errors?: {
+        message: string;
+    }[], data?: Record<string, unknown>);
+}
+/** Sends requests over HTTP and subscriptions over WebSocket; results are untyped here. */
+export declare function createTransport(options: StashOptions): {
+    send: (request: GraphQLRequest, upload?: boolean) => Promise<Record<string, unknown>>;
+    /** Streams the values of root field `field`. */
+    subscribe(request: GraphQLRequest, field: string): Subscription<unknown>;
+    request: (query: string, variables?: Record<string, unknown>) => Promise<Record<string, unknown>>;
+};

package/dist/transport.js

@@ -0,0 +1,140 @@
+/** Thrown for non-2xx responses and GraphQL errors. */
+export class StashError extends Error {
+    status;
+    errors;
+    /** The `data` of a partial result: GraphQL can return data next to errors. */
+    data;
+    constructor(message, status, errors = [], data) {
+        super(message);
+        this.name = "StashError";
+        this.status = status;
+        this.errors = errors;
+        this.data = data;
+    }
+}
+/** Sends requests over HTTP and subscriptions over WebSocket; results are untyped here. */
+export function createTransport(options) {
+    const headers = {
+        ...(options.apiKey === undefined ? {} : { ApiKey: options.apiKey }),
+        ...options.headers,
+    };
+    let client;
+    const subscriptions = () => (client ??=
+        options.subscriptions === undefined
+            ? createSubscriptionClient(options.endpoint, headers)
+            : Promise.resolve(options.subscriptions));
+    const send = async (request, upload = false) => {
+        const files = [];
+        const variables = upload ? extractFiles(request.variables, "variables", files) : undefined;
+        const response = await (options.fetch ?? fetch)(options.endpoint, {
+            method: "POST",
+            // Never forward the API key to another host.
+            redirect: "error",
+            ...(files.length === 0
+                ? {
+                    headers: { "content-type": "application/json", ...headers },
+                    body: JSON.stringify(request),
+                }
+                : { headers, body: multipart(request.query, variables, files) }),
+        });
+        const payload = await response.json().catch(() => undefined);
+        return readData(payload, response.status, response.ok);
+    };
+    return {
+        send,
+        /** Streams the values of root field `field`. */
+        subscribe(request, field) {
+            let source;
+            const open = () => (source ??= subscriptions().then((subscriber) => subscriber.iterate(request)));
+            // Delegate instead of wrapping in an async generator: a generator only handles return()
+            // at its next yield, so an idle subscription could never be stopped.
+            return {
+                async next() {
+                    const iterator = await open();
+                    const result = await iterator.next();
+                    if (result.done === true)
+                        return result;
+                    try {
+                        return { value: readData(result.value, 200, true)[field], done: false };
+                    }
+                    catch (error) {
+                        await iterator.return?.();
+                        throw error;
+                    }
+                },
+                async return() {
+                    const iterator = source === undefined ? undefined : await source;
+                    await iterator?.return?.();
+                    return { value: undefined, done: true };
+                },
+                [Symbol.asyncIterator]() {
+                    return this;
+                },
+            };
+        },
+        // Files may hide anywhere in a hand-written document, so always look for them.
+        request: (query, variables = {}) => send({ query, variables }, true),
+    };
+}
+/** Loaded on first use, so code without subscriptions never bundles graphql-ws. */
+async function createSubscriptionClient(endpoint, headers) {
+    const { createClient } = await import("graphql-ws");
+    const url = endpoint.replace(/^http/, "ws");
+    // Browsers can't set headers on a WebSocket; they authenticate with the session cookie.
+    if (Object.keys(headers).length === 0)
+        return createClient({ url });
+    const NativeWebSocket = WebSocket;
+    class AuthenticatedWebSocket extends NativeWebSocket {
+        constructor(address, protocols) {
+            super(address, {
+                protocols: typeof protocols === "string" ? [protocols] : protocols,
+                headers,
+            });
+        }
+    }
+    return createClient({ url, webSocketImpl: AuthenticatedWebSocket });
+}
+function readData(payload, status, ok) {
+    const errors = isObject(payload) && Array.isArray(payload["errors"])
+        ? payload["errors"].map((error) => ({
+            message: isObject(error) && typeof error["message"] === "string"
+                ? error["message"]
+                : String(error),
+        }))
+        : [];
+    if (!ok || errors.length > 0) {
+        const message = errors.map((error) => error.message).join("\n");
+        const data = isObject(payload) && isObject(payload["data"]) ? payload["data"] : undefined;
+        throw new StashError(message || `HTTP ${status}`, status, errors, data);
+    }
+    return isObject(payload) && isObject(payload["data"]) ? payload["data"] : {};
+}
+/** GraphQL multipart request, https://github.com/jaydenseric/graphql-multipart-request-spec */
+function multipart(query, variables, files) {
+    const form = new FormData();
+    form.append("operations", JSON.stringify({ query, variables }));
+    form.append("map", JSON.stringify(Object.fromEntries(files.map(([path], index) => [index, [path]]))));
+    for (const [index, [, file]] of files.entries())
+        form.append(String(index), file);
+    return form;
+}
+/** Replaces files with null and records their paths, as the multipart spec requires. */
+function extractFiles(value, path, files) {
+    if (value instanceof Blob) {
+        files.push([path, value]);
+        return null;
+    }
+    if (Array.isArray(value)) {
+        return value.map((item, index) => extractFiles(item, `${path}.${index}`, files));
+    }
+    if (isObject(value)) {
+        return Object.fromEntries(Object.entries(value).map(([key, item]) => [
+            key,
+            extractFiles(item, `${path}.${key}`, files),
+        ]));
+    }
+    return value;
+}
+function isObject(value) {
+    return typeof value === "object" && value !== null;
+}

package/dist/types.d.ts

@@ -0,0 +1,120 @@
+import type { Abstract, Objects } from "./generated/schema.ts";
+import type { Subscription } from "./transport.ts";
+/** A field with arguments `A` and return type expression `T`. */
+export interface F<A, T> {
+    args: A;
+    type: T;
+}
+/** A list of `T`. */
+export interface L<T> {
+    list: T;
+}
+/** A nullable `T`; anything not wrapped in `N` is non-null. */
+export interface N<T> {
+    nullable: T;
+}
+/** A reference to an object, interface or union type. */
+export interface R<Name extends keyof Objects> {
+    ref: Name;
+}
+export type ObjectName = keyof Objects;
+declare const fieldValue: unique symbol;
+declare const fragmentValue: unique symbol;
+declare const fieldsOf: unique symbol;
+/** A selected field whose value in the result is `T`. */
+export interface Field<T> {
+    readonly [fieldValue]: T;
+}
+/** Fields selected on one member of a union or interface, see `$on`. */
+export interface Fragment<T> {
+    readonly [fragmentValue]: T;
+}
+/** What a selection callback returns: result keys mapped to selected fields. */
+export type Selection = Record<string, Field<unknown> | Fragment<unknown>>;
+type Unwrap<T> = T extends N<infer I> ? Unwrap<I> : T extends L<infer I> ? Unwrap<I> : T;
+/** The value of a field of type `T`; `Inner` is the value of the object it refers to. */
+type Wrap<T, Inner> = T extends N<infer I> ? Wrap<I, Inner> | null : T extends L<infer I> ? Wrap<I, Inner>[] : T extends R<ObjectName> ? Inner : T;
+type Value<S> = S extends Field<infer T> ? T : never;
+type FragmentKey = `... on ${string}`;
+type MemberOutput<S, M extends string> = S extends Record<`... on ${M}`, Fragment<infer T>> ? T : {};
+/**
+ * The result of selection `S` on object type `Name`. The mapped types are written inline rather
+ * than as named helpers so that editors show the resulting object instead of a helper name.
+ */
+export type Output<Name extends ObjectName, S> = Name extends keyof Abstract ? Extract<keyof S, FragmentKey> extends never ? {
+    [K in keyof S]: Value<S[K]>;
+} : {
+    [M in Abstract[Name]]: {
+        [K in Exclude<keyof S, FragmentKey>]: Value<S[K]>;
+    } & {
+        __typename: M;
+    } & MemberOutput<S, M> extends infer O ? {
+        [K in keyof O]: O[K];
+    } : never;
+}[Abstract[Name]] : {
+    [K in keyof S]: Value<S[K]>;
+};
+type Select<Name extends ObjectName, S> = (fields: Fields<Name>) => S;
+type NoArgs<A> = [keyof A] extends [never] ? true : false;
+type ScalarField<A, V> = NoArgs<A> extends true ? Field<V> : {} extends A ? Field<V> & ((args: A) => Field<V>) : (args: A) => Field<V>;
+/** How a selected value arrives: as a nested field, a request or a subscription. */
+type Delivery<Kind, V> = Kind extends "subscription" ? Subscription<V> : Kind extends "query" ? Promise<V> : Field<V>;
+type ObjectField<A, T, Name extends ObjectName, Kind = "field"> = NoArgs<A> extends true ? <S extends Selection>(select: Select<Name, S>) => Delivery<Kind, Wrap<T, Output<Name, S>>> : {} extends A ? {
+    <S extends Selection>(select: Select<Name, S>): Delivery<Kind, Wrap<T, Output<Name, S>>>;
+    <S extends Selection>(args: A | undefined, select: Select<Name, S>): Delivery<Kind, Wrap<T, Output<Name, S>>>;
+} : <S extends Selection>(args: A, select: Select<Name, S>) => Delivery<Kind, Wrap<T, Output<Name, S>>>;
+type FieldOf<Definition> = Definition extends F<infer A, infer T> ? Unwrap<T> extends R<infer Name> ? ObjectField<A, T, Name> : ScalarField<A, Wrap<T, never>> : never;
+/**
+ * Selects fields on member `M` of a union or interface. Spread the result into the selection;
+ * the result is then narrowed by `__typename`.
+ */
+type On<Name extends keyof Abstract> = <M extends Abstract[Name] & ObjectName, S extends Selection>(type: M, select: Select<M, S>) => {
+    [K in `... on ${M}`]: Fragment<Output<M, S>>;
+};
+/** Fields that can be selected by name alone: scalars without required arguments. */
+type Pickable<Name extends ObjectName> = {
+    [K in keyof Objects[Name]]: FieldOf<Objects[Name][K]> extends Field<unknown> ? K : never;
+}[keyof Objects[Name]];
+/** Selects scalar fields by name. Spread the result into a selection, or return it as is. */
+type PickFields<Name extends ObjectName> = <K extends Pickable<Name>>(...names: K[]) => {
+    [P in K]: FieldOf<Objects[Name][P]>;
+};
+/**
+ * The fields of object type `Name`, passed to selection callbacks. Reading a field selects it;
+ * fields with arguments are called with them, and object fields with a nested selection.
+ * Don't use `...rest` on it: the object is empty at runtime, so a rest element selects nothing.
+ */
+export type Fields<Name extends ObjectName> = {
+    readonly [K in keyof Objects[Name]]: FieldOf<Objects[Name][K]>;
+} & {
+    /** The name of the object type. */
+    readonly __typename: Field<Name extends keyof Abstract ? Abstract[Name] : Name>;
+    readonly $pick: PickFields<Name>;
+    /** Type-only: lets `Result` find the object type of a selection callback. */
+    readonly [fieldsOf]?: Name;
+} & (Name extends keyof Abstract ? {
+    readonly $on: On<Name>;
+} : {});
+/**
+ * The result of a reusable selection callback:
+ * `const card = (performer: Fields<"Performer">) => ({ id: performer.id })` gives
+ * `Result<typeof card>`, which is `{ id: string }`.
+ */
+export type Result<Callback> = Callback extends (fields: infer Input, ...options: never[]) => infer S ? Input extends {
+    readonly [fieldsOf]?: infer Name extends ObjectName;
+} ? Output<Name, S> : never : never;
+/** All root fields; mapping over `keyof Root` keeps their docs on the client methods. */
+export type Root = Objects["Query"] & Objects["Mutation"] & Objects["Subscription"];
+/** Every query, mutation and subscription root field. */
+export type RootField = keyof Root;
+/** Root fields delivered over WebSocket. */
+export type SubscriptionField = keyof Objects["Subscription"];
+/** Arguments of a root field. */
+export type Args<K extends RootField> = Root[K] extends F<infer A extends object, unknown> ? A : never;
+type ScalarMethod<A, V, Kind> = NoArgs<A> extends true ? () => Delivery<Kind, V> : {} extends A ? (args?: A) => Delivery<Kind, V> : (args: A) => Delivery<Kind, V>;
+type Method<Definition, Kind> = Definition extends F<infer A, infer T> ? Unwrap<T> extends R<infer Name> ? ObjectField<A, T, Name, Kind> : ScalarMethod<A, Wrap<T, never>, Kind> : never;
+/** One method per root field: arguments first (when it has any), then the selection. */
+export type RootMethods = {
+    [K in keyof Root]: Method<Root[K], K extends SubscriptionField ? "subscription" : "query">;
+};
+export {};

package/package.json

@@ -1,6 +1,56 @@
 {
   "name": "stash-graphql-client",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.31.2",
+  "description": "Fully typed client for the Stash GraphQL API, without writing GraphQL",
+  "keywords": [
+    "graphql",
+    "stash",
+    "stashapp",
+    "typescript"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/shalemore/stash-graphql-client.git"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "lint": "oxfmt --check && oxlint",
+    "fix": "oxfmt && oxlint --fix",
+    "schema": "bun scripts/schema.ts && bun run generate",
+    "generate": "bun scripts/generate.ts && oxfmt schema src/generated",
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "verify": "bun check && bun run lint && bun test"
+  },
+  "dependencies": {
+    "graphql-ws": "^6.3.0"
+  },
+  "devDependencies": {
+    "@octokit/rest": "^22.0.1",
+    "@tsconfig/bun": "^1.0.11",
+    "@tsconfig/strictest": "^2.0.8",
+    "@types/bun": "^1.4.3",
+    "@types/semver": "^7.8.0",
+    "graphql": "^17.0.2",
+    "oxfmt": "^0.72.0",
+    "oxlint": "^1.87.0",
+    "oxlint-tsgolint": "^7.0.2004",
+    "semver": "^7.8.5",
+    "typescript": "^7.0.2",
+    "zod": "^4.6.7"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "packageManager": "bun@1.4.3"
+}