@ucdjs-internal/worker-utils 0.0.1-beta.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-PRESENT Lucas Nørgård
+
+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/dist/index.d.mts

@@ -0,0 +1,200 @@
+import { ApiError } from "@ucdjs/schemas";
+import { Context } from "hono";
+import { TypedResponse } from "hono/types";
+import { ContentfulStatusCode } from "hono/utils/http-status";
+import { ZodType, z } from "zod";
+
+//#region src/cache.d.ts
+type ClearCacheFn = (requestOrPath: Request | string) => Promise<void>;
+declare function clearCacheEntry(name: string): Promise<ClearCacheFn>;
+//#endregion
+//#region src/environment.d.ts
+type WorkerEnvironmentName = "production" | "preview" | "local" | "testing" | (string & {});
+declare function getApiOriginForEnvironment(environment: WorkerEnvironmentName | undefined): string;
+//#endregion
+//#region src/errors.d.ts
+interface ResponseOptions {
+  /**
+   * The message to include in the response.
+   */
+  message?: string;
+  /**
+   * Additional headers to include in the response.
+   * This can be used to set custom headers like `Content-Type`, `Cache-Control`,
+   * or any other headers that might be relevant to the response.
+   */
+  headers?: Record<string, string>;
+}
+/**
+ * Creates a standardized 400 Bad Request HTTP response with JSON error details.
+ *
+ * @param {Context | ResponseOptions} contextOrOptions - Hono context or configuration options
+ * @param {ResponseOptions?} options - Configuration options when context is provided
+ * @returns {Response} A Response object with 400 status and JSON error body
+ *
+ * @example
+ * ```typescript
+ * import { badRequest } from "../../lib";
+ *
+ * // Basic usage (legacy)
+ * return badRequest();
+ *
+ * // With custom message
+ * return badRequest({
+ *   message: "Invalid request parameters",
+ * });
+ *
+ * // With Hono context (new)
+ * return badRequest(c, { message: "Invalid request parameters" });
+ * ```
+ */
+declare function badRequest(contextOrOptions?: Context | ResponseOptions, options?: ResponseOptions): Response & TypedResponse<ApiError, 400, "json">;
+/**
+ * Creates a standardized 403 Forbidden HTTP response with JSON error details.
+ *
+ * @param {Context | ResponseOptions} contextOrOptions - Hono context or configuration options
+ * @param {ResponseOptions?} options - Configuration options when context is provided
+ * @returns {Response} A Response object with 403 status and JSON error body
+ *
+ * @example
+ * ```typescript
+ * import { forbidden } from "../../lib";
+ *
+ * // Basic usage (legacy)
+ * return forbidden();
+ *
+ * // With custom message (legacy)
+ * return forbidden({
+ *   message: "Access denied to this resource"
+ * });
+ *
+ * // With Hono context (new)
+ * return forbidden(c, { message: "Access denied to this resource" });
+ * ```
+ */
+declare function forbidden(contextOrOptions?: Context | ResponseOptions, options?: ResponseOptions): Response & TypedResponse<ApiError, 403, "json">;
+/**
+ * Creates a standardized 404 Not Found HTTP response with JSON error details.
+ *
+ * @param {Context | ResponseOptions} contextOrOptions - Hono context or configuration options
+ * @param {ResponseOptions?} options - Configuration options when context is provided
+ * @returns {Response} A Response object with 404 status and JSON error body
+ *
+ * @example
+ * ```typescript
+ * import { notFound } from "../../lib";
+ *
+ * // Basic usage (legacy)
+ * return notFound();
+ *
+ * // With custom message (legacy)
+ * return notFound({
+ *   message: "User not found"
+ * });
+ *
+ * // With Hono context (new)
+ * return notFound(c, { message: "User not found" });
+ * ```
+ */
+declare function notFound(contextOrOptions?: Context | ResponseOptions, options?: ResponseOptions): Response & TypedResponse<ApiError, 404, "json">;
+/**
+ * Creates a standardized 500 Internal Server Error HTTP response with JSON error details.
+ *
+ * @param {Context | ResponseOptions} contextOrOptions - Hono context or configuration options
+ * @param {ResponseOptions?} options - Configuration options when context is provided
+ * @returns {Response} A Response object with 500 status and JSON error body
+ *
+ * @example
+ * ```typescript
+ * import { internalServerError } from "../../lib";
+ *
+ * // Basic usage (legacy)
+ * return internalServerError();
+ *
+ * // With custom message (legacy)
+ * return internalServerError({
+ *   message: "Database connection failed"
+ * });
+ *
+ * // With Hono context (new)
+ * return internalServerError(c, { message: "Database connection failed" });
+ * ```
+ */
+declare function internalServerError(contextOrOptions?: Context | ResponseOptions, options?: ResponseOptions): Response & TypedResponse<ApiError, 500, "json">;
+declare function badGateway(contextOrOptions?: Context | ResponseOptions, options?: ResponseOptions): Response & TypedResponse<ApiError, 502, "json">;
+declare function unauthorized(contextOrOptions?: Context | ResponseOptions, options?: ResponseOptions): Response & TypedResponse<ApiError, 401, "json">;
+type CustomResponseOptions = Omit<Required<ResponseOptions>, "headers"> & {
+  /**
+   * Custom headers to include in the response.
+   * This can be used to set headers like `Content-Type`, `Cache-Control`, etc.
+   */
+  headers?: Record<string, string>;
+  /**
+   * The HTTP status code to use for the response.
+   * This should be a valid @see {ContentfulStatusCode}.
+   */
+  status: number;
+};
+type CustomResponseOptionsWithContext = CustomResponseOptions & {
+  /**
+   * Custom headers to include in the response.
+   * This can be used to set headers like `Content-Type`, `Cache-Control`, etc.
+   */
+  headers?: Record<string, string>;
+  /**
+   * The HTTP status code to use for the response.
+   * This should be a valid @see {ContentfulStatusCode}.
+   */
+  status: number;
+};
+/**
+ * Creates a custom HTTP error response with specified status code and JSON error details.
+ * This function allows for flexible error responses with any valid HTTP status code.
+ *
+ * @param {Context | CustomResponseOptions} contextOrOptions - Hono context or configuration options
+ * @param {CustomResponseOptionsWithContext?} options - Configuration options when context is provided
+ * @returns {Response} A Response object with the specified status and JSON error body
+ *
+ * @example
+ * ```typescript
+ * import { customError } from "../../lib";
+ *
+ * // Custom 422 Unprocessable Entity error (legacy)
+ * return customError({
+ *   status: 422,
+ *   message: "Validation failed",
+ * });
+ *
+ * // Custom 429 Too Many Requests error with headers (legacy)
+ * return customError({
+ *   status: 429,
+ *   message: "Rate limit exceeded",
+ *   headers: {
+ *     "Retry-After": "3600"
+ *   }
+ * });
+ *
+ * // With Hono context (new)
+ * return customError(c, {
+ *   status: 422,
+ *   message: "Validation failed"
+ * });
+ * ```
+ */
+declare function customError(contextOrOptions: Context | CustomResponseOptions, options?: CustomResponseOptionsWithContext): Response;
+//#endregion
+//#region src/hostnames.d.ts
+declare function isStoreSubdomainHostname(hostname: string): boolean;
+//#endregion
+//#region src/strict.d.ts
+declare function strictJSONResponse<C extends Context, S extends ZodType, D extends Parameters<Context["json"]>[0] & z.infer<S>, U extends ContentfulStatusCode>(c: C, schema: S, data: D, statusCode?: U): Response;
+//#endregion
+//#region src/tasks.d.ts
+declare const MAX_TAR_SIZE_BYTES: number;
+declare const MAX_WORKFLOW_INSTANCE_ID_LENGTH = 100;
+declare const ALLOWED_STRING_ID_PATTERN = "^\\w[\\w-]*$";
+declare function makeManifestUploadId(version: string, now?: () => number): string;
+declare function isValidWorkflowInstanceId(id: string): boolean;
+declare function buildR2Key(version: string, workflowId: string): string;
+//#endregion
+export { ALLOWED_STRING_ID_PATTERN, ClearCacheFn, CustomResponseOptions, CustomResponseOptionsWithContext, MAX_TAR_SIZE_BYTES, MAX_WORKFLOW_INSTANCE_ID_LENGTH, ResponseOptions, WorkerEnvironmentName, badGateway, badRequest, buildR2Key, clearCacheEntry, customError, forbidden, getApiOriginForEnvironment, internalServerError, isStoreSubdomainHostname, isValidWorkflowInstanceId, makeManifestUploadId, notFound, strictJSONResponse, unauthorized };

package/dist/index.mjs

@@ -0,0 +1,297 @@
+//#region src/cache.ts
+async function clearCacheEntry(name) {
+	let cachePromise = null;
+	return async (requestOrPath) => {
+		if (!cachePromise) cachePromise = caches.open(name);
+		const cache = await cachePromise;
+		const request = typeof requestOrPath === "string" ? new Request(requestOrPath) : requestOrPath;
+		await cache.delete(request);
+	};
+}
+
+//#endregion
+//#region src/environment.ts
+function getApiOriginForEnvironment(environment) {
+	if (environment === "production") return "https://api.ucdjs.dev";
+	if (environment === "preview") return "https://preview.api.ucdjs.dev";
+	return "http://localhost:8787";
+}
+
+//#endregion
+//#region src/errors.ts
+/**
+* Creates a standardized 400 Bad Request HTTP response with JSON error details.
+*
+* @param {Context | ResponseOptions} contextOrOptions - Hono context or configuration options
+* @param {ResponseOptions?} options - Configuration options when context is provided
+* @returns {Response} A Response object with 400 status and JSON error body
+*
+* @example
+* ```typescript
+* import { badRequest } from "../../lib";
+*
+* // Basic usage (legacy)
+* return badRequest();
+*
+* // With custom message
+* return badRequest({
+*   message: "Invalid request parameters",
+* });
+*
+* // With Hono context (new)
+* return badRequest(c, { message: "Invalid request parameters" });
+* ```
+*/
+function badRequest(contextOrOptions = {}, options = {}) {
+	let finalOptions;
+	if ("req" in contextOrOptions) finalOptions = options;
+	else finalOptions = contextOrOptions;
+	return Response.json({
+		message: finalOptions.message || "Bad Request",
+		status: 400,
+		timestamp: (/* @__PURE__ */ new Date()).toISOString()
+	}, {
+		status: 400,
+		headers: {
+			"Content-Type": "application/json",
+			...finalOptions.headers
+		}
+	});
+}
+/**
+* Creates a standardized 403 Forbidden HTTP response with JSON error details.
+*
+* @param {Context | ResponseOptions} contextOrOptions - Hono context or configuration options
+* @param {ResponseOptions?} options - Configuration options when context is provided
+* @returns {Response} A Response object with 403 status and JSON error body
+*
+* @example
+* ```typescript
+* import { forbidden } from "../../lib";
+*
+* // Basic usage (legacy)
+* return forbidden();
+*
+* // With custom message (legacy)
+* return forbidden({
+*   message: "Access denied to this resource"
+* });
+*
+* // With Hono context (new)
+* return forbidden(c, { message: "Access denied to this resource" });
+* ```
+*/
+function forbidden(contextOrOptions = {}, options = {}) {
+	let finalOptions;
+	if ("req" in contextOrOptions) finalOptions = options;
+	else finalOptions = contextOrOptions;
+	return Response.json({
+		message: finalOptions.message || "Forbidden",
+		status: 403,
+		timestamp: (/* @__PURE__ */ new Date()).toISOString()
+	}, {
+		status: 403,
+		headers: {
+			"Content-Type": "application/json",
+			...finalOptions.headers
+		}
+	});
+}
+/**
+* Creates a standardized 404 Not Found HTTP response with JSON error details.
+*
+* @param {Context | ResponseOptions} contextOrOptions - Hono context or configuration options
+* @param {ResponseOptions?} options - Configuration options when context is provided
+* @returns {Response} A Response object with 404 status and JSON error body
+*
+* @example
+* ```typescript
+* import { notFound } from "../../lib";
+*
+* // Basic usage (legacy)
+* return notFound();
+*
+* // With custom message (legacy)
+* return notFound({
+*   message: "User not found"
+* });
+*
+* // With Hono context (new)
+* return notFound(c, { message: "User not found" });
+* ```
+*/
+function notFound(contextOrOptions = {}, options = {}) {
+	let finalOptions;
+	if ("req" in contextOrOptions) finalOptions = options;
+	else finalOptions = contextOrOptions;
+	return Response.json({
+		message: finalOptions.message || "Not Found",
+		status: 404,
+		timestamp: (/* @__PURE__ */ new Date()).toISOString()
+	}, {
+		status: 404,
+		headers: {
+			"Content-Type": "application/json",
+			...finalOptions.headers
+		}
+	});
+}
+/**
+* Creates a standardized 500 Internal Server Error HTTP response with JSON error details.
+*
+* @param {Context | ResponseOptions} contextOrOptions - Hono context or configuration options
+* @param {ResponseOptions?} options - Configuration options when context is provided
+* @returns {Response} A Response object with 500 status and JSON error body
+*
+* @example
+* ```typescript
+* import { internalServerError } from "../../lib";
+*
+* // Basic usage (legacy)
+* return internalServerError();
+*
+* // With custom message (legacy)
+* return internalServerError({
+*   message: "Database connection failed"
+* });
+*
+* // With Hono context (new)
+* return internalServerError(c, { message: "Database connection failed" });
+* ```
+*/
+function internalServerError(contextOrOptions = {}, options = {}) {
+	let finalOptions;
+	if ("req" in contextOrOptions) finalOptions = options;
+	else finalOptions = contextOrOptions;
+	return Response.json({
+		message: finalOptions.message || "Internal Server Error",
+		status: 500,
+		timestamp: (/* @__PURE__ */ new Date()).toISOString()
+	}, {
+		status: 500,
+		headers: {
+			"Content-Type": "application/json",
+			...finalOptions.headers
+		}
+	});
+}
+function badGateway(contextOrOptions = {}, options = {}) {
+	let finalOptions;
+	if ("req" in contextOrOptions) finalOptions = options;
+	else finalOptions = contextOrOptions;
+	return Response.json({
+		message: finalOptions.message || "Bad Gateway",
+		status: 502,
+		timestamp: (/* @__PURE__ */ new Date()).toISOString()
+	}, {
+		status: 502,
+		headers: {
+			"Content-Type": "application/json",
+			...finalOptions.headers
+		}
+	});
+}
+function unauthorized(contextOrOptions = {}, options = {}) {
+	let finalOptions;
+	if ("req" in contextOrOptions) finalOptions = options;
+	else finalOptions = contextOrOptions;
+	return Response.json({
+		message: finalOptions.message || "Unauthorized",
+		status: 401,
+		timestamp: (/* @__PURE__ */ new Date()).toISOString()
+	}, {
+		status: 401,
+		headers: {
+			"Content-Type": "application/json",
+			...finalOptions.headers
+		}
+	});
+}
+/**
+* Creates a custom HTTP error response with specified status code and JSON error details.
+* This function allows for flexible error responses with any valid HTTP status code.
+*
+* @param {Context | CustomResponseOptions} contextOrOptions - Hono context or configuration options
+* @param {CustomResponseOptionsWithContext?} options - Configuration options when context is provided
+* @returns {Response} A Response object with the specified status and JSON error body
+*
+* @example
+* ```typescript
+* import { customError } from "../../lib";
+*
+* // Custom 422 Unprocessable Entity error (legacy)
+* return customError({
+*   status: 422,
+*   message: "Validation failed",
+* });
+*
+* // Custom 429 Too Many Requests error with headers (legacy)
+* return customError({
+*   status: 429,
+*   message: "Rate limit exceeded",
+*   headers: {
+*     "Retry-After": "3600"
+*   }
+* });
+*
+* // With Hono context (new)
+* return customError(c, {
+*   status: 422,
+*   message: "Validation failed"
+* });
+* ```
+*/
+function customError(contextOrOptions, options) {
+	let finalOptions;
+	if ("req" in contextOrOptions) {
+		if (!options) throw new Error("Options parameter is required when using Hono context");
+		finalOptions = options;
+	} else finalOptions = contextOrOptions;
+	return Response.json({
+		message: finalOptions.message,
+		status: finalOptions.status,
+		timestamp: (/* @__PURE__ */ new Date()).toISOString()
+	}, {
+		status: finalOptions.status,
+		headers: {
+			"Content-Type": "application/json",
+			...finalOptions.headers
+		}
+	});
+}
+
+//#endregion
+//#region src/hostnames.ts
+function isStoreSubdomainHostname(hostname) {
+	return hostname === "ucd-store.ucdjs.dev" || hostname === "preview.ucd-store.ucdjs.dev" || hostname === "ucd-store.localhost";
+}
+
+//#endregion
+//#region src/strict.ts
+function strictJSONResponse(c, schema, data, statusCode) {
+	const validatedResponse = schema.safeParse(data);
+	if (!validatedResponse.success) return customError({
+		status: 400,
+		message: `Invalid response data: ${validatedResponse.error.message}`
+	});
+	return c.json(validatedResponse.data, statusCode);
+}
+
+//#endregion
+//#region src/tasks.ts
+const MAX_TAR_SIZE_BYTES = 10 * 1024 * 1024;
+const MAX_WORKFLOW_INSTANCE_ID_LENGTH = 100;
+const ALLOWED_STRING_ID_PATTERN = "^\\w[\\w-]*$";
+const ALLOWED_WORKFLOW_INSTANCE_ID_REGEX = new RegExp(ALLOWED_STRING_ID_PATTERN);
+function makeManifestUploadId(version, now = Date.now) {
+	return `manifest-upload-${version.replace(/\./g, "-")}-${now()}`;
+}
+function isValidWorkflowInstanceId(id) {
+	return id.length <= MAX_WORKFLOW_INSTANCE_ID_LENGTH && ALLOWED_WORKFLOW_INSTANCE_ID_REGEX.test(id);
+}
+function buildR2Key(version, workflowId) {
+	return `manifest-tars/${version}/${workflowId}.tar`;
+}
+
+//#endregion
+export { ALLOWED_STRING_ID_PATTERN, MAX_TAR_SIZE_BYTES, MAX_WORKFLOW_INSTANCE_ID_LENGTH, badGateway, badRequest, buildR2Key, clearCacheEntry, customError, forbidden, getApiOriginForEnvironment, internalServerError, isStoreSubdomainHostname, isValidWorkflowInstanceId, makeManifestUploadId, notFound, strictJSONResponse, unauthorized };

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@ucdjs-internal/worker-utils",
+  "version": "0.0.1-beta.1",
+  "type": "module",
+  "author": {
+    "name": "Lucas Nørgård",
+    "email": "lucasnrgaard@gmail.com",
+    "url": "https://luxass.dev"
+  },
+  "license": "MIT",
+  "homepage": "https://github.com/ucdjs/ucd",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ucdjs/ucd.git",
+    "directory": "packages/worker-utils"
+  },
+  "bugs": {
+    "url": "https://github.com/ucdjs/ucd/issues"
+  },
+  "exports": {
+    ".": "./dist/index.mjs",
+    "./package.json": "./package.json"
+  },
+  "types": "./dist/index.d.mts",
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=22.18"
+  },
+  "peerDependencies": {
+    "hono": "4.11.9",
+    "zod": "4.3.6"
+  },
+  "dependencies": {
+    "@ucdjs-internal/shared": "0.1.1-beta.1",
+    "@ucdjs/schemas": "0.1.1-beta.1"
+  },
+  "devDependencies": {
+    "@luxass/eslint-config": "7.2.0",
+    "eslint": "10.0.0",
+    "hono": "4.11.9",
+    "publint": "0.3.17",
+    "tsdown": "0.20.3",
+    "typescript": "5.9.3",
+    "vitest-testdirs": "4.4.2",
+    "zod": "4.3.6",
+    "@ucdjs-tooling/tsdown-config": "1.0.0",
+    "@ucdjs-tooling/tsconfig": "1.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsdown --tsconfig=./tsconfig.build.json",
+    "dev": "tsdown --watch",
+    "clean": "git clean -xdf dist node_modules",
+    "lint": "eslint .",
+    "typecheck": "tsc --noEmit -p tsconfig.build.json"
+  }
+}