@rdlabo/workers-hono-kit 0.3.0 → 0.3.3

package/dist/firebase/firebase-verifier.d.ts

@@ -53,6 +53,21 @@ export interface FirebaseVerifier {
         uid: string;
         email?: string;
     } | null>;
+    /**
+     * Look up multiple user records by uid in as few requests as the backing service allows.
+     *
+     * Batched equivalent of {@link getUser}, intended to replace N single-uid lookups with a
+     * handful of requests.
+     *
+     * @param uids - The users' unique ids to look up.
+     * @returns The `uid`/`email` of every matching user. Uids that do not resolve to a user are
+     *   simply absent from the result (never `null` entries).
+     * @throws If the backing user-management service is not configured or the lookup fails.
+     */
+    getUsers(uids: string[]): Promise<{
+        uid: string;
+        email?: string;
+    }[]>;
     /**
      * Delete a user by uid.
      *

package/dist/firebase/identity-toolkit.d.ts

@@ -48,6 +48,17 @@ export declare class IdentityToolkit {
      * @internal
      */
     private getAccessToken;
+    /**
+     * Call the `accounts:lookup` endpoint for a single chunk of `localId`s.
+     *
+     * @param localIds - Up to {@link LOOKUP_CHUNK_SIZE} `localId`s to look up in one request.
+     * @param nowSeconds - The current Unix time in seconds, used for access-token caching.
+     * @returns The raw `users` entries returned by the endpoint (empty when the request is
+     *   unsuccessful or no matching users are returned).
+     * @throws If acquiring an access token fails.
+     * @internal
+     */
+    private lookupChunk;
     /**
      * Look up a user record by uid via the `accounts:lookup` endpoint.
      *
@@ -61,6 +72,24 @@ export declare class IdentityToolkit {
         uid: string;
         email?: string;
     } | null>;
+    /**
+     * Look up multiple user records by uid via the `accounts:lookup` endpoint.
+     *
+     * `uids` are chunked into groups of at most {@link LOOKUP_CHUNK_SIZE} (the maximum `localId`
+     * array size the endpoint accepts), issuing one `accounts:lookup` request per chunk. This lets
+     * callers replace N single-uid lookups with `ceil(N / LOOKUP_CHUNK_SIZE)` requests.
+     *
+     * @param uids - The users' unique ids (`localId`s) to look up.
+     * @param nowSeconds - The current Unix time in seconds, used for access-token caching.
+     * @returns The `uid`/`email` of every matching user. Uids Firebase does not recognize are
+     *   simply absent from the result (never `null` entries), so callers can treat "missing from
+     *   the result" as "not found/invalid".
+     * @throws If acquiring an access token fails.
+     */
+    lookupMany(uids: string[], nowSeconds: number): Promise<{
+        uid: string;
+        email?: string;
+    }[]>;
     /**
      * Delete a user by uid via the `accounts:delete` endpoint.
      *

package/dist/firebase/identity-toolkit.js

@@ -5,6 +5,8 @@ const TOKEN_URL = 'https://oauth2.googleapis.com/token';
 const IDENTITY_TOOLKIT = 'https://identitytoolkit.googleapis.com/v1';
 /** OAuth2 scopes required for Identity Toolkit account lookup and deletion. */
 const SCOPE = 'https://www.googleapis.com/auth/identitytoolkit https://www.googleapis.com/auth/firebase';
+/** Maximum number of `localId`s the `accounts:lookup` endpoint accepts in a single request. */
+const LOOKUP_CHUNK_SIZE = 100;
 /**
  * Minimal Google Identity Toolkit REST client for the user-management operations that token
  * verification does not cover: `accounts:lookup` (getUser) and `accounts:delete` (deleteUser).
@@ -71,27 +73,68 @@ export class IdentityToolkit {
         return json.access_token;
     }
     /**
-     * Look up a user record by uid via the `accounts:lookup` endpoint.
+     * Call the `accounts:lookup` endpoint for a single chunk of `localId`s.
      *
-     * @param uid - The user's unique id (`localId`).
+     * @param localIds - Up to {@link LOOKUP_CHUNK_SIZE} `localId`s to look up in one request.
      * @param nowSeconds - The current Unix time in seconds, used for access-token caching.
-     * @returns The user's `uid` and optional `email`, or `null` when the request is unsuccessful
-     *   or no matching user is returned.
+     * @returns The raw `users` entries returned by the endpoint (empty when the request is
+     *   unsuccessful or no matching users are returned).
      * @throws If acquiring an access token fails.
+     * @internal
      */
-    async lookup(uid, nowSeconds) {
+    async lookupChunk(localIds, nowSeconds) {
         const token = await this.getAccessToken(nowSeconds);
         const res = await fetch(`${IDENTITY_TOOLKIT}/projects/${this.sa.project_id}/accounts:lookup`, {
             method: 'POST',
             headers: { authorization: `Bearer ${token}`, 'content-type': 'application/json' },
-            body: JSON.stringify({ localId: [uid] }),
+            body: JSON.stringify({ localId: localIds }),
         });
         if (!res.ok) {
-            return null;
+            return [];
         }
         const json = (await res.json());
-        const user = json.users?.[0];
-        return user ? { uid: user.localId, email: user.email } : null;
+        return json.users ?? [];
+    }
+    /**
+     * Look up a user record by uid via the `accounts:lookup` endpoint.
+     *
+     * @param uid - The user's unique id (`localId`).
+     * @param nowSeconds - The current Unix time in seconds, used for access-token caching.
+     * @returns The user's `uid` and optional `email`, or `null` when the request is unsuccessful
+     *   or no matching user is returned.
+     * @throws If acquiring an access token fails.
+     */
+    async lookup(uid, nowSeconds) {
+        const users = await this.lookupChunk([uid], nowSeconds);
+        return users.length > 0 ? { uid: users[0].localId, email: users[0].email } : null;
+    }
+    /**
+     * Look up multiple user records by uid via the `accounts:lookup` endpoint.
+     *
+     * `uids` are chunked into groups of at most {@link LOOKUP_CHUNK_SIZE} (the maximum `localId`
+     * array size the endpoint accepts), issuing one `accounts:lookup` request per chunk. This lets
+     * callers replace N single-uid lookups with `ceil(N / LOOKUP_CHUNK_SIZE)` requests.
+     *
+     * @param uids - The users' unique ids (`localId`s) to look up.
+     * @param nowSeconds - The current Unix time in seconds, used for access-token caching.
+     * @returns The `uid`/`email` of every matching user. Uids Firebase does not recognize are
+     *   simply absent from the result (never `null` entries), so callers can treat "missing from
+     *   the result" as "not found/invalid".
+     * @throws If acquiring an access token fails.
+     */
+    async lookupMany(uids, nowSeconds) {
+        if (uids.length === 0) {
+            return [];
+        }
+        const results = [];
+        for (let i = 0; i < uids.length; i += LOOKUP_CHUNK_SIZE) {
+            const chunk = uids.slice(i, i + LOOKUP_CHUNK_SIZE);
+            const users = await this.lookupChunk(chunk, nowSeconds);
+            for (const user of users) {
+                results.push({ uid: user.localId, email: user.email });
+            }
+        }
+        return results;
     }
     /**
      * Delete a user by uid via the `accounts:delete` endpoint.

package/dist/firebase/jose-firebase-verifier.d.ts

@@ -85,6 +85,21 @@ export declare class JoseFirebaseVerifier implements FirebaseVerifier {
         uid: string;
         email?: string;
     } | null>;
+    /**
+     * Look up multiple user records by uid via the Identity Toolkit REST API.
+     *
+     * Batches the lookups into `ceil(uids.length / 100)` `accounts:lookup` requests instead of
+     * one request per uid.
+     *
+     * @param uids - The users' unique ids to look up.
+     * @returns The `uid`/`email` of every matching user. Uids Firebase does not recognize are
+     *   simply absent from the result (never `null` entries).
+     * @throws If no Identity Toolkit client was configured on this verifier.
+     */
+    getUsers(uids: string[]): Promise<{
+        uid: string;
+        email?: string;
+    }[]>;
     /**
      * Delete a user by uid via the Identity Toolkit REST API.
      *

package/dist/firebase/jose-firebase-verifier.js

@@ -88,6 +88,23 @@ export class JoseFirebaseVerifier {
         }
         return this.opts.identity.lookup(uid, this.nowSeconds());
     }
+    /**
+     * Look up multiple user records by uid via the Identity Toolkit REST API.
+     *
+     * Batches the lookups into `ceil(uids.length / 100)` `accounts:lookup` requests instead of
+     * one request per uid.
+     *
+     * @param uids - The users' unique ids to look up.
+     * @returns The `uid`/`email` of every matching user. Uids Firebase does not recognize are
+     *   simply absent from the result (never `null` entries).
+     * @throws If no Identity Toolkit client was configured on this verifier.
+     */
+    async getUsers(uids) {
+        if (!this.opts.identity) {
+            throw new Error('Identity Toolkit not configured');
+        }
+        return this.opts.identity.lookupMany(uids, this.nowSeconds());
+    }
     /**
      * Delete a user by uid via the Identity Toolkit REST API.
      *

package/dist/http/trailing-slash.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Trailing-slash normalization for NestJS(Express) → Hono parity.
+ *
+ * Express runs with strict routing off by default, so `/x` and `/x/` resolve to the same handler.
+ * Hono distinguishes them, so a client that sends e.g. `GET /functions/timeline/` 404s against a
+ * Hono worker that only registered `/functions/timeline`. Apply this at the Worker `fetch` entry to
+ * strip a trailing slash before routing, preserving method / headers / body.
+ *
+ * We intentionally do NOT use `hono/trailing-slash`'s `trimTrailingSlash`, which responds with a 301
+ * redirect and thus breaks non-GET methods (POST/PUT/DELETE) and clients that don't follow redirects.
+ *
+ * @example
+ * export default {
+ *   fetch: (request, env, ctx) => app.fetch(normalizeTrailingSlash(request), env, ctx),
+ * };
+ *
+ * @param request - The incoming request.
+ * @returns The same request when the path has no trailing slash (or is exactly `/`), otherwise a new
+ *   Request with the trailing slash(es) removed.
+ */
+export declare const normalizeTrailingSlash: (request: Request) => Request;

package/dist/http/trailing-slash.js

@@ -0,0 +1,28 @@
+/**
+ * Trailing-slash normalization for NestJS(Express) → Hono parity.
+ *
+ * Express runs with strict routing off by default, so `/x` and `/x/` resolve to the same handler.
+ * Hono distinguishes them, so a client that sends e.g. `GET /functions/timeline/` 404s against a
+ * Hono worker that only registered `/functions/timeline`. Apply this at the Worker `fetch` entry to
+ * strip a trailing slash before routing, preserving method / headers / body.
+ *
+ * We intentionally do NOT use `hono/trailing-slash`'s `trimTrailingSlash`, which responds with a 301
+ * redirect and thus breaks non-GET methods (POST/PUT/DELETE) and clients that don't follow redirects.
+ *
+ * @example
+ * export default {
+ *   fetch: (request, env, ctx) => app.fetch(normalizeTrailingSlash(request), env, ctx),
+ * };
+ *
+ * @param request - The incoming request.
+ * @returns The same request when the path has no trailing slash (or is exactly `/`), otherwise a new
+ *   Request with the trailing slash(es) removed.
+ */
+export const normalizeTrailingSlash = (request) => {
+    const url = new URL(request.url);
+    if (url.pathname.length > 1 && url.pathname.endsWith('/')) {
+        url.pathname = url.pathname.replace(/\/+$/, '');
+        return new Request(url, request);
+    }
+    return request;
+};

package/dist/index.d.ts

@@ -24,6 +24,7 @@ export type { AppEnv } from './http/app-env.js';
 export { HttpStatus } from './http/http-status.js';
 export { createNestErrorHandler, nestNotFoundHandler, NEST_REASON_PHRASES } from './http/nest-error.js';
 export type { NestErrorHandlerOptions, ErrorReportContext, ErrorReporter } from './http/nest-error.js';
+export { normalizeTrailingSlash } from './http/trailing-slash.js';
 export { KVCache } from './cache/kv-cache.js';
 export type { KVNamespace, KVCacheOptions } from './cache/kv-cache.js';
 export { createStripeClient, verifyStripeWebhook } from './stripe/client.js';

package/dist/index.js

@@ -20,6 +20,7 @@ export { getAppInfo } from './http/app-info.js';
 export { resolveAppEnv, isProductionEnv } from './http/app-env.js';
 export { HttpStatus } from './http/http-status.js';
 export { createNestErrorHandler, nestNotFoundHandler, NEST_REASON_PHRASES } from './http/nest-error.js';
+export { normalizeTrailingSlash } from './http/trailing-slash.js';
 // cache
 export { KVCache } from './cache/kv-cache.js';
 // stripe

package/dist/testing/fakes.d.ts

@@ -43,6 +43,16 @@ export declare class FakeFirebaseVerifier implements FirebaseVerifier {
         uid: string;
         email?: string;
     } | null>;
+    /**
+     * Return minimal user records echoing each requested UID.
+     *
+     * @param uids - UIDs to look up.
+     * @returns One `{ uid }` entry per requested uid (never omits any, in this fake).
+     */
+    getUsers(uids: string[]): Promise<{
+        uid: string;
+        email?: string;
+    }[]>;
     /**
      * Record a user deletion by appending the UID to {@link FakeFirebaseVerifier.deleted}.
      *

package/dist/testing/fakes.js

@@ -48,6 +48,15 @@ export class FakeFirebaseVerifier {
     async getUser(uid) {
         return { uid };
     }
+    /**
+     * Return minimal user records echoing each requested UID.
+     *
+     * @param uids - UIDs to look up.
+     * @returns One `{ uid }` entry per requested uid (never omits any, in this fake).
+     */
+    async getUsers(uids) {
+        return uids.map((uid) => ({ uid }));
+    }
     /**
      * Record a user deletion by appending the UID to {@link FakeFirebaseVerifier.deleted}.
      *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rdlabo/workers-hono-kit",
-  "version": "0.3.0",
+  "version": "0.3.3",
   "private": false,
   "publishConfig": {
     "access": "public"

package/src/firebase/firebase-verifier.ts

@@ -51,6 +51,18 @@ export interface FirebaseVerifier {
    * @throws If the backing user-management service is not configured or the lookup fails.
    */
   getUser(uid: string): Promise<{ uid: string; email?: string } | null>;
+  /**
+   * Look up multiple user records by uid in as few requests as the backing service allows.
+   *
+   * Batched equivalent of {@link getUser}, intended to replace N single-uid lookups with a
+   * handful of requests.
+   *
+   * @param uids - The users' unique ids to look up.
+   * @returns The `uid`/`email` of every matching user. Uids that do not resolve to a user are
+   *   simply absent from the result (never `null` entries).
+   * @throws If the backing user-management service is not configured or the lookup fails.
+   */
+  getUsers(uids: string[]): Promise<{ uid: string; email?: string }[]>;
   /**
    * Delete a user by uid.
    *

package/src/firebase/identity-toolkit.ts

@@ -21,6 +21,8 @@ const TOKEN_URL = 'https://oauth2.googleapis.com/token';
 const IDENTITY_TOOLKIT = 'https://identitytoolkit.googleapis.com/v1';
 /** OAuth2 scopes required for Identity Toolkit account lookup and deletion. */
 const SCOPE = 'https://www.googleapis.com/auth/identitytoolkit https://www.googleapis.com/auth/firebase';
+/** Maximum number of `localId`s the `accounts:lookup` endpoint accepts in a single request. */
+const LOOKUP_CHUNK_SIZE = 100;
 
 /**
  * Minimal Google Identity Toolkit REST client for the user-management operations that token
@@ -89,27 +91,70 @@ export class IdentityToolkit {
   }
 
   /**
-   * Look up a user record by uid via the `accounts:lookup` endpoint.
+   * Call the `accounts:lookup` endpoint for a single chunk of `localId`s.
    *
-   * @param uid - The user's unique id (`localId`).
+   * @param localIds - Up to {@link LOOKUP_CHUNK_SIZE} `localId`s to look up in one request.
    * @param nowSeconds - The current Unix time in seconds, used for access-token caching.
-   * @returns The user's `uid` and optional `email`, or `null` when the request is unsuccessful
-   *   or no matching user is returned.
+   * @returns The raw `users` entries returned by the endpoint (empty when the request is
+   *   unsuccessful or no matching users are returned).
    * @throws If acquiring an access token fails.
+   * @internal
    */
-  async lookup(uid: string, nowSeconds: number): Promise<{ uid: string; email?: string } | null> {
+  private async lookupChunk(localIds: string[], nowSeconds: number): Promise<{ localId: string; email?: string }[]> {
     const token = await this.getAccessToken(nowSeconds);
     const res = await fetch(`${IDENTITY_TOOLKIT}/projects/${this.sa.project_id}/accounts:lookup`, {
       method: 'POST',
       headers: { authorization: `Bearer ${token}`, 'content-type': 'application/json' },
-      body: JSON.stringify({ localId: [uid] }),
+      body: JSON.stringify({ localId: localIds }),
     });
     if (!res.ok) {
-      return null;
+      return [];
     }
     const json = (await res.json()) as { users?: { localId: string; email?: string }[] };
-    const user = json.users?.[0];
-    return user ? { uid: user.localId, email: user.email } : null;
+    return json.users ?? [];
+  }
+
+  /**
+   * Look up a user record by uid via the `accounts:lookup` endpoint.
+   *
+   * @param uid - The user's unique id (`localId`).
+   * @param nowSeconds - The current Unix time in seconds, used for access-token caching.
+   * @returns The user's `uid` and optional `email`, or `null` when the request is unsuccessful
+   *   or no matching user is returned.
+   * @throws If acquiring an access token fails.
+   */
+  async lookup(uid: string, nowSeconds: number): Promise<{ uid: string; email?: string } | null> {
+    const users = await this.lookupChunk([uid], nowSeconds);
+    return users.length > 0 ? { uid: users[0].localId, email: users[0].email } : null;
+  }
+
+  /**
+   * Look up multiple user records by uid via the `accounts:lookup` endpoint.
+   *
+   * `uids` are chunked into groups of at most {@link LOOKUP_CHUNK_SIZE} (the maximum `localId`
+   * array size the endpoint accepts), issuing one `accounts:lookup` request per chunk. This lets
+   * callers replace N single-uid lookups with `ceil(N / LOOKUP_CHUNK_SIZE)` requests.
+   *
+   * @param uids - The users' unique ids (`localId`s) to look up.
+   * @param nowSeconds - The current Unix time in seconds, used for access-token caching.
+   * @returns The `uid`/`email` of every matching user. Uids Firebase does not recognize are
+   *   simply absent from the result (never `null` entries), so callers can treat "missing from
+   *   the result" as "not found/invalid".
+   * @throws If acquiring an access token fails.
+   */
+  async lookupMany(uids: string[], nowSeconds: number): Promise<{ uid: string; email?: string }[]> {
+    if (uids.length === 0) {
+      return [];
+    }
+    const results: { uid: string; email?: string }[] = [];
+    for (let i = 0; i < uids.length; i += LOOKUP_CHUNK_SIZE) {
+      const chunk = uids.slice(i, i + LOOKUP_CHUNK_SIZE);
+      const users = await this.lookupChunk(chunk, nowSeconds);
+      for (const user of users) {
+        results.push({ uid: user.localId, email: user.email });
+      }
+    }
+    return results;
   }
 
   /**

package/src/firebase/jose-firebase-verifier.ts

@@ -115,6 +115,24 @@ export class JoseFirebaseVerifier implements FirebaseVerifier {
     return this.opts.identity.lookup(uid, this.nowSeconds());
   }
 
+  /**
+   * Look up multiple user records by uid via the Identity Toolkit REST API.
+   *
+   * Batches the lookups into `ceil(uids.length / 100)` `accounts:lookup` requests instead of
+   * one request per uid.
+   *
+   * @param uids - The users' unique ids to look up.
+   * @returns The `uid`/`email` of every matching user. Uids Firebase does not recognize are
+   *   simply absent from the result (never `null` entries).
+   * @throws If no Identity Toolkit client was configured on this verifier.
+   */
+  async getUsers(uids: string[]): Promise<{ uid: string; email?: string }[]> {
+    if (!this.opts.identity) {
+      throw new Error('Identity Toolkit not configured');
+    }
+    return this.opts.identity.lookupMany(uids, this.nowSeconds());
+  }
+
   /**
    * Delete a user by uid via the Identity Toolkit REST API.
    *

package/src/http/trailing-slash.ts

@@ -0,0 +1,28 @@
+/**
+ * Trailing-slash normalization for NestJS(Express) → Hono parity.
+ *
+ * Express runs with strict routing off by default, so `/x` and `/x/` resolve to the same handler.
+ * Hono distinguishes them, so a client that sends e.g. `GET /functions/timeline/` 404s against a
+ * Hono worker that only registered `/functions/timeline`. Apply this at the Worker `fetch` entry to
+ * strip a trailing slash before routing, preserving method / headers / body.
+ *
+ * We intentionally do NOT use `hono/trailing-slash`'s `trimTrailingSlash`, which responds with a 301
+ * redirect and thus breaks non-GET methods (POST/PUT/DELETE) and clients that don't follow redirects.
+ *
+ * @example
+ * export default {
+ *   fetch: (request, env, ctx) => app.fetch(normalizeTrailingSlash(request), env, ctx),
+ * };
+ *
+ * @param request - The incoming request.
+ * @returns The same request when the path has no trailing slash (or is exactly `/`), otherwise a new
+ *   Request with the trailing slash(es) removed.
+ */
+export const normalizeTrailingSlash = (request: Request): Request => {
+  const url = new URL(request.url);
+  if (url.pathname.length > 1 && url.pathname.endsWith('/')) {
+    url.pathname = url.pathname.replace(/\/+$/, '');
+    return new Request(url, request);
+  }
+  return request;
+};

package/src/index.ts

@@ -34,6 +34,7 @@ export type { AppEnv } from './http/app-env.js';
 export { HttpStatus } from './http/http-status.js';
 export { createNestErrorHandler, nestNotFoundHandler, NEST_REASON_PHRASES } from './http/nest-error.js';
 export type { NestErrorHandlerOptions, ErrorReportContext, ErrorReporter } from './http/nest-error.js';
+export { normalizeTrailingSlash } from './http/trailing-slash.js';
 
 // cache
 export { KVCache } from './cache/kv-cache.js';

package/src/testing/fakes.ts

@@ -56,6 +56,16 @@ export class FakeFirebaseVerifier implements FirebaseVerifier {
     return { uid };
   }
 
+  /**
+   * Return minimal user records echoing each requested UID.
+   *
+   * @param uids - UIDs to look up.
+   * @returns One `{ uid }` entry per requested uid (never omits any, in this fake).
+   */
+  async getUsers(uids: string[]): Promise<{ uid: string; email?: string }[]> {
+    return uids.map((uid) => ({ uid }));
+  }
+
   /**
    * Record a user deletion by appending the UID to {@link FakeFirebaseVerifier.deleted}.
    *