h3 - npm Package Compare versions

Comparing version 1.8.2 to 1.9.0

dist/index.d.ts

@@ -53,3 +53,16 @@ import { QueryObject } from 'ufo';
 }
+/**
+ * Checks if the input is an H3Event object.
+ * @param input - The input to check.
+ * @returns True if the input is an H3Event object, false otherwise.
+ * @see H3Event
+ */
 declare function isEvent(input: any): input is H3Event;
+/**
+ * Creates a new H3Event instance from the given Node.js request and response objects.
+ * @param req - The NodeIncomingMessage object.
+ * @param res - The NodeServerResponse object.
+ * @returns A new H3Event instance.
+ * @see H3Event
+ */
 declare function createEvent(req: IncomingMessage, res: ServerResponse): H3Event;
@@ -62,2 +75,7 @@
 declare function defineResponseMiddleware<Request extends EventHandlerRequest = EventHandlerRequest>(fn: _ResponseMiddleware<Request>): _ResponseMiddleware<Request>;
+/**
+ * Checks if any kind of input is an event handler.
+ * @param input The input to check.
+ * @returns True if the input is an event handler, false otherwise.
+ */
 declare function isEventHandler(input: any): input is EventHandler;
@@ -167,2 +185,3 @@ declare function toEventHandler(input: any, _?: any, _route?: string): EventHandler;
     query?: QueryObject;
+    routerParams?: Record<string, string>;
 }
@@ -184,5 +203,5 @@ type InferEventInput<Key extends keyof EventHandlerRequest, Event extends H3Event, T> = void extends T ? (Event extends H3Event<infer E> ? E[Key] : never) : T;
 type LazyEventHandler = () => EventHandler | Promise<EventHandler>;
-type RequestHeaders = {
-    [name: string]: string | undefined;
-};
+type RequestHeaders = Partial<Record<HTTPHeaderName, string | undefined>>;
+type _HTTPHeaderName = "WWW-Authenticate" | "Authorization" | "Proxy-Authenticate" | "Proxy-Authorization" | "Age" | "Cache-Control" | "Clear-Site-Data" | "Expires" | "Pragma" | "Accept-CH" | "Critical-CH" | "Sec-CH-UA" | "Sec-CH-UA-Arch" | "Sec-CH-UA-Bitness" | "Sec-CH-UA-Full-Version-List" | "Sec-CH-UA-Mobile" | "Sec-CH-UA-Model" | "Sec-CH-UA-Platform" | "Sec-CH-UA-Platform-Version" | "Sec-CH-UA-Prefers-Color-Scheme" | "Sec-CH-UA-Prefers-Reduced-Motion" | "Downlink" | "ECT" | "RTT" | "Save-Data" | "Last-Modified" | "ETag" | "If-Match" | "If-None-Match" | "If-Modified-Since" | "If-Unmodified-Since" | "Vary" | "Connection" | "Keep-Alive" | "Accept" | "Accept-Encoding" | "Accept-Language" | "Expect" | "Max-Forwards" | "Cookie" | "Set-Cookie" | "Access-Control-Allow-Origin" | "Access-Control-Allow-Credentials" | "Access-Control-Allow-Headers" | "Access-Control-Allow-Methods" | "Access-Control-Expose-Headers" | "Access-Control-Max-Age" | "Access-Control-Request-Headers" | "Access-Control-Request-Method" | "Origin" | "Timing-Allow-Origin" | "Content-Disposition" | "Content-Length" | "Content-Type" | "Content-Encoding" | "Content-Language" | "Content-Location" | "Forwarded" | "X-Forwarded-For" | "X-Forwarded-Host" | "X-Forwarded-Proto" | "Via" | "Location" | "Refresh" | "From" | "Host" | "Referer" | "Referrer-Policy" | "User-Agent" | "Allow" | "Server" | "Accept-Ranges" | "Range" | "If-Range" | "Content-Range" | "Cross-Origin-Embedder-Policy" | "Cross-Origin-Opener-Policy" | "Cross-Origin-Resource-Policy" | "Content-Security-Policy" | "Content-Security-Policy-Report-Only" | "Expect-CT" | "Origin-Isolation" | "Permissions-Policy" | "Strict-Transport-Security" | "Upgrade-Insecure-Requests" | "X-Content-Type-Options" | "X-Frame-Options" | "X-Permitted-Cross-Domain-Policies" | "X-Powered-By" | "X-XSS-Protection" | "Sec-Fetch-Site" | "Sec-Fetch-Mode" | "Sec-Fetch-User" | "Sec-Fetch-Dest" | "Sec-Purpose" | "Service-Worker-Navigation-Preload" | "Last-Event-ID" | "NEL" | "Ping-From" | "Ping-To" | "Report-To" | "Transfer-Encoding" | "TE" | "Trailer" | "Sec-WebSocket-Key" | "Sec-WebSocket-Extensions" | "Sec-WebSocket-Accept" | "Sec-WebSocket-Protocol" | "Sec-WebSocket-Version" | "Accept-Push-Policy" | "Accept-Signature" | "Alt-Svc" | "Alt-Used" | "Date" | "Early-Data" | "Link" | "Push-Policy" | "Retry-After" | "Signature" | "Signed-Headers" | "Server-Timing" | "Service-Worker-Allowed" | "SourceMap" | "Upgrade" | "X-DNS-Prefetch-Control" | "X-Pingback" | "X-Requested-With" | "X-Robots-Tag";
+type HTTPHeaderName = _HTTPHeaderName | Lowercase<_HTTPHeaderName> | (string & {});
 
@@ -197,7 +216,7 @@ /**
  * @property {boolean} unhandled - Indicates if the error was unhandled and auto captured.
- * @property {any} data - An extra data that will be included in the response.
+ * @property {DataT} data - An extra data that will be included in the response.
  *                         This can be used to pass additional information about the error.
  * @property {boolean} internal - Setting this property to `true` will mark the error as an internal error.
  */
-declare class H3Error extends Error {
+declare class H3Error<DataT = any> extends Error {
     static __h3_error__: boolean;
@@ -208,3 +227,3 @@ statusCode: number;
     statusMessage?: string;
-    data?: any;
+    data?: DataT;
     cause?: unknown;
@@ -214,3 +233,3 @@ constructor(message: string, opts?: {
     });
-    toJSON(): Pick<H3Error, "data" | "statusCode" | "statusMessage" | "message">;
+    toJSON(): Pick<H3Error<DataT>, "data" | "statusCode" | "statusMessage" | "message">;
 }
@@ -223,3 +242,3 @@ /**
  */
-declare function createError(input: string | (Partial<H3Error> & {
+declare function createError<DataT = any>(input: string | (Partial<H3Error<DataT>> & {
     status?: number;
@@ -287,2 +306,7 @@ statusText?: string;
 
+/**
+ * Prefixes and executes a handler with a base path.
+ * @param base The base path to prefix. When set to an empty string, the handler will be run as is.
+ * @param handler The event handler to use with the adapted path.
+ */
 declare function useBase(base: string, handler: EventHandler): EventHandler;
@@ -307,4 +331,4 @@
  * Reads request body and tries to safely parse using [destr](https://github.com/unjs/destr).
- * @param event {H3Event} H3 event passed by h3 handler
- * @param encoding {Encoding} encoding="utf-8" - The character encoding to use.
+ * @param event H3 event passed by h3 handler
+ * @param encoding The character encoding to use, defaults to 'utf-8'.
  *
@@ -320,8 +344,48 @@ * @return {*} The `Object`, `Array`, `String`, `Number`, `Boolean`, or `null` value corresponding to the request JSON body
 }): Promise<_T>;
+/**
+ * Tries to read the request body via `readBody`, then uses the provided validation function and either throws a validation error or returns the result.
+ * @param event The H3Event passed by the handler.
+ * @param validate The function to use for body validation. It will be called passing the read request body. If the result is not false, the parsed body will be returned.
+ * @throws If the validation function returns `false` or throws, a validation error will be thrown.
+ * @return {*} The `Object`, `Array`, `String`, `Number`, `Boolean`, or `null` value corresponding to the request JSON body.
+ * @see {readBody}
+ *
+ * ```ts
+ * // With a custom validation function
+ * const body = await readValidatedBody(event, (body) => {
+ *   return typeof body === "object" && body !== null
+ * })
+ *
+ * // With a zod schema
+ * import { z } from 'zod'
+ * const objectSchema = z.object()
+ * const body = await readValidatedBody(event, objectSchema.safeParse)
+ * ```
+ */
 declare function readValidatedBody<T, Event extends H3Event = H3Event, _T = InferEventInput<"body", Event, T>>(event: Event, validate: ValidateFunction<_T>): Promise<_T>;
+/**
+ * Tries to read and parse the body of a an H3Event as multipart form.
+ * @param event The H3Event object to read multipart form from.
+ *
+ * @return The parsed form data. If no form could be detected because the content type is not multipart/form-data or no boundary could be found.
+ *
+ * ```ts
+ * const formData = await readMultipartFormData(event)
+ * // The result could look like:
+ * // [
+ * //   {
+ * //     "data": "other",
+ * //     "name": "baz",
+ * //   },
+ * //   {
+ * //     "data": "something",
+ * //     "name": "some-other-data",
+ * //   },
+ * // ]
+ * ```
+ */
 declare function readMultipartFormData(event: H3Event): Promise<MultiPartData[] | undefined>;
 /**
- * Constructs a FormData object from an event.
- * @param event {H3Event}
- * @returns {FormData}
+ * Constructs a FormData object from an event, after converting it to a a web request.
+ * @param event The H3Event object to read the form data from.
  *
@@ -337,2 +401,7 @@ * ```ts
 declare function readFormData(event: H3Event): Promise<FormData>;
+/**
+ * Captures a stream from a request.
+ * @param event The H3Event object containing the request information.
+ * @returns Undefined if the request can't transport a payload, otherwise a ReadableStream of the request body.
+ */
 declare function getRequestWebStream(event: H3Event): undefined | ReadableStream;
@@ -374,4 +443,11 @@
 declare function getValidatedQuery<T, Event extends H3Event = H3Event, _T = InferEventInput<"query", Event, T>>(event: Event, validate: ValidateFunction<_T>): Promise<_T>;
-declare function getRouterParams(event: H3Event): NonNullable<H3Event["context"]["params"]>;
-declare function getRouterParam(event: H3Event, name: string): string | undefined;
+declare function getRouterParams(event: H3Event, opts?: {
+    decode?: boolean;
+}): NonNullable<H3Event["context"]["params"]>;
+declare function getValidatedRouterParams<T, Event extends H3Event = H3Event, _T = InferEventInput<"routerParams", Event, T>>(event: Event, validate: ValidateFunction<_T>, opts?: {
+    decode?: boolean;
+}): Promise<_T>;
+declare function getRouterParam(event: H3Event, name: string, opts?: {
+    decode?: boolean;
+}): string | undefined;
 /**
@@ -385,3 +461,3 @@ * @deprecated Directly use `event.method` instead.
 declare const getHeaders: typeof getRequestHeaders;
-declare function getRequestHeader(event: H3Event, name: string): RequestHeaders[string];
+declare function getRequestHeader(event: H3Event, name: HTTPHeaderName): RequestHeaders[string];
 declare const getHeader: typeof getRequestHeader;
@@ -466,2 +542,19 @@ declare function getRequestHost(event: H3Event, opts?: {
 
+interface RequestFingerprintOptions {
+    /** @default SHA-1 */
+    hash?: false | "SHA-1";
+    /** @default `true` */
+    ip?: boolean;
+    /** @default `false` */
+    xForwardedFor?: boolean;
+    /** @default `false` */
+    method?: boolean;
+    /** @default `false` */
+    path?: boolean;
+    /** @default `false` */
+    userAgent?: boolean;
+}
+/** @experimental Behavior of this utility might change in the future versions */
+declare function getRequestFingerprint(event: H3Event, opts?: RequestFingerprintOptions): Promise<string | null>;
+
 type Duplex = "half" | "full";
@@ -506,10 +599,10 @@ interface ProxyOptions {
 declare function getResponseHeaders(event: H3Event): ReturnType<H3Event["res"]["getHeaders"]>;
-declare function getResponseHeader(event: H3Event, name: string): ReturnType<H3Event["res"]["getHeader"]>;
+declare function getResponseHeader(event: H3Event, name: HTTPHeaderName): ReturnType<H3Event["res"]["getHeader"]>;
 declare function setResponseHeaders(event: H3Event, headers: Record<string, Parameters<OutgoingMessage["setHeader"]>[1]>): void;
 declare const setHeaders: typeof setResponseHeaders;
-declare function setResponseHeader(event: H3Event, name: string, value: Parameters<OutgoingMessage["setHeader"]>[1]): void;
+declare function setResponseHeader(event: H3Event, name: HTTPHeaderName, value: Parameters<OutgoingMessage["setHeader"]>[1]): void;
 declare const setHeader: typeof setResponseHeader;
 declare function appendResponseHeaders(event: H3Event, headers: Record<string, string>): void;
 declare const appendHeaders: typeof appendResponseHeaders;
-declare function appendResponseHeader(event: H3Event, name: string, value: string): void;
+declare function appendResponseHeader(event: H3Event, name: HTTPHeaderName, value: string): void;
 declare const appendHeader: typeof appendResponseHeader;
@@ -522,3 +615,3 @@ /**
 declare function clearResponseHeaders(event: H3Event, headerNames?: string[]): void;
-declare function removeResponseHeader(event: H3Event, name: string): void;
+declare function removeResponseHeader(event: H3Event, name: HTTPHeaderName): void;
 declare function isStream(data: any): data is Readable | ReadableStream;
@@ -598,2 +691,2 @@ declare function isWebResponse(data: any): data is Response;
 
-export { type AddRouteShortcuts, type App, type AppOptions, type AppUse, type CacheConditions, type CreateRouterOptions, type Duplex, type DynamicEventHandler, type Encoding, type EventHandler, type EventHandlerObject, type EventHandlerRequest, type EventHandlerResponse, type H3CorsOptions, H3Error, H3Event, type H3EventContext, H3Headers, H3Response, type HTTPMethod, type InferEventInput, type InputLayer, type InputStack, type Layer, type LazyEventHandler, MIMES, type Matcher, type MultiPartData, type NodeEventContext, type NodeListener, type NodeMiddleware, type NodePromisifiedHandler, type PlainHandler, type PlainRequest, type PlainResponse, type ProxyOptions, type RequestHeaders, type RouteNode, type Router, type RouterMethod, type RouterUse, type ServeStaticOptions, type Session, type SessionConfig, type SessionData, type Stack, type StaticAssetMeta, type ValidateFunction, type ValidateResult, type WebEventContext, type WebHandler, type _RequestMiddleware, type _ResponseMiddleware, appendCorsHeaders, appendCorsPreflightHeaders, appendHeader, appendHeaders, appendResponseHeader, appendResponseHeaders, assertMethod, callNodeListener, clearResponseHeaders, clearSession, createApp, createAppEventHandler, createError, createEvent, createRouter, defaultContentType, defineEventHandler, defineLazyEventHandler, defineNodeListener, defineNodeMiddleware, defineRequestMiddleware, defineResponseMiddleware, deleteCookie, dynamicEventHandler, eventHandler, fetchWithEvent, fromNodeMiddleware, fromPlainHandler, fromWebHandler, getCookie, getHeader, getHeaders, getMethod, getProxyRequestHeaders, getQuery, getRequestHeader, getRequestHeaders, getRequestHost, getRequestIP, getRequestPath, getRequestProtocol, getRequestURL, getRequestWebStream, getResponseHeader, getResponseHeaders, getResponseStatus, getResponseStatusText, getRouterParam, getRouterParams, getSession, getValidatedQuery, handleCacheHeaders, handleCors, isCorsOriginAllowed, isError, isEvent, isEventHandler, isMethod, isPreflightRequest, isStream, isWebResponse, lazyEventHandler, parseCookies, promisifyNodeListener, proxyRequest, readBody, readFormData, readMultipartFormData, readRawBody, readValidatedBody, removeResponseHeader, sanitizeStatusCode, sanitizeStatusMessage, sealSession, send, sendError, sendNoContent, sendProxy, sendRedirect, sendStream, sendWebResponse, serveStatic, setCookie, setHeader, setHeaders, setResponseHeader, setResponseHeaders, setResponseStatus, splitCookiesString, toEventHandler, toNodeListener, toPlainHandler, toWebHandler, toWebRequest, unsealSession, updateSession, use, useBase, useSession, writeEarlyHints };
+export { type AddRouteShortcuts, type App, type AppOptions, type AppUse, type CacheConditions, type CreateRouterOptions, type Duplex, type DynamicEventHandler, type Encoding, type EventHandler, type EventHandlerObject, type EventHandlerRequest, type EventHandlerResponse, type H3CorsOptions, H3Error, H3Event, type H3EventContext, H3Headers, H3Response, type HTTPHeaderName, type HTTPMethod, type InferEventInput, type InputLayer, type InputStack, type Layer, type LazyEventHandler, MIMES, type Matcher, type MultiPartData, type NodeEventContext, type NodeListener, type NodeMiddleware, type NodePromisifiedHandler, type PlainHandler, type PlainRequest, type PlainResponse, type ProxyOptions, type RequestFingerprintOptions, type RequestHeaders, type RouteNode, type Router, type RouterMethod, type RouterUse, type ServeStaticOptions, type Session, type SessionConfig, type SessionData, type Stack, type StaticAssetMeta, type ValidateFunction, type ValidateResult, type WebEventContext, type WebHandler, type _RequestMiddleware, type _ResponseMiddleware, appendCorsHeaders, appendCorsPreflightHeaders, appendHeader, appendHeaders, appendResponseHeader, appendResponseHeaders, assertMethod, callNodeListener, clearResponseHeaders, clearSession, createApp, createAppEventHandler, createError, createEvent, createRouter, defaultContentType, defineEventHandler, defineLazyEventHandler, defineNodeListener, defineNodeMiddleware, defineRequestMiddleware, defineResponseMiddleware, deleteCookie, dynamicEventHandler, eventHandler, fetchWithEvent, fromNodeMiddleware, fromPlainHandler, fromWebHandler, getCookie, getHeader, getHeaders, getMethod, getProxyRequestHeaders, getQuery, getRequestFingerprint, getRequestHeader, getRequestHeaders, getRequestHost, getRequestIP, getRequestPath, getRequestProtocol, getRequestURL, getRequestWebStream, getResponseHeader, getResponseHeaders, getResponseStatus, getResponseStatusText, getRouterParam, getRouterParams, getSession, getValidatedQuery, getValidatedRouterParams, handleCacheHeaders, handleCors, isCorsOriginAllowed, isError, isEvent, isEventHandler, isMethod, isPreflightRequest, isStream, isWebResponse, lazyEventHandler, parseCookies, promisifyNodeListener, proxyRequest, readBody, readFormData, readMultipartFormData, readRawBody, readValidatedBody, removeResponseHeader, sanitizeStatusCode, sanitizeStatusMessage, sealSession, send, sendError, sendNoContent, sendProxy, sendRedirect, sendStream, sendWebResponse, serveStatic, setCookie, setHeader, setHeaders, setResponseHeader, setResponseHeaders, setResponseStatus, splitCookiesString, toEventHandler, toNodeListener, toPlainHandler, toWebHandler, toWebRequest, unsealSession, updateSession, use, useBase, useSession, writeEarlyHints };

package.json

 {
   "name": "h3",
-  "version": "1.8.2",
+  "version": "1.9.0",
   "description": "Minimal H(TTP) framework built for high performance and portability.",
@@ -24,7 +24,7 @@ "repository": "unjs/h3",
     "cookie-es": "^1.0.0",
-    "defu": "^6.1.2",
-    "destr": "^2.0.1",
-    "iron-webcrypto": "^0.10.1",
+    "defu": "^6.1.3",
+    "destr": "^2.0.2",
+    "iron-webcrypto": "^1.0.0",
     "radix3": "^1.1.0",
-    "ufo": "^1.3.0",
+    "ufo": "^1.3.2",
     "uncrypto": "^0.1.3",
@@ -35,17 +35,17 @@ "unenv": "^1.7.4"
     "0x": "^5.7.0",
-    "@types/express": "^4.17.18",
-    "@types/node": "^20.7.0",
-    "@types/supertest": "^2.0.13",
-    "@vitest/coverage-v8": "^0.34.5",
+    "@types/express": "^4.17.21",
+    "@types/node": "^20.9.2",
+    "@types/supertest": "^2.0.16",
+    "@vitest/coverage-v8": "^0.34.6",
     "autocannon": "^7.12.0",
     "changelogen": "^0.5.5",
     "connect": "^3.7.0",
-    "eslint": "^8.50.0",
+    "eslint": "^8.54.0",
     "eslint-config-unjs": "^0.2.1",
     "express": "^4.18.2",
     "get-port": "^7.0.0",
-    "jiti": "^1.20.0",
+    "jiti": "^1.21.0",
     "listhen": "^1.5.5",
-    "node-fetch-native": "^1.4.0",
-    "prettier": "^3.0.3",
+    "node-fetch-native": "^1.4.1",
+    "prettier": "^3.1.0",
     "react": "^18.2.0",
@@ -56,6 +56,6 @@ "react-dom": "^18.2.0",
     "unbuild": "^2.0.0",
-    "vitest": "^0.34.5",
-    "zod": "^3.22.2"
+    "vitest": "^0.34.6",
+    "zod": "^3.22.4"
   },
-  "packageManager": "pnpm@8.8.0",
+  "packageManager": "pnpm@8.10.5",
   "scripts": {
@@ -62,0 +62,0 @@ "build": "unbuild",

README.md

@@ -10,3 +10,3 @@ # H3
 
-H3 is a minimal h(ttp) framework built for high performance and portability.
+H3 (pronounced as /eɪtʃθriː/, like h-3) is a minimal h(ttp) framework built for high performance and portability.
 
@@ -218,3 +218,5 @@ 👉 [Online Playground](https://stackblitz.com/github/unjs/h3/tree/main/playground?startScript=dev)
 - `getValidatedQuery(event, validate)`
-- `getRouterParams(event)`
+- `getRouterParams(event, { decode? })`
+- `getRouterParam(event, name, { decode? })`
+- `getValidatedRouterParams(event, validate, { decode? })`
 - `getMethod(event, default?)`
@@ -317,2 +319,11 @@ - `isMethod(event, expected, allowHead?)`
   - `useValidateParams(event, schema)`
+- [@intlify/h3](https://github.com/intlify/h3)
+  - `defineI18nMiddleware(options)`
+  - `useTranslation(event)`
+  - `getHeaderLocale(event, options)`
+  - `getHeaderLocales(event, options)`
+  - `getCookieLocale(event, options)`
+  - `setCookieLocale(event, options)`
+  - `getPathLocale(event, options)`
+  - `getQueryLocale(event, options)`
 
@@ -319,0 +330,0 @@ ## License

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Number of lines in readme file

345

increased by3.29%

Worsened metrics

Total package byte prevSize

241839

decreased by-14.05%

Number of package files

8

decreased by-11.11%

Lines of code

4846

decreased by-28.24%

Dependency changes

• + Addediron-webcrypto@1.2.1(transitive)

• - Removediron-webcrypto@0.10.1(transitive)

• Updateddefu@^6.1.3

• Updateddestr@^2.0.2

• Updatediron-webcrypto@^1.0.0

• Updatedufo@^1.3.2