@substrio/sdk 0.0.0-stage → 0.1.1

package/substrio_operation_client.mjs

@@ -0,0 +1,196 @@
+/**
+ * Substrio SDK: every registry operation as a typed method, grouped by the
+ * words of its dotted name the way the CLI groups them: kv.get is
+ * client.ops.kv.get(input), account.key.create is
+ * client.ops.account.key.create(input).
+ *
+ * What an operation is (its routes, path and query parameters, whether it
+ * takes a JSON body) comes only from substrio_operations.mjs, which
+ * scripts/gen_operations.mjs generates from the server's catalog
+ * (GET /v1/_openapi, projected from src/substrio/core/substrio_operation_registry.h).
+ * Nothing here knows one operation from another. Types for every input,
+ * result and the error envelope are in substrio_operations.d.mts.
+ *
+ * An input is one object: each {placeholder} of the route takes its field,
+ * declared query parameters go in the query string, and the rest is the
+ * query string (GET, HEAD, DELETE) or the JSON body. A route whose body is
+ * one input property's value (bodyProperty, such as kv.set's entries) sends
+ * that value as the body. A non-object input is the body as it is.
+ */
+
+import { OPERATIONS } from './substrio_operations.mjs';
+
+// Methods whose remaining inputs travel in the query string.
+const QUERY_METHODS = new Set(['GET', 'HEAD', 'DELETE']);
+
+const isObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+const text = (value) => (typeof value === 'string' ? value : JSON.stringify(value));
+const absent = (value) => value === undefined || value === null;
+
+/** The {placeholders} of a route path, in order (pure). */
+export function routeParams(path) {
+    return [...path.matchAll(/\{([^}]+)\}/g)].map((m) => m[1]);
+}
+
+/**
+ * One route of the server's catalog (GET /v1/_openapi) as this module calls
+ * it (pure): `op` is paths[path][method]. {method, path, params, query,
+ * parameters, body, bodyProperty, bodySchema}: `body` is true when the route
+ * takes a JSON body, and `bodyProperty` names the input property whose value
+ * is that whole body (x-substrio-body-property), else null.
+ */
+export function catalogRoute(path, method, op) {
+    const parameters = Array.isArray(op?.parameters) ? op.parameters : [];
+    const bodySchema = op?.requestBody?.content?.['application/json']?.schema ?? null;
+    return {
+        method: method.toUpperCase(),
+        path,
+        params: routeParams(path),
+        query: parameters.filter((p) => p.in === 'query').map((p) => p.name),
+        parameters,
+        body: bodySchema !== null,
+        bodyProperty: op?.['x-substrio-body-property'] ?? null,
+        bodySchema,
+    };
+}
+
+/**
+ * The route of an operation to call with `input` (pure): among its routes
+ * (those with `method`, when given) whose path parameters the input fills,
+ * the one that carries a JSON body (any field fits there), else the first
+ * that fits, else the first (its error names what is missing).
+ */
+export function pickRoute(operation, input, method = null) {
+    const candidates = method ? operation.routes.filter((r) => r.method === method) : operation.routes;
+    if (candidates.length === 0) {
+        throw new TypeError(`${operation.name} has no ${method} route (it has ${[...new Set(operation.routes.map((r) => r.method))].join(', ')})`);
+    }
+    const fitting = candidates.filter((r) => r.params.every((p) => isObject(input) && !absent(input[p])));
+    return fitting.find((r) => r.body) || fitting[0] || candidates[0];
+}
+
+/**
+ * The request for one route and an input (pure): {method, path, body}.
+ * Throws when a path parameter is missing. With `rawBody` the caller sends the
+ * body itself as raw bytes (data.import's NDJSON, file.upload): the route's
+ * JSON body field is neither required nor built.
+ */
+export function buildRequest(route, input, { rawBody = false } = {}) {
+    const rest = isObject(input) ? { ...input } : {};
+    const missing = route.params.filter((p) => absent(rest[p]));
+    if (missing.length) throw new TypeError(`missing ${missing.join(', ')} (the route is ${route.method} ${route.path})`);
+    const path = route.path.replace(/\{([^}]+)\}/g, (_, name) => {
+        const value = rest[name];
+        delete rest[name];
+        return encodeURIComponent(text(value));
+    });
+    const query = new URLSearchParams();
+    for (const name of route.query) {
+        if (!absent(rest[name])) query.append(name, text(rest[name]));
+        delete rest[name];
+    }
+    let body;
+    if (rawBody) {
+        body = undefined;
+    } else if (route.bodyProperty) {
+        if (absent(rest[route.bodyProperty])) {
+            throw new TypeError(`missing ${route.bodyProperty} (the body of ${route.method} ${route.path})`);
+        }
+        body = rest[route.bodyProperty];
+    } else if (QUERY_METHODS.has(route.method)) {
+        if (input !== undefined && !isObject(input)) {
+            throw new TypeError(`${route.method} ${route.path} takes named fields, not a bare JSON value`);
+        }
+        for (const [key, value] of Object.entries(rest)) if (!absent(value)) query.append(key, text(value));
+    } else {
+        body = isObject(input) ? rest : (input === undefined ? {} : input);
+    }
+    const qs = query.toString();
+    return { method: route.method, path: qs ? `${path}?${qs}` : path, body };
+}
+
+/** Calls `operation` over `http` (the SDK's Http: req(method, path, body)). */
+export function callOperation(http, operation, input, options = {}) {
+    const request = buildRequest(pickRoute(operation, input, options.method ?? null), input);
+    return http.req(request.method, request.path, request.body);
+}
+
+/**
+ * The operation tree for `http`: one method per operation at the path of
+ * its name's words. A name that is also the prefix of others (function.logs,
+ * function.logs.clear) is a method that carries its children.
+ */
+export function bindOperations(http) {
+    const root = {};
+    for (const operation of OPERATIONS) {
+        const words = operation.words;
+        let node = root;
+        for (const word of words.slice(0, -1)) node = node[word] ??= {};
+        const last = words[words.length - 1];
+        const call = (input, options) => callOperation(http, operation, input, options);
+        Object.defineProperty(call, 'name', { value: operation.name });
+        Object.defineProperty(call, 'operation', { value: operation });
+        // Children bound before their parent move onto the parent's method.
+        node[last] = Object.assign(call, node[last]);
+    }
+    return deepFreeze(root);
+}
+
+function deepFreeze(node) {
+    for (const child of Object.values(node)) deepFreeze(child);
+    return Object.freeze(node);
+}
+
+/**
+ * Makes each operation group reachable on `client` by its name (client.kv.get)
+ * next to client.ops. A group whose name the client already uses keeps the
+ * client's member; that member takes the group's operations whose names it
+ * does not have (a method gets its own bound copy), non-enumerable, so
+ * nothing the client already offered changes.
+ */
+export function attachOperations(client, ops) {
+    for (const [group, node] of Object.entries(ops)) {
+        if (!(group in client)) {
+            Object.defineProperty(client, group, { value: node, enumerable: false });
+            continue;
+        }
+        const descriptor = findDescriptor(client, group);
+        if (typeof descriptor?.value === 'function') {
+            const method = descriptor.value.bind(client);
+            addMissing(method, node);
+            Object.defineProperty(client, group, { value: method, enumerable: false, writable: true, configurable: true });
+        } else if (descriptor?.get) {
+            // A getter's object is made when first read: it takes the group then.
+            const read = descriptor.get;
+            const merged = new WeakSet();
+            Object.defineProperty(client, group, {
+                enumerable: false,
+                configurable: true,
+                get() {
+                    const value = read.call(this);
+                    if (value !== null && typeof value === 'object' && !merged.has(value)) {
+                        addMissing(value, node);
+                        merged.add(value);
+                    }
+                    return value;
+                },
+            });
+        } else if (descriptor && descriptor.value !== null && typeof descriptor.value === 'object') {
+            addMissing(descriptor.value, node);
+        }
+    }
+}
+
+function findDescriptor(object, name) {
+    for (let o = object; o; o = Object.getPrototypeOf(o)) {
+        const d = Object.getOwnPropertyDescriptor(o, name);
+        if (d) return d;
+    }
+    return undefined;
+}
+
+function addMissing(target, node) {
+    for (const [word, child] of Object.entries(node)) {
+        if (!(word in target)) Object.defineProperty(target, word, { value: child, enumerable: false });
+    }
+}