@atom-forge/rpc 0.3.2

package/dist/client/create-client.js

@@ -0,0 +1,277 @@
+import { Packr } from "msgpackr";
+import { RPC_ERROR_KEY } from "../util/constants.js";
+import { pipeline } from "../util/pipeline.js";
+import { ClientContext } from "./client-context.js";
+import { RpcResponse } from "./rpc-response.js";
+import { camelToKebabCase } from "../util/string.js";
+const rpcMethods = ["$command", "$query", "$get"];
+const rpcMethodTypeMap = {
+    $command: "command",
+    $query: "query",
+    $get: "get",
+};
+const packr = new Packr({ structuredClone: true, useRecords: true });
+/**
+ * Creates an API client and a corresponding middleware configuration object.
+ *
+ * @template T
+ * @param {string} [baseUrl='/api'] - The base URL for the API client.
+ * @returns {[ApiClientDefinition<T>, MiddlewareConfig<T>]} A tuple containing the API client and the middleware config object.
+ */
+export function createClient(baseUrl = "/api") {
+    const middlewareMap = new Map();
+    function createSetterProxy(path) {
+        const handler = {
+            get(_, prop) {
+                return createSetterProxy([...path, prop]);
+            },
+            set(_, prop, value) {
+                const keyPath = prop === "$" ? path : [...path, prop];
+                const key = keyPath.map(camelToKebabCase).join(".");
+                const existing = middlewareMap.get(key) || [];
+                const newMiddlewares = Array.isArray(value) ? value : [value];
+                middlewareMap.set(key, [...existing, ...newMiddlewares]);
+                return true;
+            },
+        };
+        return new Proxy({}, handler);
+    }
+    function createRecursiveProxy(pathSegments = []) {
+        return new Proxy({}, {
+            get(_target, prop) {
+                if (typeof prop !== "string")
+                    return undefined;
+                const isResultRequested = rpcMethods.includes(prop);
+                if (isResultRequested) {
+                    const rpcType = rpcMethodTypeMap[prop];
+                    return async (args, options = {}) => {
+                        const ctx = new ClientContext(pathSegments, args, rpcType, options);
+                        const middlewares = [];
+                        if (middlewareMap.has(""))
+                            middlewares.push(...middlewareMap.get(""));
+                        for (let i = 1; i <= ctx.path.length; i++) {
+                            const key = ctx.path.slice(0, i).map(camelToKebabCase).join(".");
+                            if (middlewareMap.has(key))
+                                middlewares.push(...middlewareMap.get(key));
+                        }
+                        await pipeline(ctx, ...middlewares, async (ctx) => {
+                            let result = await call(baseUrl, ctx);
+                            ctx.result = result;
+                            return result;
+                        });
+                        const rpcResponse = ctx.result;
+                        rpcResponse._attachCtx(ctx);
+                        return rpcResponse;
+                    };
+                }
+                return createRecursiveProxy([...pathSegments, prop]);
+            },
+        });
+    }
+    const api = createRecursiveProxy();
+    const cfg = createSetterProxy([]);
+    return [api, cfg];
+}
+async function call(baseUrl, ctx) {
+    const args = ctx.args;
+    const uploads = new Map();
+    const isGet = ctx.rpcType === "get";
+    const isQuery = ctx.rpcType === "query";
+    const isCommand = ctx.rpcType === "command";
+    if (isCommand) {
+        args.forEach((value, key) => {
+            if (value instanceof File ||
+                (Array.isArray(value) && value.length > 0 && value.every((v) => v instanceof File))) {
+                uploads.set(key, value);
+                args.delete(key);
+            }
+        });
+    }
+    const hasUploads = !!uploads.size;
+    const pathString = ctx.path.map(camelToKebabCase).join(".");
+    const url = typeof window !== "undefined" && typeof window.document !== "undefined"
+        ? new URL(`${baseUrl}/${pathString}`, window ? window.location.origin : undefined)
+        : new URL(`${baseUrl}/${pathString}`);
+    const onProgress = ctx.onProgress;
+    const hasProgress = !!onProgress;
+    const signal = ctx.abortSignal;
+    const headers = ctx.request.headers;
+    const requestType = isGet
+        ? "GET"
+        : isQuery
+            ? "QUERY"
+            : hasUploads
+                ? "UPLOAD"
+                : "COMMAND";
+    const method = isCommand ? "POST" : "GET";
+    let body = null;
+    switch (requestType) {
+        case "GET":
+            args.forEach((value, key) => value !== undefined &&
+                value !== null &&
+                url.searchParams.set(key, String(value)));
+            break;
+        case "QUERY":
+            if (args.size > 0)
+                url.searchParams.set("args", encodeToBase64Url(new Uint8Array(packr.pack(Object.fromEntries(args)))));
+            break;
+        case "UPLOAD":
+            body = new FormData();
+            if (args.size > 0) {
+                const argsObj = Object.fromEntries(args);
+                body.append("args", new Blob([new Uint8Array(packr.pack(argsObj))], {
+                    type: "application/msgpack",
+                }));
+            }
+            for (let key of uploads.keys()) {
+                const file = uploads.get(key);
+                if (Array.isArray(file)) {
+                    for (const f of file) {
+                        body.append(key.endsWith("[]") ? key : `${key}[]`, f, f.name);
+                    }
+                }
+                else if (file) {
+                    body.append(key, file, file.name);
+                }
+            }
+            break;
+        case "COMMAND":
+            body = new Uint8Array(packr.pack(Object.fromEntries(args)));
+            headers.set("Content-Type", "application/msgpack");
+            break;
+    }
+    let response;
+    try {
+        response = hasProgress
+            ? await fetchWithXhr(url, method, body, headers, onProgress, signal)
+            : await fetch(url, {
+                method,
+                headers,
+                body,
+                signal,
+                credentials: "include",
+                window: null,
+            });
+    }
+    catch (e) {
+        return RpcResponse.error("NETWORK_ERROR", { message: e.message });
+    }
+    ctx._response = response;
+    const buffer = await response.arrayBuffer();
+    if (buffer.byteLength === 0) {
+        if (response.ok)
+            return RpcResponse.ok(null);
+        return RpcResponse.error(`HTTP:${response.status}`, null);
+    }
+    let unpacked;
+    try {
+        unpacked = packr.unpack(new Uint8Array(buffer));
+    }
+    catch {
+        try {
+            unpacked = JSON.parse(new TextDecoder().decode(buffer));
+        }
+        catch {
+            unpacked = null;
+        }
+    }
+    const errorCode = unpacked?.[RPC_ERROR_KEY];
+    if (errorCode) {
+        const { [RPC_ERROR_KEY]: _, ...rest } = unpacked;
+        return RpcResponse.error(errorCode, rest);
+    }
+    if (!response.ok) {
+        return RpcResponse.error(`HTTP:${response.status}`, unpacked);
+    }
+    return RpcResponse.ok(unpacked);
+}
+/**
+ * Fetch with XMLHttpRequest for progress tracking and AbortSignal support
+ */
+function fetchWithXhr(url, method, body, headers, onProgress, signal) {
+    return new Promise((resolve, reject) => {
+        const xhr = new XMLHttpRequest();
+        // 👇 AbortSignal kezelés - ha már megszakított, throw azonnal
+        if (signal?.aborted) {
+            reject(new DOMException("Request aborted", "AbortError"));
+            return;
+        }
+        // 👇 Signal listener - ha megszakítják, abort az XHR-t
+        const abortHandler = () => {
+            xhr.abort();
+            reject(new DOMException("Request aborted", "AbortError"));
+        };
+        signal?.addEventListener("abort", abortHandler);
+        if (onProgress) {
+            if (method === "POST" && body) {
+                xhr.upload.addEventListener("progress", (e) => {
+                    if (e.lengthComputable)
+                        onProgress({
+                            loaded: e.loaded,
+                            total: e.total,
+                            percent: Math.round((e.loaded / e.total) * 100),
+                            phase: "upload",
+                        });
+                });
+            }
+            xhr.addEventListener("progress", (e) => {
+                if (e.lengthComputable)
+                    onProgress({
+                        loaded: e.loaded,
+                        total: e.total,
+                        percent: Math.round((e.loaded / e.total) * 100),
+                        phase: "download",
+                    });
+            });
+        }
+        xhr.addEventListener("load", () => {
+            signal?.removeEventListener("abort", abortHandler);
+            const headers = new Headers();
+            const headerMap = xhr.getAllResponseHeaders();
+            headerMap.trim().split(/[\r\n]+/).forEach(line => {
+                const separatorIndex = line.indexOf(':');
+                if (separatorIndex > 0) {
+                    const key = line.substring(0, separatorIndex).trim();
+                    const value = line.substring(separatorIndex + 1).trim();
+                    headers.append(key, value);
+                }
+            });
+            resolve(new Response(xhr.response, {
+                status: xhr.status,
+                statusText: xhr.statusText,
+                headers,
+            }));
+        });
+        xhr.addEventListener("error", () => {
+            signal?.removeEventListener("abort", abortHandler);
+            reject(new Error("Network error"));
+        });
+        xhr.addEventListener("abort", () => {
+            signal?.removeEventListener("abort", abortHandler);
+            reject(new DOMException("Request aborted", "AbortError"));
+        });
+        xhr.open(method, url);
+        headers.forEach((value, key) => {
+            xhr.setRequestHeader(key, value);
+        });
+        xhr.responseType = "arraybuffer";
+        xhr.send(body);
+    });
+}
+/**
+ * Encodes the given binary data into a Base64 URL-safe string.
+ *
+ * This method converts the provided binary data into a standard Base64 string,
+ * then makes it URL-safe by replacing `+` with `-`, `/` with `_`, and removing
+ * any padding characters (`=`) from the end.
+ *
+ * @param {Uint8Array} data - The input binary data to be encoded as a Base64 URL-safe string.
+ * @return {string} The Base64 URL-safe encoded string representation of the input data.
+ */
+function encodeToBase64Url(data) {
+    const binStr = Array.from(data)
+        .map((b) => String.fromCharCode(b))
+        .join("");
+    const base64 = btoa(binStr);
+    return base64.replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}

package/dist/client/logger.d.ts

@@ -0,0 +1,6 @@
+import type { ClientMiddleware } from "./types.js";
+/**
+ * A client middleware that logs RPC call details to the browser console.
+ * Logs the request path, arguments, response, timing, and HTTP status.
+ */
+export declare function clientLogger(baseUrl?: string): ClientMiddleware;

package/dist/client/logger.js

@@ -0,0 +1,41 @@
+import { camelToKebabCase } from "../util/string.js";
+/**
+ * A client middleware that logs RPC call details to the browser console.
+ * Logs the request path, arguments, response, timing, and HTTP status.
+ */
+export function clientLogger(baseUrl = "/api") {
+    return async (ctx, next) => {
+        console.groupCollapsed(`🔆 %c${baseUrl}/%c${ctx.path.map(camelToKebabCase).join(".")}`, "font-weight:200; color:gray", "font-weight:800;");
+        console.log("ARG:", ctx.getArgs());
+        try {
+            await next();
+        }
+        catch (e) {
+            console.log("PIPELINE ERR:", e);
+            console.groupEnd();
+            throw e;
+        }
+        const duration = ctx.elapsedTime.toFixed(2);
+        console.log("RES:", ctx.result);
+        if (ctx.response) {
+            console.log(`%c${duration} %cms / %c${parseFloat(ctx.response.headers.get("x-atom-forge-rpc-exec-time") || "0").toFixed(2)} %cms`, "font-weight:800;", "font-weight:200;", "font-weight:800;", "font-weight:200;");
+            console.groupEnd();
+            let color;
+            if (ctx.response.status < 200)
+                color = "#3498db";
+            else if (ctx.response.status < 300)
+                color = "#2ecc71";
+            else if (ctx.response.status < 400)
+                color = "#f1c40f";
+            else if (ctx.response.status < 500)
+                color = "#e74c3c";
+            else
+                color = "#9b59b6";
+            console.log(`️ ↘ %c${ctx.response.status} %c${ctx.response.statusText}`, `font-weight:800; color: ${color}`, `font-weight:200; color: ${color}`);
+        }
+        else {
+            console.log(`%c${duration} %cms %c(no response object)`, "font-weight:800;", "font-weight:200; color:gray");
+            console.groupEnd();
+        }
+    };
+}

package/dist/client/middleware.d.ts

@@ -0,0 +1,6 @@
+import type { ClientMiddleware } from "./types.js";
+/**
+ * Creates a ClientMiddleware function.
+ * @param middleware
+ */
+export declare function makeClientMiddleware(middleware: ClientMiddleware): ClientMiddleware;

package/dist/client/middleware.js

@@ -0,0 +1,7 @@
+/**
+ * Creates a ClientMiddleware function.
+ * @param middleware
+ */
+export function makeClientMiddleware(middleware) {
+    return middleware;
+}

package/dist/client/rpc-response.d.ts

@@ -0,0 +1,27 @@
+import { RPC_ERROR_KEY } from "../util/constants.js";
+import type { ClientContext } from "./client-context.js";
+export { RPC_ERROR_KEY };
+type RpcErrorKey = typeof RPC_ERROR_KEY;
+type RpcErrorObject = {
+    [K in RpcErrorKey]: string;
+};
+export declare class RpcResponse<TSuccess, TError extends RpcErrorObject = never> {
+    private readonly _status;
+    private readonly _result;
+    private _ctx?;
+    constructor(status: string, result: TSuccess | Omit<TError, RpcErrorKey>);
+    isOK(): this is RpcResponse<TSuccess, never>;
+    isError<TCode extends string>(code?: TCode): this is RpcResponse<never, Extract<TError, {
+        [K in RpcErrorKey]: TCode;
+    }>>;
+    getStatus(): string;
+    get status(): string;
+    getResult(): TSuccess | Omit<TError, RpcErrorKey>;
+    get result(): TSuccess | Omit<TError, RpcErrorKey>;
+    getCtx(): ClientContext;
+    get ctx(): ClientContext;
+    /** @internal */
+    _attachCtx(ctx: ClientContext): void;
+    static ok<T>(result: T): RpcResponse<T, never>;
+    static error(code: string, result: unknown): RpcResponse<any, any>;
+}

package/dist/client/rpc-response.js

@@ -0,0 +1,46 @@
+import { RPC_ERROR_KEY } from "../util/constants.js";
+export { RPC_ERROR_KEY };
+export class RpcResponse {
+    constructor(status, result) {
+        this._status = status;
+        this._result = result;
+    }
+    isOK() {
+        return this._status === "OK";
+    }
+    isError(code) {
+        if (code !== undefined)
+            return this._status === code;
+        return this._status !== "OK";
+    }
+    getStatus() {
+        return this._status;
+    }
+    get status() {
+        return this._status;
+    }
+    getResult() {
+        return this._result;
+    }
+    get result() {
+        return this._result;
+    }
+    getCtx() {
+        if (!this._ctx)
+            throw new Error("ClientContext is not available on this RpcResponse");
+        return this._ctx;
+    }
+    get ctx() {
+        return this.getCtx();
+    }
+    /** @internal */
+    _attachCtx(ctx) {
+        this._ctx = ctx;
+    }
+    static ok(result) {
+        return new RpcResponse("OK", result);
+    }
+    static error(code, result) {
+        return new RpcResponse(code, result);
+    }
+}

package/dist/client/types.d.ts

@@ -0,0 +1,151 @@
+import { z } from "zod";
+import type { Middleware } from "../util/pipeline.js";
+import type { UnwrappedPromise } from "../util/types.js";
+import type { ClientContext } from "./client-context.js";
+import { RPC_ERROR_KEY } from "../util/constants.js";
+import type { RpcResponse } from "./rpc-response.js";
+export type { RpcResponse };
+type RpcErrorKey = typeof RPC_ERROR_KEY;
+type RpcErrorShape = {
+    [K in RpcErrorKey]: string;
+};
+type ExtractSuccess<R> = R extends RpcErrorShape ? never : R;
+type ExtractErrors<R> = R extends RpcErrorShape ? R : never;
+/**
+ * Represents a middleware function that operates on the client context during
+ * the execution cycle. This middleware type is used to manipulate or process
+ * the client context or the result during the middleware chain.
+ * @internal
+ */
+export type ClientMiddleware<RET = any> = Middleware<ClientContext, RET>;
+/**
+ * A callback type representing a handler for monitoring the progress of a data transfer operation.
+ *
+ * This type is used to track the progress of an upload or download process by providing
+ * periodic updates about the amount of data transferred, the total data size, the percentage
+ * completed, and the current phase of the operation (upload or download).
+ *
+ * @callback OnProgress
+ * @param {Object} progress - The progress information of the operation.
+ * @param {number} progress.loaded - The amount of data that has been transferred so far.
+ * @param {number} progress.total - The total size of the data to be transferred.
+ * @param {number} progress.percent - The percentage of the data transfer that has been completed.
+ * @param {'upload' | 'download'} progress.phase - The current phase of the data transfer operation, either "upload" or "download".
+ * @internal
+ */
+export type OnProgress = (progress: {
+    loaded: number;
+    total: number;
+    percent: number;
+    phase: "upload" | "download";
+}) => void;
+/**
+ * Represents options that can be used to customize the behavior of a call or request.
+ * @internal
+ */
+export type CallOptions = {
+    /**
+     * A callback function that gets invoked to report the progress of an ongoing operation.
+     *
+     * This optional property can be used to track and handle progress updates during a process.
+     * The function typically receives information related to the current state or percentage
+     * of completion of the operation.
+     */
+    onProgress?: OnProgress;
+    /**
+     * An optional AbortSignal object that allows you to communicate with, or to monitor, a cancellation or abort request.
+     * Can be used to terminate an ongoing operation if the associated signal is triggered.
+     */
+    abortSignal?: AbortSignal;
+    /**
+     * Optional `headers` parameter that represents the HTTP headers
+     * to be sent with the request. It can include custom headers
+     * and standard headers to define how the request should be processed.
+     */
+    headers?: Headers;
+};
+/** A type that can be either a single middleware or an array of them. */
+type MiddlewareAssignable = ClientMiddleware | ClientMiddleware[];
+/**
+ * This type recursively transforms the structure of ApiClientDefinition<T>
+ * into the structure needed for the middleware configuration.
+ * Each branch node (group) will have a '$' property for its own middlewares,
+ * and each leaf node (endpoint) will be directly assignable.
+ */
+type MiddlewareConfigFromApi<T> = {
+    [K in keyof T]: T[K] extends {
+        $command: any;
+    } | {
+        $query: any;
+    } | {
+        $get: any;
+    } ? MiddlewareAssignable : T[K] extends object ? {
+        $?: MiddlewareAssignable;
+    } & MiddlewareConfigFromApi<T[K]> : never;
+};
+/**
+ * The main middleware configuration type. It combines the global '$' with this transformed structure.
+ * @internal
+ */
+export type MiddlewareConfig<T> = {
+    $?: MiddlewareAssignable;
+} & MiddlewareConfigFromApi<ApiClientDefinition<T>>;
+/**
+ * Base interface for all RPC method descriptors.
+ * @internal
+ */
+export interface RpcMethodDescriptor {
+    rpcType: "query" | "command" | "get";
+    zodSchema?: z.ZodSchema<any>;
+}
+/**
+ *The properties are transformed to the target type, or to `never` if they need to be filtered out.
+ */
+type MappedApi<T> = {
+    [K in keyof T]: T[K] extends RpcMethodDescriptor ? CallableRpcMethod<GetArgs<T[K]>, GetSuccessRet<T[K]>, GetErrorRet<T[K]>, GetRpcType<T[K]>> : T[K] extends object ? T[K] extends Function | RpcMethodDescriptor ? never : keyof ApiClientDefinition<T[K]> extends never ? never : ApiClientDefinition<T[K]> : never;
+};
+/**
+ * We collect the keys whose values are not `never`.
+ */
+type FilteredKeys<T> = {
+    [K in keyof T]: T[K] extends never ? never : K;
+}[keyof T];
+/**
+ * The final type only contains filtered and transformed properties.
+ * @internal
+ */
+export type ApiClientDefinition<T> = Pick<MappedApi<T>, FilteredKeys<MappedApi<T>>>;
+/**
+ *Extract the ARGS type from the zod schema or the implementation function.
+ */
+type GetArgs<T> = T extends {
+    zodSchema: z.ZodSchema<infer ZodArgs>;
+} ? ZodArgs : T extends {
+    implementation: (args: infer ARGS) => any;
+} ? ARGS : never;
+/**
+ *  Extract the success return type (non-error returns).
+ */
+type GetSuccessRet<T> = T extends {
+    implementation: (args: any) => infer R;
+} ? ExtractSuccess<UnwrappedPromise<R>> : never;
+/**
+ *  Extract the error return type (rpc error objects).
+ */
+type GetErrorRet<T> = T extends {
+    implementation: (args: any) => infer R;
+} ? ExtractErrors<UnwrappedPromise<R>> : never;
+/**
+ *  Extract the RPC type ('query', 'command', 'get').
+ */
+type GetRpcType<T> = T extends RpcMethodDescriptor ? T["rpcType"] : never;
+/**
+ *  Describes the callable method that the proxy returns.
+ */
+type CallableRpcMethod<ARGS, TSuccess, TError extends RpcErrorShape, Type extends "query" | "command" | "get"> = Type extends "command" ? {
+    $command: (args: ARGS, options?: CallOptions) => Promise<RpcResponse<TSuccess, TError>>;
+} : Type extends "query" ? {
+    $query: (args: ARGS, options?: CallOptions) => Promise<RpcResponse<TSuccess, TError>>;
+} : Type extends "get" ? {
+    $get: (args: ARGS, options?: CallOptions) => Promise<RpcResponse<TSuccess, TError>>;
+} : never;

package/dist/client/types.js

@@ -0,0 +1 @@
+export {};

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { createClient } from "./client/create-client.js";
+export { makeClientMiddleware } from "./client/middleware.js";
+export { clientLogger } from "./client/logger.js";
+export { RpcResponse } from "./client/rpc-response.js";
+export { createCoreHandler, flattenApiDefinition } from "./server/create-handler.js";
+export { makeServerMiddleware } from "./server/middleware.js";
+export { rpcFactory, rpc } from "./server/rpc.js";

package/dist/index.js

@@ -0,0 +1,7 @@
+export { createClient } from "./client/create-client.js";
+export { makeClientMiddleware } from "./client/middleware.js";
+export { clientLogger } from "./client/logger.js";
+export { RpcResponse } from "./client/rpc-response.js";
+export { createCoreHandler, flattenApiDefinition } from "./server/create-handler.js";
+export { makeServerMiddleware } from "./server/middleware.js";
+export { rpcFactory, rpc } from "./server/rpc.js";

package/dist/server/create-handler.d.ts

@@ -0,0 +1,18 @@
+import { ServerContext } from "./server-context.js";
+import type { ApiDefinition } from "./types.js";
+export declare function flattenApiDefinition(apiDefinition: ApiDefinition<any>): Map<string, {
+    rpcType: string;
+    handler: (ctx: ServerContext<any>) => Promise<any>;
+}>;
+/**
+ * Creates a framework-agnostic handler function for processing RPC requests.
+ *
+ * @param endpointMap - The flattened API endpoint map produced by `flattenApiDefinition`.
+ * @param options
+ * @return An async function that accepts a standard `Request`, route info, and an optional adapter context.
+ */
+export declare function createCoreHandler<TAdapter = unknown>(endpointMap: ReturnType<typeof flattenApiDefinition>, options?: {
+    createServerContext?: (args: any, request: Request, adapterContext: TAdapter) => ServerContext<TAdapter>;
+}): (request: Request, routeInfo: {
+    path: string;
+}, adapterContext?: TAdapter) => Promise<Response>;