fareql 0.0.0-stage → 0.1.0

package/dist/price.js

@@ -0,0 +1,485 @@
+import { getNamedType, getVariableValues, isAbstractType, isCompositeType, isInterfaceType, isListType, isNonNullType, isObjectType, Kind, valueFromASTUntyped, } from 'graphql';
+/**
+ * SDL for the directives FareQL reads. Add it to your type definitions.
+ *
+ * `@listSize` follows the IBM GraphQL Cost Directives draft, so schemas that already
+ * use it for complexity analysis price connections correctly without changes.
+ * Code-first schemas can set the same values in `extensions`
+ * (`{ price: '0.001' }` or `{ directives: { price: { amount: '0.001' } } }`).
+ */
+export const fareDirectiveTypeDefs = /* GraphQL */ `
+  """
+  Price of resolving this field, or of any field returning this type, in token units (e.g. "0.001").
+  """
+  directive @price(amount: String!) on FIELD_DEFINITION | OBJECT | INTERFACE
+
+  """
+  How many items a list or connection field returns, for pricing.
+  """
+  directive @listSize(
+    assumedSize: Int
+    slicingArguments: [String!]
+    sizedFields: [String!]
+    requireOneSlicingArgument: Boolean = true
+  ) on FIELD_DEFINITION
+`;
+export class PricingError extends Error {
+    code;
+    name = 'PricingError';
+    constructor(message, code) {
+        super(message);
+        this.code = code;
+    }
+}
+export class PriceLimitError extends PricingError {
+    amount;
+    maxPrice;
+    name = 'PriceLimitError';
+    constructor(amount, maxPrice) {
+        super(`Operation price ${amount} exceeds the maximum of ${maxPrice}`, 'PRICE_LIMIT_EXCEEDED');
+        this.amount = amount;
+        this.maxPrice = maxPrice;
+    }
+}
+const DEFAULT_LIST_ARGS = ['first', 'last', 'limit', 'take', 'top', 'pageSize', 'perPage'];
+const MAX_BREAKDOWN_ITEMS = 100;
+const MAX_PATH_LENGTH = 200;
+/** Parses a decimal token amount ("0.001") into base units at `decimals`. */
+export function parseUnits(value, decimals) {
+    const m = /^(\d+)(?:\.(\d+))?$/.exec(value.trim());
+    if (!m)
+        throw new PricingError(`Invalid amount "${value}"`, 'INVALID_PRICE');
+    const whole = m[1] ?? '0';
+    const frac = m[2] ?? '';
+    if (frac.length > decimals)
+        throw new PricingError(`Amount "${value}" has more than ${decimals} decimals`, 'INVALID_PRICE');
+    return BigInt(whole) * 10n ** BigInt(decimals) + BigInt(frac.padEnd(decimals, '0') || '0');
+}
+/** Formats base units as a decimal token amount without trailing zeros. */
+export function formatUnits(units, decimals) {
+    const base = 10n ** BigInt(decimals);
+    const whole = units / base;
+    const frac = (units % base).toString().padStart(decimals, '0').replace(/0+$/, '');
+    return frac ? `${whole}.${frac}` : whole.toString();
+}
+function findDirective(host, name) {
+    if (!host)
+        return undefined;
+    for (const node of [host.astNode, ...(host.extensionASTNodes ?? [])]) {
+        const d = node?.directives?.find((x) => x.name.value === name);
+        if (!d)
+            continue;
+        const args = {};
+        for (const a of d.arguments ?? [])
+            args[a.name.value] = valueFromASTUntyped(a.value);
+        return args;
+    }
+    // Code-first schemas (graphql-tools, Pothos, Nexus…): extensions.directives.<name> or extensions.<name>.
+    const ext = host.extensions;
+    if (!ext)
+        return undefined;
+    const fromDirectives = ext['directives']?.[name];
+    const value = fromDirectives ?? ext[name];
+    const first = Array.isArray(value) ? value[0] : value;
+    if (name === 'price' && typeof first === 'string')
+        return { amount: first };
+    return first && typeof first === 'object' ? first : undefined;
+}
+const priceCache = new WeakMap();
+function directivePrice(host) {
+    if (!host)
+        return undefined;
+    const hit = priceCache.get(host);
+    if (hit !== undefined)
+        return hit ?? undefined;
+    const d = findDirective(host, 'price');
+    if (d && typeof d['amount'] !== 'string')
+        throw new PricingError('@price(amount:) must be a string such as "0.001"', 'INVALID_PRICE');
+    const amount = d ? d['amount'] : undefined;
+    priceCache.set(host, amount ?? null);
+    return amount;
+}
+/** The higher of two prices; undefined only when both are. */
+function higher(a, b, decimals) {
+    if (a === undefined)
+        return b;
+    if (b === undefined)
+        return a;
+    return parseUnits(b, decimals) > parseUnits(a, decimals) ? b : a;
+}
+/** Price of a field: its own @price, else the highest @price of the same field on an interface it implements. */
+function fieldDirectivePrice(parent, field, decimals) {
+    const own = directivePrice(field);
+    if (own !== undefined)
+        return own;
+    let best;
+    for (const i of parent.getInterfaces())
+        best = higher(best, directivePrice(i.getFields()[field.name]), decimals);
+    return best;
+}
+/** Type-level price of an object type: its own @price, else the highest of its interfaces. */
+function typePrice(type, decimals) {
+    const own = directivePrice(type);
+    if (own !== undefined)
+        return own;
+    let best;
+    for (const i of type.getInterfaces())
+        best = higher(best, directivePrice(i), decimals);
+    return best;
+}
+const schemaPriced = new WeakMap();
+/** Whether any type or field in the schema carries a price. */
+function schemaHasPrices(schema) {
+    const hit = schemaPriced.get(schema);
+    if (hit !== undefined)
+        return hit;
+    let found = false;
+    for (const type of Object.values(schema.getTypeMap())) {
+        if (type.name.startsWith('__') || !(isObjectType(type) || isInterfaceType(type)))
+            continue;
+        if (directivePrice(type) !== undefined || Object.values(type.getFields()).some((f) => directivePrice(f) !== undefined)) {
+            found = true;
+            break;
+        }
+    }
+    schemaPriced.set(schema, found);
+    return found;
+}
+function directiveListSize(host) {
+    const d = findDirective(host, 'listSize');
+    if (!d)
+        return undefined;
+    const strings = (v) => (Array.isArray(v) ? v.filter((x) => typeof x === 'string') : []);
+    return {
+        assumedSize: typeof d['assumedSize'] === 'number' ? d['assumedSize'] : undefined,
+        slicingArguments: strings(d['slicingArguments']),
+        sizedFields: strings(d['sizedFields']),
+        requireOne: d['requireOneSlicingArgument'] !== false,
+    };
+}
+// ── graphql 16 / 17 compatibility ─────────────────────────────────────────────
+/** Default value of an argument definition, in graphql 16 (`defaultValue`) and 17 (`default`). */
+function argDefault(def) {
+    const v17 = def.default;
+    if (v17)
+        return v17.literal ? valueFromASTUntyped(v17.literal) : v17.value;
+    return def.defaultValue;
+}
+function coerceVariables(schema, op, inputs) {
+    const r = getVariableValues(schema, op.variableDefinitions ?? [], inputs);
+    if (r.errors)
+        throw new PricingError(r.errors.map((e) => e.message).join('; '), 'INVALID_VARIABLES');
+    return r.coerced ?? r.variableValues?.coerced ?? {};
+}
+const pathArray = (p) => {
+    const out = [];
+    for (let n = p; n; n = n.prev)
+        out.push(n.key);
+    return out.reverse();
+};
+const ZERO = { units: 0n, items: [], truncated: false };
+function addItems(into, from) {
+    for (const item of from) {
+        if (into.length >= MAX_BREAKDOWN_ITEMS)
+            return true;
+        into.push(item);
+    }
+    return false;
+}
+function tick(ctx) {
+    if (++ctx.visits > ctx.maxVisits) {
+        throw new PricingError(`Operation is too complex to price (more than ${ctx.maxVisits} selections)`, 'TOO_COMPLEX');
+    }
+}
+function conditional(node, name, vars) {
+    const d = node.directives?.find((x) => x.name.value === name);
+    const arg = d?.arguments?.find((a) => a.name.value === 'if');
+    return arg ? valueFromASTUntyped(arg.value, vars) : undefined;
+}
+function isIncluded(node, vars) {
+    return conditional(node, 'skip', vars) !== true && conditional(node, 'include', vars) !== false;
+}
+/** Whether a fragment with type condition `condition` applies to runtime type `type`. */
+function applies(ctx, condition, type) {
+    if (!condition || condition === type)
+        return true;
+    return isAbstractType(condition) && ctx.schema.isSubType(condition, type);
+}
+function runtimeTypes(ctx, type) {
+    if (isObjectType(type))
+        return [type];
+    if (isAbstractType(type))
+        return ctx.schema.getPossibleTypes(type);
+    return [];
+}
+/**
+ * graphql-js field collection: groups selections by response key for one runtime type,
+ * follows fragments whose condition matches, and skips fragments already spread in this
+ * selection set. Priced fields are therefore charged as often as the executor resolves them.
+ */
+function collectFields(ctx, type, sets, out = new Map(), visited = new Set()) {
+    for (const set of sets) {
+        for (const sel of set.selections) {
+            tick(ctx);
+            if (!isIncluded(sel, ctx.variables))
+                continue;
+            if (sel.kind === Kind.FIELD) {
+                const key = sel.alias?.value ?? sel.name.value;
+                const list = out.get(key);
+                if (list)
+                    list.push(sel);
+                else
+                    out.set(key, [sel]);
+            }
+            else if (sel.kind === Kind.INLINE_FRAGMENT) {
+                const cond = sel.typeCondition ? ctx.schema.getType(sel.typeCondition.name.value) : undefined;
+                if (applies(ctx, cond, type))
+                    collectFields(ctx, type, [sel.selectionSet], out, visited);
+            }
+            else if (sel.kind === Kind.FRAGMENT_SPREAD) {
+                const name = sel.name.value;
+                if (visited.has(name))
+                    continue;
+                visited.add(name);
+                const frag = ctx.fragments[name];
+                if (!frag)
+                    throw new PricingError(`Unknown fragment "${name}"`, 'UNKNOWN_FRAGMENT');
+                if (applies(ctx, ctx.schema.getType(frag.typeCondition.name.value), type)) {
+                    collectFields(ctx, type, [frag.selectionSet], out, visited);
+                }
+            }
+        }
+    }
+    return out;
+}
+function argValues(field, node, vars) {
+    const out = {};
+    for (const def of field.args) {
+        const d = argDefault(def);
+        if (d !== undefined)
+            out[def.name] = d;
+    }
+    for (const a of node.arguments ?? []) {
+        const v = valueFromASTUntyped(a.value, vars);
+        if (v !== undefined)
+            out[a.name.value] = v;
+    }
+    return out;
+}
+/** Number of list levels in a type: `[Hit]` → 1, `[[Cell!]!]!` → 2. */
+function listLevels(type) {
+    let levels = 0;
+    let t = type;
+    while (true) {
+        if (isNonNullType(t))
+            t = t.ofType;
+        else if (isListType(t)) {
+            levels++;
+            t = t.ofType;
+        }
+        else
+            return levels;
+    }
+}
+/**
+ * Size given by `names` in `args` (top level, or one level inside an input object).
+ * The largest one wins. `null`, NaN and non-finite numbers mean "unbounded": maxListSize.
+ * Negative sizes are refused, since resolvers that slice with them return almost everything.
+ */
+function sliceSize(ctx, args, names) {
+    let size;
+    const consider = (name, v) => {
+        let n;
+        if (v === null)
+            n = ctx.maxListSize;
+        else if (typeof v === 'number') {
+            if (v < 0)
+                throw new PricingError(`List size "${name}" must not be negative`, 'INVALID_LIST_SIZE');
+            n = Number.isFinite(v) ? BigInt(Math.floor(v)) : ctx.maxListSize;
+            if (n > ctx.maxListSize)
+                n = ctx.maxListSize;
+        }
+        else
+            return;
+        if (size === undefined || n > size)
+            size = n;
+    };
+    for (const name of names) {
+        if (name in args)
+            consider(name, args[name]);
+        for (const v of Object.values(args)) {
+            if (v && typeof v === 'object' && !Array.isArray(v) && name in v)
+                consider(name, v[name]);
+        }
+    }
+    return size;
+}
+function sizing(ctx, field, args, path, inherited) {
+    const levels = listLevels(field.type);
+    const inner = levels > 1 ? ctx.defaultListSize ** BigInt(levels - 1) : 1n;
+    const ls = directiveListSize(field);
+    if (ls) {
+        const names = ls.slicingArguments.length > 0 ? ls.slicingArguments : ctx.listArgs;
+        if (ls.requireOne && ls.slicingArguments.length > 0) {
+            const given = ls.slicingArguments.filter((n) => args[n] !== undefined && args[n] !== null);
+            if (given.length !== 1) {
+                throw new PricingError(`Field "${pathArray(path).join('.')}" needs exactly one of ${ls.slicingArguments.map((n) => `"${n}"`).join(', ')}`, 'SLICING_ARGUMENT_REQUIRED');
+            }
+        }
+        const assumed = ls.assumedSize !== undefined ? BigInt(Math.min(Math.max(ls.assumedSize, 0), Number(ctx.maxListSize))) : undefined;
+        const size = sliceSize(ctx, args, names) ?? assumed ?? inherited ?? ctx.defaultListSize;
+        if (ls.sizedFields.length > 0) {
+            const self = levels > 0 ? (inherited ?? ctx.defaultListSize) * inner : 1n;
+            return { multiplier: self, children: { named: new Map(ls.sizedFields.map((f) => [f, size])) } };
+        }
+        return { multiplier: levels > 0 ? size * inner : 1n };
+    }
+    if (levels > 0)
+        return { multiplier: (sliceSize(ctx, args, ctx.listArgs) ?? inherited ?? ctx.defaultListSize) * inner };
+    if (ctx.connections && isCompositeType(getNamedType(field.type))) {
+        const size = sliceSize(ctx, args, ctx.listArgs);
+        if (size !== undefined) {
+            const named = ctx.connections.sizedFields;
+            return { multiplier: inherited ?? 1n, children: named ? { named: new Map(named.map((f) => [f, size])) } : { all: size } };
+        }
+    }
+    return { multiplier: inherited ?? 1n };
+}
+/** Cost of selection sets on one concrete runtime type, after graphql-js field collection. */
+function setCostOn(ctx, type, sets, path, scale, sized, depth) {
+    if (depth > ctx.maxDepth)
+        throw new PricingError(`Operation is nested deeper than ${ctx.maxDepth} levels`, 'TOO_COMPLEX');
+    let units = 0n;
+    const items = [];
+    let truncated = false;
+    for (const [key, nodes] of collectFields(ctx, type, sets)) {
+        const c = fieldCost(ctx, type, key, nodes, path, scale, sized, depth);
+        units += c.units;
+        truncated = addItems(items, c.items) || c.truncated || truncated;
+    }
+    return { units, items, truncated };
+}
+function fieldCost(ctx, parent, key, nodes, path, scale, sized, depth) {
+    const node = nodes[0];
+    const name = node.name.value;
+    if (name.startsWith('__'))
+        return ZERO; // __typename and introspection are free
+    tick(ctx);
+    const field = parent.getFields()[name];
+    if (!field)
+        throw new PricingError(`Unknown field "${name}" on type "${parent.name}"`, 'UNKNOWN_FIELD');
+    const fieldPath = { prev: path, key };
+    const args = argValues(field, node, ctx.variables);
+    const override = ctx.fieldPrice?.({ parentType: parent, field, args, path: pathArray(fieldPath) });
+    const fieldOwn = override ?? fieldDirectivePrice(parent, field, ctx.decimals);
+    const isList = listLevels(field.type) > 0;
+    const inherited = sized?.named?.get(name) ?? (isList ? sized?.all : undefined);
+    const { multiplier, children } = sizing(ctx, field, args, fieldPath, inherited);
+    const count = scale * multiplier;
+    const named = getNamedType(field.type);
+    const unitOf = (p) => (p !== undefined ? parseUnits(p, ctx.decimals) : ctx.defaultFieldUnits);
+    const priced = (unit, rest) => {
+        if (unit === 0n)
+            return { units: rest.units, items: rest.items, truncated: rest.truncated };
+        const items = [{ path: fieldPath, unit, count }];
+        const truncated = addItems(items, rest.items) || rest.truncated;
+        return { units: unit * count + rest.units, items, truncated };
+    };
+    const sets = nodes.flatMap((n) => (n.selectionSet ? [n.selectionSet] : []));
+    if (sets.length === 0)
+        return priced(unitOf(fieldOwn), ZERO);
+    // Abstract return types: price every possible runtime type and charge the most expensive.
+    // Without a field price, the runtime type's @price applies (or its interfaces', or the return type's).
+    const abstractPrice = isAbstractType(named) ? directivePrice(named) : undefined;
+    let best;
+    for (const t of runtimeTypes(ctx, named)) {
+        const own = fieldOwn ?? typePrice(t, ctx.decimals) ?? abstractPrice;
+        const c = priced(unitOf(own), setCostOn(ctx, t, sets, fieldPath, count, children, depth + 1));
+        if (!best || c.units > best.units)
+            best = c;
+    }
+    return best ?? priced(unitOf(fieldOwn), ZERO);
+}
+/** Selects the operation the request will execute, following GraphQL's rules. */
+export function selectOperation(document, operationName) {
+    const ops = document.definitions.filter((d) => d.kind === Kind.OPERATION_DEFINITION);
+    if (operationName) {
+        const matches = ops.filter((o) => o.name?.value === operationName);
+        if (matches.length !== 1) {
+            throw new PricingError(matches.length === 0 ? `Unknown operation "${operationName}"` : `Several operations are named "${operationName}"`, 'UNKNOWN_OPERATION');
+        }
+        return matches[0];
+    }
+    if (ops.length !== 1) {
+        throw new PricingError('Must provide operationName when the document has several operations', 'UNKNOWN_OPERATION');
+    }
+    return ops[0];
+}
+const shortPath = (p) => (p.length > MAX_PATH_LENGTH ? `…${p.slice(-(MAX_PATH_LENGTH - 1))}` : p);
+/**
+ * Computes the price of the operation a GraphQL request will run. Pure and deterministic:
+ * the same schema, document and variables always give the same price.
+ */
+export function priceOperation(input, options = {}) {
+    const decimals = options.decimals ?? 6;
+    const defaultFieldUnits = parseUnits(options.defaultFieldPrice ?? '0', decimals);
+    if (!options.fieldPrice && defaultFieldUnits === 0n && !schemaHasPrices(input.schema)) {
+        // Fail closed: a schema whose directives were lost (introspection copy, code-first without
+        // extensions) would otherwise make every operation free.
+        throw new PricingError('The schema has no @price anywhere; add fareDirectiveTypeDefs and @price, or pass fieldPrice', 'NO_PRICES');
+    }
+    const op = selectOperation(input.document, input.operationName);
+    const fragments = {};
+    for (const d of input.document.definitions)
+        if (d.kind === Kind.FRAGMENT_DEFINITION)
+            fragments[d.name.value] = d;
+    const root = op.operation === 'query'
+        ? input.schema.getQueryType()
+        : op.operation === 'mutation'
+            ? input.schema.getMutationType()
+            : input.schema.getSubscriptionType();
+    if (!root)
+        throw new PricingError(`Schema has no ${op.operation} type`, 'UNKNOWN_OPERATION');
+    const ctx = {
+        schema: input.schema,
+        fragments,
+        variables: coerceVariables(input.schema, op, input.variables ?? {}),
+        decimals,
+        defaultFieldUnits,
+        listArgs: options.listSizeArguments ?? DEFAULT_LIST_ARGS,
+        defaultListSize: BigInt(options.defaultListSize ?? 10),
+        maxListSize: BigInt(options.maxListSize ?? 100),
+        connections: options.connections === false ? undefined : (options.connections ?? {}),
+        fieldPrice: options.fieldPrice,
+        visits: 0,
+        maxVisits: options.maxFieldVisits ?? 10_000,
+        maxDepth: options.maxDepth ?? 100,
+    };
+    let cost;
+    try {
+        cost = setCostOn(ctx, root, [op.selectionSet], undefined, 1n, undefined, 0);
+    }
+    catch (error) {
+        if (error instanceof RangeError)
+            throw new PricingError('Operation is too complex to price', 'TOO_COMPLEX');
+        throw error;
+    }
+    const amount = formatUnits(cost.units, decimals);
+    if (options.maxPrice !== undefined && cost.units > parseUnits(options.maxPrice, decimals)) {
+        throw new PriceLimitError(amount, options.maxPrice);
+    }
+    const price = {
+        amount,
+        units: cost.units,
+        decimals,
+        breakdown: cost.items.map((i) => ({
+            path: shortPath(pathArray(i.path).join('.')),
+            unitAmount: formatUnits(i.unit, decimals),
+            count: i.count.toString(),
+            amount: formatUnits(i.unit * i.count, decimals),
+        })),
+    };
+    if (cost.truncated)
+        price.breakdownTruncated = true;
+    return price;
+}

package/dist/yoga.d.ts

@@ -0,0 +1,26 @@
+import { type GraphQLSchema } from 'graphql';
+import type { Plugin } from 'graphql-yoga';
+import { type DocumentLimits, type FareOptions } from './core.js';
+export type UseFareqlOptions = FareOptions & Pick<DocumentLimits, 'maxQueryLength' | 'maxTokens'> & {
+    /** Schema to price against. Default: the schema the operation executes on. */
+    schema?: GraphQLSchema;
+    /**
+     * The HTTP request a payment belongs to. Default: `context.request`, which Yoga sets for HTTP.
+     * Operations that reach execution without one (graphql-ws, `yoga.getEnveloped()`) are refused
+     * when priced, unless this returns a Request (e.g. built from `connectionParams`).
+     */
+    getRequest?: (context: Record<string, unknown>) => Request | undefined;
+    /** Events one payment buys on a priced subscription; the stream then ends. Default: 100. */
+    maxSubscriptionEvents?: number;
+};
+/**
+ * GraphQL Yoga plugin. It charges right before execution, after Yoga and every other plugin have
+ * parsed, validated and restored the document (APQ, persisted operations, depth limits…), so
+ * what is priced is exactly what runs, and nobody pays for an operation a later check rejects.
+ * A backstop before the response is sent charges results that skipped execution (response
+ * caches, other plugins' shortcuts), so a cached priced result is never served unpaid.
+ *
+ * Priced operations answer with the MPP Challenge status (402) and `WWW-Authenticate` header
+ * until the client retries with a valid Credential; the paid response carries `Payment-Receipt`.
+ */
+export declare function useFareql(options: UseFareqlOptions): Plugin;