@zudojs/api 0.1.0 → 1.0.0

package/dist/api/registry/operationRegistry.core.js

@@ -1,7 +1,12 @@
+import { assertValidOperationShape, freezeOperationMetadata, } from "../operation/operation.type.js";
+import { APIDuplicateOperationError, APIOperationNotFoundError, createAPIError, } from "../errors/index.js";
 /**
  * Registry for API operations.
  *
  * Enforces uniqueness and provides O(1) lookup by operation name.
+ *
+ * Every failure leaving this class is an `APIError`, so a transport can
+ * map it by `statusCode` / `code` without special-casing the registry.
  */
 export class APIOperationRegistry {
     operations = new Map();
@@ -9,16 +14,24 @@ export class APIOperationRegistry {
     /**
      * Registers an operation.
      *
+     * The operation and its metadata are frozen on registration, so a
+     * registered operation cannot be rewritten through `metadata.tags` or
+     * `metadata.timeout` after the fact.
+     *
      * @throws {APIDuplicateOperationError} if an operation with the same name is already registered.
+     * @throws {APIError} if the registry is frozen.
+     * @throws {TypeError | RangeError} if the operation's name or handler is invalid.
      */
     register(operation) {
         if (this.frozen) {
-            throw new Error("Cannot register operations on a frozen registry.");
+            throw frozenRegistryError("register");
         }
+        assertValidOperationShape(operation);
         const existing = this.operations.get(operation.name);
         if (existing !== undefined) {
-            throw new Error(`Operation "${operation.name}" is already registered.`);
+            throw new APIDuplicateOperationError(operation.name);
         }
+        freezeOperationMetadata(operation.metadata);
         this.operations.set(operation.name, Object.freeze(operation));
     }
     /**
@@ -35,11 +48,13 @@ export class APIOperationRegistry {
     }
     /**
      * Retrieves an operation by name or throws.
+     *
+     * @throws {APIOperationNotFoundError} (404) if no operation is registered under `name`.
      */
     require(name) {
         const operation = this.get(name);
         if (operation === undefined) {
-            throw new Error(`Operation "${name}" is not registered.`);
+            throw new APIOperationNotFoundError(name);
         }
         return operation;
     }
@@ -57,10 +72,12 @@ export class APIOperationRegistry {
     }
     /**
      * Unregisters an operation.
+     *
+     * @throws {APIError} if the registry is frozen.
      */
     unregister(name) {
         if (this.frozen) {
-            throw new Error("Cannot unregister operations on a frozen registry.");
+            throw frozenRegistryError("unregister");
         }
         return this.operations.delete(name);
     }
@@ -77,4 +94,15 @@ export class APIOperationRegistry {
         return this.frozen;
     }
 }
+/**
+ * Mutating a frozen registry is a server-side programming error, never a
+ * client mistake — hence 500 and `expose: false`.
+ */
+function frozenRegistryError(action) {
+    return createAPIError(`Cannot ${action} operations on a frozen registry.`, {
+        statusCode: 500,
+        expose: false,
+        isOperational: false,
+    });
+}
 //# sourceMappingURL=operationRegistry.core.js.map

package/dist/index.d.ts

@@ -4,40 +4,49 @@
  * Application-facing API layer for the Zudojs framework.
  *
  * Provides transport-agnostic operation definitions, execution context,
- * interceptors, policies, and result types.
+ * interceptors, and result types.
  *
  * @example
  * ```ts
- * import { defineOperation, APIOperationRegistry, APIExecutor } from "@zudojs/api";
+ * import {
+ *   defineOperation,
+ *   APIOperationRegistry,
+ *   APIExecutor,
+ *   createAPIContext,
+ * } from "@zudojs/api";
  *
  * const getUser = defineOperation({
  *   name: "users.get",
- *   input: GetUserSchema,
+ *   input: GetUserSchema, // any Standard Schema (Zod, Valibot, ArkType, …)
  *   output: UserSchema,
- *   handler: async (input, context) => {
- *     return userService.findById(input.id);
- *   },
+ *   handler: async (input, context) => userService.findById(input.id),
  * });
  *
  * const registry = new APIOperationRegistry();
  * registry.register(getUser);
  *
  * const executor = new APIExecutor();
- * const result = await executor.execute(getUser, { id: "123" }, context);
+ * const context = createAPIContext("req-1", {});
+ * const result = await executor.execute(
+ *   registry.require("users.get"),
+ *   { id: "123" },
+ *   context,
+ * );
  * ```
  */
 export type { APISuccess, APIFailure, APIResult, } from "./api/result/apiResult.type.js";
 export { apiSuccess, apiFailure, isApiSuccess, isApiFailure, } from "./api/result/apiResult.type.js";
 export type { APIErrorOptions } from "./api/errors/index.js";
-export { APIError, APIValidationError, APIAuthenticationError, APIAuthorizationError, APINotFoundError, APIConflictError, APIRateLimitError, APITimeoutError, APIUnavailableError, APIInternalError, APIVersionError, APIOperationNotFoundError, APIDuplicateOperationError, APIIdempotencyError, createAPIError, isAPIError, } from "./api/errors/index.js";
-export { DEFAULT_OPERATION_TIMEOUT, MAX_INTERCEPTORS, MAX_POLICIES, } from "./api/constants.js";
+export { APIError, APIValidationError, APIAuthenticationError, APIAuthorizationError, APINotFoundError, APIConflictError, APIRateLimitError, APITimeoutError, APIUnavailableError, APIInternalError, APIVersionError, APIOperationNotFoundError, APIDuplicateOperationError, APIIdempotencyError, createAPIError, isAPIError, ErrorCode, } from "./api/errors/index.js";
+export { DEFAULT_OPERATION_TIMEOUT, MAX_OPERATION_TIMEOUT, MAX_INTERCEPTORS, MAX_VALIDATION_ISSUES, MAX_VALIDATION_ISSUE_LENGTH, MAX_OPERATION_NAME_LENGTH, MAX_REQUEST_ID_LENGTH, } from "./api/constants.js";
 export type { APIContext, APIContextKey } from "./api/context/context.type.js";
-export { createAPIContext, RequestIdContextKey, CorrelationIdContextKey, TenantIdContextKey, UserIdContextKey, StartTimeContextKey, } from "./api/context/context.type.js";
+export { createAPIContext, createContextKey, isValidRequestId, normalizeRequestId, RequestIdContextKey, CorrelationIdContextKey, TenantIdContextKey, UserIdContextKey, StartTimeContextKey, } from "./api/context/context.type.js";
 export type { APIHandler } from "./api/handler/handler.type.js";
-export type { APIOperation, APIOperationMetadata, DefineOperationOptions, } from "./api/operation/operation.type.js";
-export { defineOperation } from "./api/operation/operation.type.js";
+export type { AnyAPIOperation, APIOperation, APIOperationMetadata, DefineOperationOptions, } from "./api/operation/operation.type.js";
+export { defineOperation, resolveOperationTimeout, } from "./api/operation/operation.type.js";
 export { APIOperationRegistry } from "./api/registry/index.js";
 export type { APIInterceptor, APIExecutionContext, } from "./api/interceptors/interceptor.type.js";
 export { createNoopInterceptor } from "./api/interceptors/interceptor.type.js";
+export type { APIExecutorOptions } from "./api/executor/index.js";
 export { APIExecutor, normalizeAPIError } from "./api/executor/index.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -4,37 +4,44 @@
  * Application-facing API layer for the Zudojs framework.
  *
  * Provides transport-agnostic operation definitions, execution context,
- * interceptors, policies, and result types.
+ * interceptors, and result types.
  *
  * @example
  * ```ts
- * import { defineOperation, APIOperationRegistry, APIExecutor } from "@zudojs/api";
+ * import {
+ *   defineOperation,
+ *   APIOperationRegistry,
+ *   APIExecutor,
+ *   createAPIContext,
+ * } from "@zudojs/api";
  *
  * const getUser = defineOperation({
  *   name: "users.get",
- *   input: GetUserSchema,
+ *   input: GetUserSchema, // any Standard Schema (Zod, Valibot, ArkType, …)
  *   output: UserSchema,
- *   handler: async (input, context) => {
- *     return userService.findById(input.id);
- *   },
+ *   handler: async (input, context) => userService.findById(input.id),
  * });
  *
  * const registry = new APIOperationRegistry();
  * registry.register(getUser);
  *
  * const executor = new APIExecutor();
- * const result = await executor.execute(getUser, { id: "123" }, context);
+ * const context = createAPIContext("req-1", {});
+ * const result = await executor.execute(
+ *   registry.require("users.get"),
+ *   { id: "123" },
+ *   context,
+ * );
  * ```
  */
 export { apiSuccess, apiFailure, isApiSuccess, isApiFailure, } from "./api/result/apiResult.type.js";
-export { APIError, APIValidationError, APIAuthenticationError, APIAuthorizationError, APINotFoundError, APIConflictError, APIRateLimitError, APITimeoutError, APIUnavailableError, APIInternalError, APIVersionError, APIOperationNotFoundError, APIDuplicateOperationError, APIIdempotencyError, createAPIError, isAPIError, } from "./api/errors/index.js";
+export { APIError, APIValidationError, APIAuthenticationError, APIAuthorizationError, APINotFoundError, APIConflictError, APIRateLimitError, APITimeoutError, APIUnavailableError, APIInternalError, APIVersionError, APIOperationNotFoundError, APIDuplicateOperationError, APIIdempotencyError, createAPIError, isAPIError, ErrorCode, } from "./api/errors/index.js";
 // Constants
-export { DEFAULT_OPERATION_TIMEOUT, MAX_INTERCEPTORS, MAX_POLICIES, } from "./api/constants.js";
-export { createAPIContext, RequestIdContextKey, CorrelationIdContextKey, TenantIdContextKey, UserIdContextKey, StartTimeContextKey, } from "./api/context/context.type.js";
-export { defineOperation } from "./api/operation/operation.type.js";
+export { DEFAULT_OPERATION_TIMEOUT, MAX_OPERATION_TIMEOUT, MAX_INTERCEPTORS, MAX_VALIDATION_ISSUES, MAX_VALIDATION_ISSUE_LENGTH, MAX_OPERATION_NAME_LENGTH, MAX_REQUEST_ID_LENGTH, } from "./api/constants.js";
+export { createAPIContext, createContextKey, isValidRequestId, normalizeRequestId, RequestIdContextKey, CorrelationIdContextKey, TenantIdContextKey, UserIdContextKey, StartTimeContextKey, } from "./api/context/context.type.js";
+export { defineOperation, resolveOperationTimeout, } from "./api/operation/operation.type.js";
 // Registry
 export { APIOperationRegistry } from "./api/registry/index.js";
 export { createNoopInterceptor } from "./api/interceptors/interceptor.type.js";
-// Executor
 export { APIExecutor, normalizeAPIError } from "./api/executor/index.js";
 //# sourceMappingURL=index.js.map

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@zudojs/api",
-  "version": "0.1.0",
-  "description": "Application-facing API layer for Zudojs — operation definitions, execution context, interceptors, policies, and transport-agnostic contracts.",
+  "version": "1.0.0",
+  "description": "Application-facing API layer for Zudojs — operation definitions, execution context, interceptors, and transport-agnostic contracts.",
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.js",
@@ -14,26 +14,22 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "!dist/**/*.map",
+    "!dist/**/*.tsbuildinfo",
+    "!dist/.tsbuildinfo"
   ],
-  "scripts": {
-    "build": "tsc -p tsconfig.json",
-    "typecheck": "tsc -p tsconfig.json --noEmit",
-    "clean": "rm -rf dist",
-    "test": "vitest run",
-    "test:watch": "vitest"
-  },
   "engines": {
     "node": ">=24.0.0"
   },
   "dependencies": {
-    "@zudojs/errors": "0.1.0",
-    "@zudojs/constants": "0.1.0",
-    "@zudojs/types": "0.1.0",
-    "@zudojs/schema": "0.1.0"
+    "@zudojs/errors": "1.0.0",
+    "@zudojs/constants": "1.0.0",
+    "@zudojs/types": "1.0.0",
+    "@zudojs/schema": "1.0.0"
   },
   "devDependencies": {
-    "typescript": "^7.0.2",
+    "typescript": "7.0.2",
     "vitest": "^4.1.11"
   },
   "publishConfig": {
@@ -46,8 +42,19 @@
     "interceptors"
   ],
   "homepage": "https://github.com/oyinlola-tech/zudo#readme",
+  "bugs": {
+    "url": "https://github.com/oyinlola-tech/zudo/issues"
+  },
   "repository": {
     "type": "git",
-    "url": "https://github.com/oyinlola-tech/zudo"
+    "url": "https://github.com/oyinlola-tech/zudo",
+    "directory": "packages/api"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.test.json --noEmit",
+    "clean": "rm -rf dist",
+    "test": "vitest run",
+    "test:watch": "vitest"
   }
-}
+}