hono-utils 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,357 @@
+import * as hono from 'hono';
+import { Env, Context } from 'hono';
+import { Logger, Details } from 'hierarchical-area-logger';
+import * as hono_utils_http_status from 'hono/utils/http-status';
+import { ContentfulStatusCode, SuccessStatusCode, ClientErrorStatusCode } from 'hono/utils/http-status';
+import z$1, { z, ZodObject } from 'zod';
+import { Message, MessageBatch, Queue } from '@cloudflare/workers-types';
+import * as hono_utils_types from 'hono/utils/types';
+
+type HonoLoggerVariables = {
+    logger: Logger;
+    eventId: string;
+};
+/**
+ * Logger middleware
+ *
+ * @description
+ * This middleware sets up a logger.
+ *
+ * @param details - Details to pass to the logger
+ * @param parentEventIdHeader - Header name to use for parent event ID
+ *
+ * @example
+ * ```ts
+ * app.use('*', logger(
+ * {
+ *   service: 'logger',
+ * },
+ * parentEventIdHeader: 'parent-event-id',
+ * ));
+ * ```
+ */
+declare const logger: (details: Details, parentEventIdHeader?: string) => hono.MiddlewareHandler<{
+    Variables: HonoLoggerVariables;
+}, string, {}, Response>;
+
+type WrappableMiddleware<V extends Env> = (c: Context<V>, loggerFunctions: ReturnType<Logger['getArea']> & Pick<Logger, 'eventId' | 'parentEventId' | 'dump'>) => Promise<void>;
+/**
+ * Wraps middleware with logger. Logger should be initialized before middleware.
+ *
+ * @param name - Name of the middleware
+ * @param middleware - Middleware function
+ *
+ * @example
+ * ```ts
+ * app.use('*', logger(
+ * {
+ *   service: 'logger',
+ * },
+ * parentEventIdHeader: 'parent-event-id',
+ * ));
+ *
+ * app.use('*', withLogger('middlewareName', (c, { info }) => {
+ *   info('Middleware initialized');
+ * }));
+ * ```
+ */
+declare const withLogger: <V extends Env>(name: string, middleware: WrappableMiddleware<V>) => hono.MiddlewareHandler<any, string, {}, Response>;
+
+/**
+ * @description
+ * Validator middleware for JSON data.
+ *
+ * @param schema - Zod schema for validation
+ *
+ * @example
+ * ```ts
+ * app.post('/user', jsonValidator(z.object({
+ *   name: z.string(),
+ *   age: z.number(),
+ * })), (c) => {
+ *   const { name, age } = await c.req.valid('json');
+ *   return c.json({ name, age });
+ * });
+ * ```
+ */
+declare const jsonValidator: <T extends z.ZodRawShape>(schema: z.ZodObject<T>) => hono.MiddlewareHandler<any, string, {
+    in: {
+        json: z.core.$InferObjectOutput<T, {}> extends infer T_1 ? T_1 extends z.core.$InferObjectOutput<T, {}> ? T_1 extends Promise<infer PR> ? PR extends Response | hono.TypedResponse<any, any, any> ? never : PR : T_1 extends Response | hono.TypedResponse<any, any, any> ? never : T_1 : never : never;
+    };
+    out: {
+        json: z.core.$InferObjectOutput<T, {}> extends infer T_2 ? T_2 extends z.core.$InferObjectOutput<T, {}> ? T_2 extends Promise<infer PR> ? PR extends Response | hono.TypedResponse<any, any, any> ? never : PR : T_2 extends Response | hono.TypedResponse<any, any, any> ? never : T_2 : never : never;
+    };
+}, z.core.$InferObjectOutput<T, {}> extends infer T_3 ? T_3 extends z.core.$InferObjectOutput<T, {}> ? T_3 extends Promise<infer PR_1> ? PR_1 extends hono.TypedResponse<infer T_4, infer S extends hono_utils_http_status.StatusCode, infer F extends string> ? hono.TypedResponse<T_4, S, F> : PR_1 extends Response ? PR_1 : PR_1 extends undefined ? never : never : T_3 extends hono.TypedResponse<infer T_5, infer S_1 extends hono_utils_http_status.StatusCode, infer F_1 extends string> ? hono.TypedResponse<T_5, S_1, F_1> : T_3 extends Response ? T_3 : T_3 extends undefined ? never : never : never : never>;
+
+type HonoIsBotVariables = {
+    isBot: boolean;
+};
+/**
+ * Middleware to detect and optionally block requests based on Cloudflare's Bot Management score.
+ * @param {Object} options - Configuration options for bot detection.
+ * @param {number} [options.threshold=49] - The bot score threshold (1-100).
+ * Cloudflare scores below this value are treated as bots. A lower score indicates a higher
+ * probability that the request is automated.
+ * @param {boolean} [options.allowVerifiedBot] - If true, the middleware strictly requires
+ * bots to be "verified" (e.g., Googlebot, Bingbot).
+ * Note: If this is enabled, non-verified bots will be blocked regardless of their score.
+ * @returns {MiddlewareHandler} A Hono middleware handler.
+ * @throws {HTTPException} Throws a 401 "Bot detected" error if the score is below the
+ * threshold or if a non-verified bot is detected when `allowVerifiedBot` is true.
+ * @example
+ * ```ts
+ * const app = new Hono<{ Variables: HonoIsBotVariables }>();
+ * // Block suspected bots with a score lower than 50
+ * app.use('/api/*', isBot({ threshold: 50, allowVerifiedBot: true }));
+ * ```
+ */
+declare const isBot: ({ threshold, allowVerifiedBot, }: {
+    threshold: number;
+    allowVerifiedBot?: boolean;
+}) => hono.MiddlewareHandler<{
+    Variables: HonoIsBotVariables;
+}, string, {}, Response>;
+
+type HonoLanguageVariables = {
+    language: string;
+};
+type I18nShape = {
+    [key: string]: I18nShape | string;
+};
+type HonoI18nVariables = {
+    t: ReturnType<typeof setI18n>;
+};
+/**
+ * Set i18n
+ *
+ * @param translations - Translations object
+ * @param language - Language
+ * @param defaultLanguage - Default language
+ */
+declare const setI18n: <T extends I18nShape>(translations: T, language: keyof T, defaultLanguage: string) => (input: string, params?: Record<string, string | number>, overrideLanguage?: keyof T) => string;
+/**
+ * I18n Middleware and Queue Factory.
+ * @description
+ * Sets up the `t` translation function in the Hono context.
+ * Note: Requires a preceding middleware to set the `language` variable.
+ * @template T - The shape of the translations object.
+ * @param translations - The dictionary of translations.
+ * @param defaultLanguage - The fallback language code.
+ * @returns An object containing the `middleware` for Hono and a `queue` helper for background tasks.
+ * @example
+ * ```ts
+ * const translations = { en: { hi: "Hi {{name}}" }, fr: { hi: "Salut {{name}}" } };
+ * // 1. Set language first
+ * app.use('*', async (c, next) => {
+ * c.set('language', 'en');
+ * await next();
+ * });
+ * // 2. Initialize i18n
+ * const { middleware } = i18n(translations, 'en');
+ * app.use('*', middleware);
+ * // 3. Use in routes
+ * app.get('/', (c) => c.text(c.var.t('hi', { name: 'User' })));
+ * ```
+ */
+declare const i18n: <T extends I18nShape>(translations: T, defaultLanguage: string) => {
+    middleware: hono.MiddlewareHandler<{
+        Variables: HonoLanguageVariables & HonoI18nVariables;
+    }, string, {}, Response>;
+    queue: (language?: keyof T) => (input: string, params?: Record<string, string | number>, overrideLanguage?: keyof T | undefined) => string;
+};
+
+type DataShape = Record<string, unknown>;
+
+type QueueSendParams = {
+  parentEventId?: string;
+  language?: string;
+};
+
+type GenericQueueDataParams = {
+  eventId: string;
+} & QueueSendParams;
+
+type GenericQueueData<Content extends DataShape> = {
+  handler: keyof Content;
+  content: Content[keyof Content];
+} & GenericQueueDataParams;
+
+interface Variables<Context> {
+  context: Context & Pick<Message, 'retry' | 'ack'>;
+  metadata: Omit<GenericQueueData<DataShape>, 'content'> &
+    Omit<Message, 'body' | 'retry' | 'ack'>;
+}
+
+interface Handler<Content, Context> {
+  (message: Content, context: Context): Promise<void>;
+}
+
+type MessageHandlers<QueueData extends DataShape, Context> = {
+  [Term in keyof QueueData]: Handler<QueueData[Term], Variables<Context>>;
+};
+
+interface ContextFn<Env, Context> {
+  (env: Env, params: GenericQueueDataParams): Context;
+}
+
+/**
+ * A type-safe wrapper for Cloudflare Worker Queues using Zod for validation.
+ * * This class orchestrates the relationship between incoming queue messages and
+ * specific logic handlers, ensuring that data is validated at the edge before
+ * reaching your business logic.
+ *
+ * @template Schema - The Zod schema defining the message shapes.
+ * @template Environment - The Cloudflare Worker environment bindings (Env).
+ * @template Context - The application context derived from the environment and message.
+ */
+declare class QueueHandler<Schema extends ZodObject<any>, Environment, Context> {
+    private readonly config;
+    private readonly handlers;
+    /**
+     * @param config - Configuration object.
+     * @param config.schema - The Zod schema used to parse and validate incoming message content.
+     * @param config.setContext - A factory function to generate context (e.g., DB connections, logging) for each message.
+     */
+    constructor(config: {
+        schema: Schema;
+        setContext: ContextFn<Environment, Context>;
+    });
+    /**
+     * Registers a specific processing function for a given message type (handlerName).
+     * * @template {keyof z.infer<Schema>} HandlerName - A specific key defined in your Zod schema.
+     * @param handlerName - The key identifying which handler to use.
+     * @param handler - The asynchronous logic to execute when this message type is received.
+     * @returns The current instance for fluent chaining.
+     */
+    addHandler<HandlerName extends keyof z.infer<Schema>>(handlerName: HandlerName, handler: Handler<z.infer<Schema>[HandlerName], Variables<Context>>): this;
+    /**
+     * Generates the Cloudflare Worker queue consumer function.
+     * * This handles the batch processing loop, parses the message body against the
+     * schema, injects context, and manages concurrency via `Promise.allSettled`.
+     * * @returns An async function compatible with the Cloudflare `queue` export.
+     */
+    getConsumer(): (batch: MessageBatch<GenericQueueData<z.infer<Schema>>>, env: Environment) => Promise<void>;
+    /**
+     * Creates a factory function for sending typed messages to a specific queue.
+     * * @param queue - The Cloudflare Queue binding (e.g., `env.MY_QUEUE`).
+     * @param params - Global parameters to include in every message (e.g., trace IDs).
+     * @returns A producer function that accepts a `handler` key and the corresponding typed content.
+     */
+    getProducer(queue: Queue<unknown>, params: QueueSendParams): <HandlerName extends keyof z.infer<Schema>>(handler: HandlerName, content: z.infer<Schema>[HandlerName]) => Promise<void>;
+}
+
+/**
+ * Middleware to initialize a Queue producer and attach it to the Hono context.
+ * @description
+ * This middleware manages Cloudflare Queue interactions. If `finalizeLogHandler` is provided,
+ * it will automatically capture the current logger state and send it to the queue after
+ * the request is processed (post-`next()`).
+ * @param options.name - The name of the Queue binding defined in your `wrangler.toml`.
+ * @param options.queueHandler - An instance of your custom QueueHandler.
+ * @param [options.finalizeLogHandler] - Optional: The specific message type/key to use when finalizing the log.
+ * @example
+ * ```ts
+ * // OPTIONAL
+ * app.use('*', logger(
+ *  {
+ *   service: 'logger',
+ *  },
+ *  parentEventIdHeader: 'parent-event-id',
+ * ));
+ *
+ * app.use('*', queue({
+ *  name: 'queue',
+ *  queueHandler: new QueueHandler(),
+ *  finalizeLogHandler: 'log'
+ * }));
+ * ```
+ */
+declare const queue: <Schema extends ZodObject<any>, Environment, Context, Key extends keyof z$1.infer<Schema>>({ name, queueHandler, finalizeLogHandler, }: {
+    name: string;
+    queueHandler: QueueHandler<Schema, Environment, Context>;
+    finalizeLogHandler?: Key;
+}) => hono.MiddlewareHandler<{
+    Bindings: Record<string, Queue>;
+    Variables: HonoLoggerVariables & Record<string, ReturnType<QueueHandler<Schema, Environment, Context>["getProducer"]>>;
+}, string, {}, Response>;
+
+type HonoResponseVariables = {
+    res: ReturnType<typeof setResponseHandlers>;
+};
+declare const setResponseHandlers: (c: Context) => {
+    raw: <T extends {
+        status?: ContentfulStatusCode;
+    }>(data: T) => Response & hono.TypedResponse<hono_utils_types.JSONParsed<Omit<T, "status">, bigint | readonly bigint[]>, 100 | 102 | 103 | 200 | 201 | 202 | 203 | 206 | 207 | 208 | 226 | 300 | 301 | 302 | 303 | 305 | 306 | 307 | 308 | 400 | 401 | 402 | 403 | 404 | 405 | 406 | 407 | 408 | 409 | 410 | 411 | 412 | 413 | 414 | 415 | 416 | 417 | 418 | 421 | 422 | 423 | 424 | 425 | 426 | 428 | 429 | 431 | 451 | 500 | 501 | 502 | 503 | 504 | 505 | 506 | 507 | 508 | 510 | 511 | -1, "json">;
+    success: <T extends object>(message: string, data?: T, status?: SuccessStatusCode) => Response & hono.TypedResponse<{
+        message: string;
+    }, 100 | 102 | 103 | 200 | 201 | 202 | 203 | 206 | 207 | 208 | 226 | 300 | 301 | 302 | 303 | 305 | 306 | 307 | 308 | 400 | 401 | 402 | 403 | 404 | 405 | 406 | 407 | 408 | 409 | 410 | 411 | 412 | 413 | 414 | 415 | 416 | 417 | 418 | 421 | 422 | 423 | 424 | 425 | 426 | 428 | 429 | 431 | 451 | 500 | 501 | 502 | 503 | 504 | 505 | 506 | 507 | 508 | 510 | 511 | -1, "json">;
+    error: (message: string, status: ClientErrorStatusCode) => never;
+    websocket: (socket: WebSocket) => Response;
+};
+/**
+ * Response Middleware
+ * @description
+ * Injects a `res` object into the Hono context (`c.var.res`).
+ * This ensures all outgoing responses follow a consistent schema and include
+ * tracing metadata (like `eventId`) automatically.
+ * @example
+ * ```ts
+ * app.use('*', response());
+ * ```
+ */
+declare const response: hono.MiddlewareHandler<{
+    Variables: HonoResponseVariables & HonoLoggerVariables;
+}, string, {}, Response>;
+
+/**
+ * Derives a secure hex-encoded hash from an input string using PBKDF2-HMAC-SHA256.
+ * * @example
+ * const passwordHash = await hash("myPassword123", "random-salt-string");
+ * * @param {string} input - The plain-text string to hash.
+ * @param {string} salt - The salt string used to randomize the hash.
+ * @param {number} [iterations=600000] - The CPU cost factor. Default is 600,000.
+ * @returns {Promise<string>} A hex-encoded string representing the derived key.
+ */
+declare function hash$1(input: string, salt: string, iterations?: number): Promise<string>;
+/**
+ * Verifies if an input string matches a stored hash using a constant-time comparison.
+ * This prevents timing attacks by ensuring the execution time does not reveal
+ * how many characters of the hash were correct.
+ * * @param {string} input - The plain-text string to verify.
+ * @param {string} salt - The salt used during the original hashing.
+ * @param {string} storedHash - The hex-encoded hash previously stored in the database.
+ * @param {number} iterations - The iteration count used for the original hash.
+ * @returns {Promise<boolean>} Resolves to `true` if the input matches the hash, otherwise `false`.
+ */
+declare function verify(input: string, salt: string, storedHash: string, iterations: number): Promise<boolean>;
+
+declare const pbkdf2_verify: typeof verify;
+declare namespace pbkdf2 {
+  export { hash$1 as hash, pbkdf2_verify as verify };
+}
+
+/**
+ * Generates a cryptographically strong random salt.
+ */
+declare function generateSalt(length?: number): string;
+/**
+ * Calculates the SHA hash of the given input string.
+ * @param algorithm - The algorithm to be used for hashing. Defaults to 256.
+ * @param pepper - An optional string to be prepended to the input before hashing.
+ * @param salt - An optional string to be appended to the input before hashing.
+ * @returns A Promise that resolves to the hashed string.
+ */
+declare function hash({ input, algorithm, pepper, salt, }: {
+    input: string;
+    algorithm: 'SHA-256' | 'SHA-384' | 'SHA-512';
+    pepper?: string;
+    salt?: string;
+}): Promise<string>;
+
+declare const sha_generateSalt: typeof generateSalt;
+declare const sha_hash: typeof hash;
+declare namespace sha {
+  export { sha_generateSalt as generateSalt, sha_hash as hash };
+}
+
+export { type ContextFn, type HonoI18nVariables, type HonoIsBotVariables, type HonoLanguageVariables, type HonoLoggerVariables, type HonoResponseVariables, type MessageHandlers, pbkdf2 as PBKDF2, QueueHandler, sha as SHA, type WrappableMiddleware, i18n, isBot, jsonValidator, logger, queue, response, withLogger };