npm - skir-client - Versions diffs - 0.1.0 → 1.0.0 - Mend

skir-client 0.1.0 → 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (10) hide show

package/dist/cjs/skir-client.d.ts +302 -22
package/dist/cjs/skir-client.d.ts.map +1 -1
package/dist/cjs/skir-client.js +184 -84
package/dist/cjs/skir-client.js.map +1 -1
package/dist/esm/skir-client.d.ts +302 -22
package/dist/esm/skir-client.d.ts.map +1 -1
package/dist/esm/skir-client.js +182 -82
package/dist/esm/skir-client.js.map +1 -1
package/package.json +1 -1
package/src/skir-client.ts +468 -121

package/dist/cjs/skir-client.js CHANGED Viewed

@@ -9,7 +9,7 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
     });
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports._initModuleClasses = exports.installServiceOnExpressApp = exports.Service = exports.RawResponse = exports.ServiceClient = exports._EnumBase = exports._FrozenBase = exports._toFrozenArray = exports._EMPTY_ARRAY = exports.parseTypeDescriptorFromJsonCode = exports.parseTypeDescriptorFromJson = exports.optionalSerializer = exports.arraySerializer = exports.primitiveSerializer = exports.ByteString = exports.Timestamp = void 0;
+exports._initModuleClasses = exports.installServiceOnExpressApp = exports.Service = exports.ServiceError = exports.ServiceClient = exports._EnumBase = exports._FrozenBase = exports._toFrozenArray = exports._EMPTY_ARRAY = exports.parseTypeDescriptorFromJsonCode = exports.parseTypeDescriptorFromJson = exports.optionalSerializer = exports.arraySerializer = exports.primitiveSerializer = exports.ByteString = exports.Timestamp = void 0;
 /**
  * A single moment in time represented in a platform-independent format, with a
  * precision of one millisecond.
@@ -1867,7 +1867,6 @@ class ServiceClient {
     /** Invokes the given method on the remote server through an RPC. */
     invokeRemote(method, request, httpMethod = "POST") {
         return __awaiter(this, void 0, void 0, function* () {
-            this.lastRespHeaders = undefined;
             const requestJson = method.requestSerializer.toJsonCode(request);
             const requestBody = [method.name, method.number, "", requestJson].join(":");
             const requestInit = Object.assign({}, (yield Promise.resolve(this.getRequestMetadata(method))));
@@ -1880,7 +1879,6 @@ class ServiceClient {
                 url.search = requestBody.replace(/%/g, "%25");
             }
             const httpResponse = yield fetch(url, requestInit);
-            this.lastRespHeaders = httpResponse.headers;
             const responseData = yield httpResponse.blob();
             if (httpResponse.ok) {
                 const jsonCode = yield responseData.text();
@@ -1895,77 +1893,134 @@ class ServiceClient {
             }
         });
     }
-    get lastResponseHeaders() {
-        return this.lastRespHeaders;
-    }
 }
 exports.ServiceClient = ServiceClient;
-/** Raw response returned by the server. */
-class RawResponse {
-    constructor(data, type) {
-        this.data = data;
-        this.type = type;
-    }
-    get statusCode() {
-        switch (this.type) {
-            case "ok-json":
-            case "ok-html":
-                return 200;
-            case "bad-request":
-                return 400;
-            case "server-error":
-                return 500;
-            default: {
-                const _ = this.type;
-                throw new Error(_);
-            }
-        }
-    }
-    get contentType() {
-        switch (this.type) {
-            case "ok-json":
-                return "application/json";
-            case "ok-html":
-                return "text/html; charset=utf-8";
-            case "bad-request":
-            case "server-error":
-                return "text/plain; charset=utf-8";
-            default: {
-                const _ = this.type;
-                throw new Error(_);
-            }
-        }
-    }
+function makeOkJsonResponse(data) {
+    return {
+        data: data,
+        statusCode: 200,
+        contentType: "application/json",
+    };
+}
+function makeOkHtmlResponse(data) {
+    return {
+        data: data,
+        statusCode: 200,
+        contentType: "text/html; charset=utf-8",
+    };
 }
-exports.RawResponse = RawResponse;
-// Copied from
-//   https://github.com/gepheum/restudio/blob/main/index.jsdeliver.html
-const RESTUDIO_HTML = `<!DOCTYPE html>
+function makeBadRequestResponse(data) {
+    return {
+        data: data,
+        statusCode: 400,
+        contentType: "text/plain; charset=utf-8",
+    };
+}
+function makeServerErrorResponse(data, statusCode = 500) {
+    return {
+        data: data,
+        statusCode: statusCode,
+        contentType: "text/plain; charset=utf-8",
+    };
+}
+function getStudioHtml(studioAppJsUrl) {
+    // Copied from
+    //   https://github.com/gepheum/skir-studio/blob/main/index.jsdeliver.html
+    return `<!DOCTYPE html>
 <html>
   <head>
     <meta charset="utf-8" />
     <title>RESTudio</title>
-    <script src="https://cdn.jsdelivr.net/npm/restudio/dist/restudio-standalone.js"></script>
+    <script src="${studioAppJsUrl}"></script>
   </head>
   <body style="margin: 0; padding: 0;">
     <restudio-app></restudio-app>
   </body>
 </html>
 `;
+}
+/**
+ * If this error is thrown from a method implementation, the specified status
+ * code and message will be returned in the HTTP response.
+ *
+ * If any other type of exception is thrown, the response status code will be
+ * 500 (Internal Server Error).
+ */
+class ServiceError extends Error {
+    constructor(spec) {
+        var _a;
+        super((_a = spec.message) !== null && _a !== void 0 ? _a : spec.desc);
+        this.spec = spec;
+    }
+    toRawResponse() {
+        var _a;
+        return makeServerErrorResponse((_a = this.spec.message) !== null && _a !== void 0 ? _a : this.spec.desc, this.spec.statusCode);
+    }
+}
+exports.ServiceError = ServiceError;
 /**
  * Implementation of a skir service.
  *
  * Usage: call `.addMethod()` to register methods, then install the service on
  * an HTTP server either by:
- *   - calling the `installServiceOnExpressApp()` top-level function  if you are
+ *   - calling the `installServiceOnExpressApp()` top-level function if you are
  *       using ExpressJS
  *   - writing your own implementation of `installServiceOn*()` which calls
  *       `.handleRequest()` if you are using another web application framework
+ *
+ * ## Handling Request Metadata
+ *
+ * The `RequestMeta` type parameter specifies what metadata (authentication,
+ * headers, etc.) your method implementations receive. There are two approaches:
+ *
+ * ### Approach 1: Use the framework's request type directly
+ *
+ * Set `RequestMeta` to your framework's request type (e.g., `ExpressRequest`).
+ * All method implementations will receive the full framework request object.
+ *
+ * ```typescript
+ * const service = new Service<ExpressRequest>();
+ * service.addMethod(myMethod, async (req, expressReq) => {
+ *   const isAdmin = expressReq.user?.role === 'admin';
+ *   // ...
+ * });
+ * installServiceOnExpressApp(app, '/api', service, text, json);
+ * ```
+ *
+ * ### Approach 2: Use a simplified custom type (recommended for testing)
+ *
+ * Set `RequestMeta` to a minimal type containing only what your service needs.
+ * Use `withRequestMeta()` to extract this data from the framework request when
+ * installing the service.
+ *
+ * ```typescript
+ * const service = new Service<{ isAdmin: boolean }>();
+ * service.addMethod(myMethod, async (req, { isAdmin }) => {
+ *   // Implementation is framework-agnostic and easy to unit test
+ *   if (!isAdmin) throw new ServiceError({ statusCode: 403, desc: "Forbidden" });
+ *   // ...
+ * });
+ *
+ * // Adapt to Express when installing
+ * const handler = service.withRequestMeta((req: ExpressRequest) => ({
+ *   isAdmin: req.user?.role === 'admin'
+ * }));
+ * installServiceOnExpressApp(app, '/api', handler, text, json);
+ * ```
+ *
+ * This approach decouples your service from the HTTP framework, making it easier
+ * to test and clearer about what request data it actually uses.
  */
 class Service {
-    constructor() {
+    constructor(options) {
+        var _a, _b, _c;
         this.methodImpls = {};
+        this.options = {
+            keepUnrecognizedValues: (_a = options === null || options === void 0 ? void 0 : options.keepUnrecognizedValues) !== null && _a !== void 0 ? _a : DEFAULT_SERVICE_OPTIONS.keepUnrecognizedValues,
+            canCopyUnknownErrorMessageToResponse: (_b = options === null || options === void 0 ? void 0 : options.canCopyUnknownErrorMessageToResponse) !== null && _b !== void 0 ? _b : DEFAULT_SERVICE_OPTIONS.canCopyUnknownErrorMessageToResponse,
+            studioAppJsUrl: new URL((_c = options === null || options === void 0 ? void 0 : options.studioAppJsUrl) !== null && _c !== void 0 ? _c : DEFAULT_SERVICE_OPTIONS.studioAppJsUrl).toString(),
+        };
     }
     addMethod(method, impl) {
         const { number } = method;
@@ -1978,20 +2033,7 @@ class Service {
         };
         return this;
     }
-    /**
-     * Parses the content of a user request and invokes the appropriate method.
-     * If you are using ExpressJS as your web application framework, you don't
-     * need to call this method, you can simply call the
-     * `installServiceOnExpressApp()` top-level function.
-     *
-     * If the request is a GET request, pass in the decoded query string as the
-     * request's body. The query string is the part of the URL after '?', and it
-     * can be decoded with DecodeURIComponent.
-     *
-     * Pass in "keep-unrecognized-values" if the request cannot come from a
-     * malicious user.
-     */
-    handleRequest(reqBody, reqMeta, resMeta, keepUnrecognizedValues) {
+    handleRequest(reqBody, reqMeta) {
         return __awaiter(this, void 0, void 0, function* () {
             if (reqBody === "" || reqBody === "list") {
                 const json = {
@@ -2004,10 +2046,11 @@ class Service {
                     })),
                 };
                 const jsonCode = JSON.stringify(json, undefined, "  ");
-                return new RawResponse(jsonCode, "ok-json");
+                return makeOkHtmlResponse(jsonCode);
             }
-            else if (reqBody === "debug" || reqBody === "restudio") {
-                return new RawResponse(RESTUDIO_HTML, "ok-html");
+            else if (reqBody === "studio") {
+                const studioHtml = getStudioHtml(this.options.studioAppJsUrl);
+                return makeOkHtmlResponse(studioHtml);
             }
             // Parse request
             let methodName;
@@ -2022,11 +2065,11 @@ class Service {
                     reqBodyJson = JSON.parse(reqBody);
                 }
                 catch (_e) {
-                    return new RawResponse("bad request: invalid JSON", "bad-request");
+                    return makeBadRequestResponse("bad request: invalid JSON");
                 }
                 const methodField = reqBodyJson["method"];
                 if (methodField === undefined) {
-                    return new RawResponse("bad request: missing 'method' field in JSON", "bad-request");
+                    return makeBadRequestResponse("bad request: missing 'method' field in JSON");
                 }
                 if (typeof methodField === "string") {
                     methodName = methodField;
@@ -2037,12 +2080,12 @@ class Service {
                     methodNumber = methodField;
                 }
                 else {
-                    return new RawResponse("bad request: 'method' field must be a string or a number", "bad-request");
+                    return makeBadRequestResponse("bad request: 'method' field must be a string or a number");
                 }
                 format = "readable";
                 const requestField = reqBodyJson["request"];
                 if (requestField === undefined) {
-                    return new RawResponse("bad request: missing 'request' field in JSON", "bad-request");
+                    return makeBadRequestResponse("bad request: missing 'request' field in JSON");
                 }
                 requestData = ["json", requestField];
             }
@@ -2050,7 +2093,7 @@ class Service {
                 // A colon-separated string
                 const match = reqBody.match(/^([^:]*):([^:]*):([^:]*):([\S\s]*)$/);
                 if (!match) {
-                    return new RawResponse("bad request: invalid request format", "bad-request");
+                    return makeBadRequestResponse("bad request: invalid request format");
                 }
                 methodName = match[1];
                 const methodNumberStr = match[2];
@@ -2058,7 +2101,7 @@ class Service {
                 requestData = ["json-code", match[4]];
                 if (methodNumberStr) {
                     if (!/^-?[0-9]+$/.test(methodNumberStr)) {
-                        return new RawResponse("bad request: can't parse method number", "bad-request");
+                        return makeBadRequestResponse("bad request: can't parse method number");
                     }
                     methodNumber = parseInt(methodNumberStr);
                 }
@@ -2072,35 +2115,47 @@ class Service {
                 const allMethods = Object.values(this.methodImpls);
                 const nameMatches = allMethods.filter((m) => m.method.name === methodName);
                 if (nameMatches.length === 0) {
-                    return new RawResponse(`bad request: method not found: ${methodName}`, "bad-request");
+                    return makeBadRequestResponse(`bad request: method not found: ${methodName}`);
                 }
                 else if (nameMatches.length > 1) {
-                    return new RawResponse(`bad request: method name '${methodName}' is ambiguous; use method number instead`, "bad-request");
+                    return makeBadRequestResponse(`bad request: method name '${methodName}' is ambiguous; use method number instead`);
                 }
                 methodNumber = nameMatches[0].method.number;
             }
             const methodImpl = this.methodImpls[methodNumber];
             if (!methodImpl) {
-                return new RawResponse(`bad request: method not found: ${methodName}; number: ${methodNumber}`, "bad-request");
+                return makeBadRequestResponse(`bad request: method not found: ${methodName}; number: ${methodNumber}`);
             }
             let req;
             try {
                 if (requestData[0] == "json") {
-                    req = methodImpl.method.requestSerializer.fromJson(requestData[1], keepUnrecognizedValues);
+                    req = methodImpl.method.requestSerializer.fromJson(requestData[1], this.options.keepUnrecognizedValues
+                        ? "keep-unrecognized-values"
+                        : undefined);
                 }
                 else {
-                    req = methodImpl.method.requestSerializer.fromJsonCode(requestData[1], keepUnrecognizedValues);
+                    req = methodImpl.method.requestSerializer.fromJsonCode(requestData[1], this.options.keepUnrecognizedValues
+                        ? "keep-unrecognized-values"
+                        : undefined);
                 }
             }
             catch (e) {
-                return new RawResponse(`bad request: can't parse JSON: ${e}`, "bad-request");
+                return makeBadRequestResponse(`bad request: can't parse JSON: ${e}`);
             }
             let res;
             try {
-                res = yield methodImpl.impl(req, reqMeta, resMeta);
+                res = yield methodImpl.impl(req, reqMeta);
             }
             catch (e) {
-                return new RawResponse(`server error: ${e}`, "server-error");
+                if (e instanceof ServiceError) {
+                    return e.toRawResponse();
+                }
+                else {
+                    const message = this.options.canCopyUnknownErrorMessageToResponse(reqMeta)
+                        ? `server error: ${e}`
+                        : "server error";
+                    return makeServerErrorResponse(message);
+                }
             }
             let resJson;
             try {
@@ -2108,14 +2163,59 @@ class Service {
                 resJson = methodImpl.method.responseSerializer.toJsonCode(res, flavor);
             }
             catch (e) {
-                return new RawResponse(`server error: can't serialize response to JSON: ${e}`, "server-error");
+                return makeServerErrorResponse(`server error: can't serialize response to JSON: ${e}`);
             }
-            return new RawResponse(resJson, "ok-json");
+            return makeOkJsonResponse(resJson);
         });
     }
+    /**
+     * Creates a request handler that extracts simplified request metadata from
+     * framework-specific request objects before passing it to this service.
+     *
+     * This decouples your service implementation from the HTTP framework, making
+     * it easier to unit test (tests don't need to mock framework objects) and
+     * making the service implementation clearer by explicitly declaring exactly
+     * what request data it needs.
+     *
+     * @param transformFn Function that extracts the necessary data from the
+     *   framework-specific request object. Can be async or sync.
+     * @returns A request handler that accepts the framework-specific request type.
+     *
+     * @example
+     * ```typescript
+     * // Define a service that only needs to know if the user is an admin
+     *
+     * const service = new Service<{ isAdmin: boolean }>();
+     *
+     * service.addMethod(myMethod, async (req, { isAdmin }) => {
+     *   // Implementation is framework-agnostic and easy to test
+     *   if (!isAdmin) throw new ServiceError({ statusCode: 403, desc: "Forbidden" });
+     *   // ...
+     * });
+     *
+     * // Adapt it to work with Express
+     * const expressHandler = service.withRequestMeta((req: ExpressRequest) => ({
+     *   isAdmin: req.user?.role === 'admin'
+     * }));
+     * installServiceOnExpressApp(app, '/api', expressHandler, text, json);
+     * ```
+     */
+    withRequestMeta(transformFn) {
+        return {
+            handleRequest: (reqBody, reqMeta) => __awaiter(this, void 0, void 0, function* () {
+                const transformedMeta = yield Promise.resolve(transformFn(reqMeta));
+                return this.handleRequest(reqBody, transformedMeta);
+            }),
+        };
+    }
 }
 exports.Service = Service;
-function installServiceOnExpressApp(app, queryPath, service, text, json, keepUnrecognizedValues) {
+const DEFAULT_SERVICE_OPTIONS = {
+    keepUnrecognizedValues: false,
+    canCopyUnknownErrorMessageToResponse: () => false,
+    studioAppJsUrl: "https://cdn.jsdelivr.net/npm/skir-studio/dist/skir-studio-standalone.js",
+};
+function installServiceOnExpressApp(app, queryPath, service, text, json) {
     const callback = (req, res) => __awaiter(this, void 0, void 0, function* () {
         let body;
         const indexOfQuestionMark = req.originalUrl.indexOf("?");
@@ -2131,7 +2231,7 @@ function installServiceOnExpressApp(app, queryPath, service, text, json, keepUnr
                         ? JSON.stringify(req.body)
                         : "";
         }
-        const rawResponse = yield service.handleRequest(body, req, res, keepUnrecognizedValues);
+        const rawResponse = yield service.handleRequest(body, req);
         res
             .status(rawResponse.statusCode)
             .contentType(rawResponse.contentType)