@kosmojs/api 0.0.20 → 0.0.21

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-present, Slee Woo and KosmoJS contributors.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package.json

@@ -1,7 +1,7 @@
 {
   "type": "module",
   "name": "@kosmojs/api",
-  "version": "0.0.20",
+  "version": "0.0.21",
   "author": "Slee Woo",
   "license": "MIT",
   "publishConfig": {
@@ -12,40 +12,33 @@
   ],
   "exports": {
     ".": {
-      "types": "./pkg/src/index.d.ts",
+      "types": "./pkg/index.d.ts",
       "default": "./pkg/index.js"
     },
-    "./bodyparser": {
-      "types": "./pkg/src/bodyparser/index.d.ts",
-      "default": "./pkg/bodyparser/index.js"
-    },
-    "./queryparser": {
-      "types": "./pkg/src/queryparser/index.d.ts",
-      "default": "./pkg/queryparser/index.js"
-    },
     "./errors": {
-      "types": "./pkg/src/errors/index.d.ts",
+      "types": "./pkg/errors/index.d.ts",
       "default": "./pkg/errors/index.js"
     }
   },
   "dependencies": {
-    "@koa/router": "^15.0.0",
+    "@koa/router": "^15.3.1",
     "formidable": "^3.5.4",
-    "koa": "^3.1.1",
-    "qs": "^6.14.0",
+    "koa": "^3.1.2",
+    "qs": "^6.15.0",
     "raw-body": "^3.0.2",
-    "string-width": "^8.1.0"
+    "string-width": "^8.2.0"
   },
   "devDependencies": {
-    "@types/formidable": "^3.4.6",
+    "@types/bun": "^1.3.10",
+    "@types/formidable": "^3.5.0",
     "@types/koa": "^3.0.1",
     "@types/koa-compose": "^3.2.9",
     "@types/picomatch": "^4.0.2",
-    "@types/qs": "^6.14.0",
+    "@types/qs": "^6.15.0",
     "koa-compose": "^4.1.0"
   },
   "scripts": {
-    "build": "esbuilder src/index.ts src/bodyparser/index.ts src/queryparser/index.ts src/errors/index.ts",
+    "build": "esbuilder src/index.ts src/errors/index.ts",
     "test": "vitest --root ../../.. --project core/api"
   }
 }

package/pkg/debug.d.ts

@@ -0,0 +1,16 @@
+import type { HTTPMethod, Route, UseOptions } from "./types";
+export declare const debugRouteEntry: <MiddlewareT>(entry: {
+    name: string;
+    path: string;
+    file: string;
+    methods: Array<string>;
+    middleware: Array<{
+        middleware: Array<MiddlewareT>;
+        options?: UseOptions | undefined;
+    }>;
+    handler: {
+        kind: "handler";
+        middleware: Array<MiddlewareT>;
+        method: HTTPMethod;
+    };
+}) => Route<MiddlewareT>["debug"];

package/pkg/errors/index.d.ts

@@ -0,0 +1,21 @@
+import type { ValidationTarget } from "../types";
+import type { ValidationErrorData, ValidationErrorEntry } from "./types";
+export * from "./types";
+/**
+ * Standardized error wrapper used by validation generators.
+ *
+ * Instances of this class are thrown whenever validation fails,
+ * carrying both the validation target and the list of validation error details.
+ * */
+export declare class ValidationError extends Error {
+    target: ValidationTarget;
+    errors: Array<ValidationErrorEntry>;
+    errorMessage: string;
+    errorSummary: string;
+    route: string;
+    data: unknown;
+    constructor([target, { errors, errorMessage, errorSummary, route, data }]: [
+        ValidationTarget,
+        ValidationErrorData
+    ]);
+}

package/pkg/errors/index.js

@@ -1,16 +1,20 @@
 // src/errors/index.ts
 var ValidationError = class extends Error {
-  scope;
+  target;
   errors = [];
   errorMessage;
   errorSummary;
-  constructor([scope, { errors, errorMessage, errorSummary }]) {
+  route;
+  data;
+  constructor([target, { errors, errorMessage, errorSummary, route, data }]) {
     super(JSON.stringify(errors, null, 2));
-    this.name = `${scope}ValidationError`;
-    this.scope = scope;
+    this.name = `${target}ValidationError`;
+    this.target = target;
     this.errors = errors;
     this.errorMessage = errorMessage;
     this.errorSummary = errorSummary;
+    this.route = route;
+    this.data = data;
   }
 };
 export {

package/pkg/errors/index.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../src/errors/index.ts"],
-  "sourcesContent": ["import type {\n  ValidationErrorData,\n  ValidationErrorEntry,\n  ValidationErrorScope,\n} from \"@/types\";\n\n/**\n * Standardized error wrapper used by validation generators.\n *\n * Instances of this class are thrown whenever validation fails,\n * carrying both the error scope (e.g. `\"params\"`, `\"payload\"`)\n * and the list of validation error details.\n * */\nexport class ValidationError extends Error {\n  public scope: ValidationErrorScope;\n  public errors: Array<ValidationErrorEntry> = [];\n  public errorMessage: string;\n  public errorSummary: string;\n\n  constructor([scope, { errors, errorMessage, errorSummary }]: [\n    ValidationErrorScope,\n    ValidationErrorData,\n  ]) {\n    super(JSON.stringify(errors, null, 2));\n    this.name = `${scope}ValidationError`;\n    this.scope = scope;\n    this.errors = errors;\n    this.errorMessage = errorMessage;\n    this.errorSummary = errorSummary;\n  }\n}\n"],
-  "mappings": ";AAaO,IAAM,kBAAN,cAA8B,MAAM;AAAA,EAClC;AAAA,EACA,SAAsC,CAAC;AAAA,EACvC;AAAA,EACA;AAAA,EAEP,YAAY,CAAC,OAAO,EAAE,QAAQ,cAAc,aAAa,CAAC,GAGvD;AACD,UAAM,KAAK,UAAU,QAAQ,MAAM,CAAC,CAAC;AACrC,SAAK,OAAO,GAAG,KAAK;AACpB,SAAK,QAAQ;AACb,SAAK,SAAS;AACd,SAAK,eAAe;AACpB,SAAK,eAAe;AAAA,EACtB;AACF;",
+  "sourcesContent": ["import type { ValidationTarget } from \"../types\";\nimport type { ValidationErrorData, ValidationErrorEntry } from \"./types\";\n\nexport * from \"./types\";\n\n/**\n * Standardized error wrapper used by validation generators.\n *\n * Instances of this class are thrown whenever validation fails,\n * carrying both the validation target and the list of validation error details.\n * */\nexport class ValidationError extends Error {\n  public target: ValidationTarget;\n  public errors: Array<ValidationErrorEntry> = [];\n  public errorMessage: string;\n  public errorSummary: string;\n  public route: string;\n  public data: unknown;\n\n  constructor([target, { errors, errorMessage, errorSummary, route, data }]: [\n    ValidationTarget,\n    ValidationErrorData,\n  ]) {\n    super(JSON.stringify(errors, null, 2));\n    this.name = `${target}ValidationError`;\n    this.target = target;\n    this.errors = errors;\n    this.errorMessage = errorMessage;\n    this.errorSummary = errorSummary;\n    this.route = route;\n    this.data = data;\n  }\n}\n"],
+  "mappings": ";AAWO,IAAM,kBAAN,cAA8B,MAAM;AAAA,EAClC;AAAA,EACA,SAAsC,CAAC;AAAA,EACvC;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EAEP,YAAY,CAAC,QAAQ,EAAE,QAAQ,cAAc,cAAc,OAAO,KAAK,CAAC,GAGrE;AACD,UAAM,KAAK,UAAU,QAAQ,MAAM,CAAC,CAAC;AACrC,SAAK,OAAO,GAAG,MAAM;AACrB,SAAK,SAAS;AACd,SAAK,SAAS;AACd,SAAK,eAAe;AACpB,SAAK,eAAe;AACpB,SAAK,QAAQ;AACb,SAAK,OAAO;AAAA,EACd;AACF;",
   "names": []
 }

package/pkg/errors/types.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Shape of individual validation errors emitted by generators.
+ * */
+export type ValidationErrorEntry = {
+    /**
+     * JSON Schema keyword that triggered the error
+     * (e.g. `format`, `maxItems`, `maxLength`).
+     * */
+    keyword: string;
+    /**
+     * JSON Pointer–style path to the invalid field
+     * (matches JSON Schema `instancePath`).
+     * */
+    path: string;
+    /**
+     * Human-readable error message.
+     * */
+    message: string;
+    /**
+     * Constraint parameters (e.g. `{ limit: 5 }`, `{ format: "email" }`).
+     * */
+    params?: Record<string, unknown>;
+    /**
+     * Optional error code for i18n/l10n or custom handling.
+     * */
+    code?: string;
+};
+export type ValidationErrorData = {
+    errors: Array<ValidationErrorEntry>;
+    /**
+     * Formats errors into a single human-readable message.
+     * @example: Validation failed: user: missing required properties:
+     * "email", "name"; password: must be at least 8 characters long
+     * */
+    errorMessage: string;
+    /**
+     * Gets a simple error summary for quick feedback.
+     * @example: 2 validation errors found across 2 fields
+     * */
+    errorSummary: string;
+    route: string;
+    data: unknown;
+};

package/pkg/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./debug";
+export * from "./routes";
+export * from "./types";

package/pkg/index.js

@@ -1,64 +1,3 @@
-// src/app.ts
-import Koa from "koa";
-
-// src/queryparser/index.ts
-import { parse, stringify } from "qs";
-var queryparser_default = (app, _parseOptions = {}, _stringifyOptions = {}) => {
-  const parseOptions = {
-    ignoreQueryPrefix: true,
-    parseArrays: true,
-    arrayLimit: 100,
-    parameterLimit: 100,
-    depth: 5,
-    ..._parseOptions
-  };
-  const stringifyOptions = {
-    encodeValuesOnly: true,
-    arrayFormat: "brackets",
-    ..._stringifyOptions
-  };
-  const obj = {
-    get query() {
-      return parse(this.querystring || "", parseOptions);
-    },
-    set query(obj2) {
-      this.querystring = stringify(obj2, stringifyOptions);
-    }
-  };
-  const entries = Object.getOwnPropertyNames(obj).map((name) => [
-    name,
-    Object.getOwnPropertyDescriptor(obj, name)
-  ]);
-  for (const [name, desc] of entries) {
-    Object.defineProperty(app.request, name, desc);
-  }
-  return app;
-};
-
-// src/app.ts
-var createApp = (options) => {
-  return queryparser_default(new Koa(options));
-};
-
-// src/errors/index.ts
-var ValidationError = class extends Error {
-  scope;
-  errors = [];
-  errorMessage;
-  errorSummary;
-  constructor([scope, { errors, errorMessage, errorSummary }]) {
-    super(JSON.stringify(errors, null, 2));
-    this.name = `${scope}ValidationError`;
-    this.scope = scope;
-    this.errors = errors;
-    this.errorMessage = errorMessage;
-    this.errorSummary = errorSummary;
-  }
-};
-
-// src/router.ts
-import Router from "@koa/router";
-
 // src/debug.ts
 import { styleText } from "node:util";
 import stringWidth from "string-width";
@@ -73,7 +12,7 @@ var colorizeMethod = (method) => {
   }[method];
   return color ? styleText(color, method) : method;
 };
-var debug_default = (entry) => {
+var debugRouteEntry = (entry) => {
   const { path, file } = entry;
   const methodLines = entry.methods.flatMap((method) => {
     const coloredMethod = colorizeMethod(method);
@@ -83,13 +22,12 @@ var debug_default = (entry) => {
     const lines = [];
     if (options?.slot) {
       lines.push(
-        `${styleText("dim", "slot:")} ${styleText("blue", options.slot)};`
+        `${styleText("dim", "slot:")} ${styleText("blue", options.slot)}`
       );
     }
-    const funcNames = middleware2.map((fn) => {
-      return styleText("magenta", funcName(fn));
-    });
-    lines.push(`${styleText("dim", "exec:")} ${funcNames.join("; ")}`);
+    lines.push(
+      styleText("dim", middleware2.map(funcName).join("; "))
+    );
     return lines.join(" ");
   }).join(`
 ${Array(12).fill(" ").join("")}`);
@@ -133,107 +71,35 @@ var funcName = (fn) => {
   return fn.name || fn.toString().split("\n")[0].slice(0, 30);
 };
 
-// src/use.ts
-var use = (middleware, options) => {
-  return {
-    kind: "middleware",
-    middleware: [middleware].flat(),
-    options
-  };
-};
-
-// src/router.ts
-var defineRoute = (factory) => {
-  return factory({
-    use(middleware, options) {
-      return {
-        kind: "middleware",
-        middleware: [middleware].flat(),
-        options
-      };
-    },
-    HEAD(middleware) {
-      return {
-        kind: "handler",
-        middleware: [middleware].flat(),
-        method: "HEAD"
-      };
-    },
-    OPTIONS(middleware) {
-      return {
-        kind: "handler",
-        middleware: [middleware].flat(),
-        method: "OPTIONS"
-      };
-    },
-    GET(middleware) {
-      return {
-        kind: "handler",
-        middleware: [middleware].flat(),
-        method: "GET"
-      };
-    },
-    POST(middleware) {
-      return {
-        kind: "handler",
-        middleware: [middleware].flat(),
-        method: "POST"
-      };
-    },
-    PUT(middleware) {
-      return {
-        kind: "handler",
-        middleware: [middleware].flat(),
-        method: "PUT"
-      };
-    },
-    PATCH(middleware) {
-      return {
-        kind: "handler",
-        middleware: [middleware].flat(),
-        method: "PATCH"
-      };
-    },
-    DELETE(middleware) {
-      return {
-        kind: "handler",
-        middleware: [middleware].flat(),
-        method: "DELETE"
-      };
-    }
-  });
-};
-var createRouter = (options) => {
-  return new Router(options);
-};
-var createRouterRoutes = (routeSources, {
-  // Global middleware applied to every route (e.g., logging)
-  coreMiddleware
+// src/routes.ts
+var createRoutes = (routeSources, {
+  globalMiddleware,
+  createRouteMiddleware
 }) => {
   const prioritizedSlots = [
     "errorHandler",
-    "params",
-    "validateParams",
+    "extendContext",
     "bodyparser",
-    "payload",
-    "validatePayload",
-    "validateResponse"
+    "validate:params",
+    "validate:query",
+    "validate:headers",
+    "validate:cookies",
+    "validate:json",
+    "validate:form",
+    "validate:raw",
+    "validate:response"
   ];
   const stack = [];
-  for (const { name, path, file, ...rest } of routeSources) {
+  for (const routeSource of routeSources) {
+    const { name, path, file } = routeSource;
     const definitionItems = [
-      ...rest.useWrappers,
-      ...rest.definitionItems
+      ...routeSource.cascadingMiddleware,
+      ...routeSource.definitionItems
     ].flat();
-    const routeMiddleware = definitionItems.filter(
-      (e) => e.kind === "middleware"
-    );
+    const routeMiddleware = definitionItems.filter((e) => e.kind === "middleware");
     const middlewareStack = [
-      ...createParamsMiddleware(rest.params, rest.numericParams),
-      ...createValidationMiddleware(rest.validationSchemas),
-      // core middleware overrides builtin middleware (of same slot)
-      ...coreMiddleware,
-      // route middleware overrides core middleware (of same slot)
+      ...createRouteMiddleware(routeSource),
+      ...globalMiddleware,
       ...routeMiddleware
     ];
     const routeStack = [
@@ -245,7 +111,7 @@ var createRouterRoutes = (routeSources, {
         );
         return middleware ? [middleware] : [];
       }),
-      ...coreMiddleware.flatMap((entry) => {
+      ...globalMiddleware.flatMap((entry) => {
         if (!entry.options?.slot) {
           return [entry];
         }
@@ -265,7 +131,7 @@ var createRouterRoutes = (routeSources, {
           if (prioritizedSlots.includes(slot)) {
             return [];
           }
-          if (coreMiddleware.some((e) => e.options?.slot === slot)) {
+          if (globalMiddleware.some((e) => e.options?.slot === slot)) {
             return [];
           }
         }
@@ -289,7 +155,7 @@ var createRouterRoutes = (routeSources, {
             ...middleware.flatMap((e) => e.middleware),
             ...entry.middleware
           ],
-          debug: debug_default({
+          debug: debugRouteEntry({
             name,
             path,
             file,
@@ -303,63 +169,6 @@ var createRouterRoutes = (routeSources, {
   }
   return stack;
 };
-var createParamsMiddleware = (params, numericParams) => [
-  use(
-    function useParams(ctx, next) {
-      ctx.typedParams = params.reduce(
-        (map, [name, isRest]) => {
-          const value = ctx.params[name];
-          if (value) {
-            if (isRest) {
-              map[name] = numericParams.includes(name) ? value.split("/").map(Number) : value.split("/");
-            } else {
-              map[name] = numericParams.includes(name) ? Number(value) : value;
-            }
-          } else {
-            map[name] = value;
-          }
-          return map;
-        },
-        {}
-      );
-      return next();
-    },
-    { slot: "params" }
-  )
-];
-var createValidationMiddleware = (validationSchemas) => [
-  use(
-    function useValidateParams(ctx, next) {
-      validationSchemas.params?.validate(ctx.typedParams);
-      return next();
-    },
-    { slot: "validateParams" }
-  ),
-  use(
-    function useValidatePayload(ctx, next) {
-      validationSchemas.payload?.[ctx.method]?.validate(ctx.payload);
-      return next();
-    },
-    {
-      slot: "validatePayload",
-      on: Object.keys(validationSchemas.payload || {})
-    }
-  ),
-  use(
-    async function useValidateResponse(ctx, next) {
-      if (validationSchemas.response?.[ctx.method]) {
-        await next();
-        validationSchemas.response?.[ctx.method]?.validate(ctx.body);
-      } else {
-        return next();
-      }
-    },
-    {
-      slot: "validateResponse",
-      on: Object.keys(validationSchemas.response || {})
-    }
-  )
-];
 
 // src/types.ts
 var HTTPMethods = /* @__PURE__ */ ((HTTPMethods2) => {
@@ -372,13 +181,28 @@ var HTTPMethods = /* @__PURE__ */ ((HTTPMethods2) => {
   HTTPMethods2["DELETE"] = "DELETE";
   return HTTPMethods2;
 })(HTTPMethods || {});
+var RequestMetadataTargets = {
+  query: "URL query parameters",
+  headers: "HTTP request headers",
+  cookies: "HTTP cookies"
+};
+var RequestBodyTargets = {
+  json: "JSON request body",
+  form: "URL-encoded or Multipart form",
+  raw: "Raw body format (string/Buffer/ArrayBuffer/Blob)"
+};
+var RequestValidationTargets = {
+  ...RequestMetadataTargets,
+  ...RequestBodyTargets
+};
+var StateKey = /* @__PURE__ */ Symbol("kosmo.state");
 export {
   HTTPMethods,
-  ValidationError,
-  createApp,
-  createRouter,
-  createRouterRoutes,
-  defineRoute,
-  use
+  RequestBodyTargets,
+  RequestMetadataTargets,
+  RequestValidationTargets,
+  StateKey,
+  createRoutes,
+  debugRouteEntry
 };
 //# sourceMappingURL=index.js.map