@haruhimemoe/next-kit 0.1.0

package/dist/auth-react/use-account.js

@@ -0,0 +1,52 @@
+/**
+ * @file src/auth-react/use-account.ts
+ * @desc The React side of the account store: useAccount (loading during server render), and
+ *       createAccount, which wires a store to a better-auth client and the app's marker cookie
+ *       the way packs and pools each did at the bottom of src/hooks/useAccount.ts.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Mon Sep 28, 2026
+ * @modified Mon Sep 28, 2026
+ */
+"use client";
+import { createElement, useSyncExternalStore } from "react";
+import { createAccountStore, LOADING, } from "./account-store.js";
+import { RestoreSignedIn } from "./RestoreSignedIn.js";
+/**
+ * @function sessionFetcher
+ * @param client {SessionClient} the app's better-auth client
+ * @returns {() => Promise<SessionData | null>} a getSession that throws better-auth's error
+ */
+export const sessionFetcher = (client) => async () => {
+    const { data, error } = await client.getSession();
+    if (error)
+        throw error;
+    return data ?? null;
+};
+/**
+ * @function useAccount
+ * @param store {AccountStore} the page-wide store
+ * @returns {Account} current account state ("loading" during server render)
+ */
+export const useAccount = (store) => useSyncExternalStore(store.subscribe, store.getSnapshot, () => LOADING);
+/**
+ * @function createAccount
+ * @param client {SessionClient} the app's better-auth client
+ * @param marker {SignedInMarker} the app's signed-in marker
+ * @returns {AccountKit} a page-wide store reading document.cookie, with its hook, sign-out and
+ *          RestoreSignedIn (export them from the app's own "use client" module, so server pages
+ *          render <RestoreSignedIn next={next} /> with only serializable props)
+ */
+export const createAccount = (client, marker) => {
+    const store = createAccountStore({
+        getSession: sessionFetcher(client),
+        readCookie: () => document.cookie,
+        hasMarker: marker.has,
+        clearMarker: () => marker.clear(),
+    });
+    return {
+        store,
+        useAccount: () => useAccount(store),
+        markSignedOut: () => store.markSignedOut(),
+        RestoreSignedIn: (props) => createElement(RestoreSignedIn, { ...props, store, hasMarker: marker.has }),
+    };
+};

package/dist/env/errors.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @file src/env/errors.ts
+ * @desc EnvError, thrown for a missing or invalid environment variable. Its message names the
+ *       variable and never prints its value.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Mon Sep 28, 2026
+ * @modified Mon Sep 28, 2026
+ */
+/** A missing or invalid environment variable, named but never printed. */
+export declare class EnvError extends Error {
+    constructor(message: string);
+}
+/**
+ * @function invalidEnv
+ * @param keys {readonly string[]} the variables that are missing or invalid
+ * @returns {EnvError} "Missing or invalid environment variables: A, B. See .env.example."
+ */
+export declare const invalidEnv: (keys: readonly string[]) => EnvError;

package/dist/env/errors.js

@@ -0,0 +1,21 @@
+/**
+ * @file src/env/errors.ts
+ * @desc EnvError, thrown for a missing or invalid environment variable. Its message names the
+ *       variable and never prints its value.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Mon Sep 28, 2026
+ * @modified Mon Sep 28, 2026
+ */
+/** A missing or invalid environment variable, named but never printed. */
+export class EnvError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "EnvError";
+    }
+}
+/**
+ * @function invalidEnv
+ * @param keys {readonly string[]} the variables that are missing or invalid
+ * @returns {EnvError} "Missing or invalid environment variables: A, B. See .env.example."
+ */
+export const invalidEnv = (keys) => new EnvError(`Missing or invalid environment variables: ${keys.join(", ")}. See .env.example.`);

package/dist/env/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @file src/env/index.ts
+ * @desc @haruhimemoe/next-kit/env: zod env parsing with SKIP_ENV_VALIDATION and the production
+ *       placeholder guard, the osu! app's five variables, and per-call readers for optional
+ *       secrets, id lists, flags and origins. Server only.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Mon Sep 28, 2026
+ * @modified Mon Sep 28, 2026
+ */
+export { EnvError, invalidEnv } from "./errors.js";
+export { optionalSecret, readFlag, readIdSet, readOptional, readOrigin, } from "./optional.js";
+export { OSU_APP_PLACEHOLDERS, OSU_APP_SECRET_KEYS, type OsuAppEnv, osuAppEnvSchema, } from "./osu-app.js";
+export { BUILD_PHASE, createServerEnv, type EnvSchema, type EnvSource, isEnvValidationSkipped, isProductionServer, type ServerEnv, type ServerEnvOptions, } from "./server-env.js";

package/dist/env/index.js

@@ -0,0 +1,13 @@
+/**
+ * @file src/env/index.ts
+ * @desc @haruhimemoe/next-kit/env: zod env parsing with SKIP_ENV_VALIDATION and the production
+ *       placeholder guard, the osu! app's five variables, and per-call readers for optional
+ *       secrets, id lists, flags and origins. Server only.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Mon Sep 28, 2026
+ * @modified Mon Sep 28, 2026
+ */
+export { EnvError, invalidEnv } from "./errors.js";
+export { optionalSecret, readFlag, readIdSet, readOptional, readOrigin, } from "./optional.js";
+export { OSU_APP_PLACEHOLDERS, OSU_APP_SECRET_KEYS, osuAppEnvSchema, } from "./osu-app.js";
+export { BUILD_PHASE, createServerEnv, isEnvValidationSkipped, isProductionServer, } from "./server-env.js";

package/dist/env/optional.d.ts

@@ -0,0 +1,54 @@
+/**
+ * @file src/env/optional.ts
+ * @desc Variables read on every call instead of memoized with the server env, so a missing or
+ *       bad value only breaks what uses it and a change applies at the next request (a removed
+ *       admin id stops working at once): optional secrets, osu! id lists, flags and origins.
+ *       Moved from packs (optionalSecret: CRON_SECRET, POOLS_SERVICE_TOKEN) and pools
+ *       (getAdminOsuIds, getAllowSharedDbUser, the PACKS_URL check).
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Mon Sep 28, 2026
+ * @modified Mon Sep 28, 2026
+ */
+import type { EnvSource } from "./server-env.js";
+/**
+ * @function readOptional
+ * @param key {string} the variable
+ * @param source {EnvSource} usually process.env (the default)
+ * @returns {string | undefined} its value, trimmed; undefined when unset or blank
+ */
+export declare const readOptional: (key: string, source?: EnvSource) => string | undefined;
+/**
+ * @function optionalSecret
+ * @param key {string} the variable
+ * @param minLength {number} the shortest secret accepted
+ * @param source {EnvSource} usually process.env (the default)
+ * @returns {string | undefined} the secret, trimmed; undefined when unset (whatever needs it then
+ *          refuses every call)
+ * @throws {EnvError} naming (never printing) the variable when it's set but too short
+ */
+export declare const optionalSecret: (key: string, minLength: number, source?: EnvSource) => string | undefined;
+/**
+ * @function readIdSet
+ * @param key {string} the variable, like ADMIN_OSU_IDS
+ * @param source {EnvSource} usually process.env (the default)
+ * @returns {ReadonlySet<number>} the comma-separated ids (spaces allowed around commas); empty
+ *          when unset
+ * @throws {EnvError} naming (never printing) the variable when it isn't an id list
+ */
+export declare const readIdSet: (key: string, source?: EnvSource) => ReadonlySet<number>;
+/**
+ * @function readFlag
+ * @param key {string} the variable
+ * @param source {EnvSource} usually process.env (the default)
+ * @returns {boolean} true only when it's "true" (trimmed); unset, blank or anything else is false
+ */
+export declare const readFlag: (key: string, source?: EnvSource) => boolean;
+/**
+ * @function readOrigin
+ * @param key {string} the variable, like PACKS_URL
+ * @param fallback {string} the origin when it's unset
+ * @param source {EnvSource} usually process.env (the default)
+ * @returns {string} an origin (no path, query or hash): https, or http on localhost
+ * @throws {EnvError} naming (never printing) the variable when it's anything else
+ */
+export declare const readOrigin: (key: string, fallback: string, source?: EnvSource) => string;

package/dist/env/optional.js

@@ -0,0 +1,84 @@
+/**
+ * @file src/env/optional.ts
+ * @desc Variables read on every call instead of memoized with the server env, so a missing or
+ *       bad value only breaks what uses it and a change applies at the next request (a removed
+ *       admin id stops working at once): optional secrets, osu! id lists, flags and origins.
+ *       Moved from packs (optionalSecret: CRON_SECRET, POOLS_SERVICE_TOKEN) and pools
+ *       (getAdminOsuIds, getAllowSharedDbUser, the PACKS_URL check).
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Mon Sep 28, 2026
+ * @modified Mon Sep 28, 2026
+ */
+import { invalidEnv } from "./errors.js";
+/**
+ * @function readOptional
+ * @param key {string} the variable
+ * @param source {EnvSource} usually process.env (the default)
+ * @returns {string | undefined} its value, trimmed; undefined when unset or blank
+ */
+export const readOptional = (key, source = process.env) => source[key]?.trim() || undefined;
+/**
+ * @function optionalSecret
+ * @param key {string} the variable
+ * @param minLength {number} the shortest secret accepted
+ * @param source {EnvSource} usually process.env (the default)
+ * @returns {string | undefined} the secret, trimmed; undefined when unset (whatever needs it then
+ *          refuses every call)
+ * @throws {EnvError} naming (never printing) the variable when it's set but too short
+ */
+export const optionalSecret = (key, minLength, source = process.env) => {
+    const value = readOptional(key, source);
+    if (value !== undefined && value.length < minLength)
+        throw invalidEnv([key]);
+    return value;
+};
+const ID_LIST = /^\d+(\s*,\s*\d+)*$/;
+/**
+ * @function readIdSet
+ * @param key {string} the variable, like ADMIN_OSU_IDS
+ * @param source {EnvSource} usually process.env (the default)
+ * @returns {ReadonlySet<number>} the comma-separated ids (spaces allowed around commas); empty
+ *          when unset
+ * @throws {EnvError} naming (never printing) the variable when it isn't an id list
+ */
+export const readIdSet = (key, source = process.env) => {
+    const raw = readOptional(key, source);
+    if (raw === undefined)
+        return new Set();
+    if (!ID_LIST.test(raw))
+        throw invalidEnv([key]);
+    return new Set(raw.split(",").map((part) => Number(part.trim())));
+};
+/**
+ * @function readFlag
+ * @param key {string} the variable
+ * @param source {EnvSource} usually process.env (the default)
+ * @returns {boolean} true only when it's "true" (trimmed); unset, blank or anything else is false
+ */
+export const readFlag = (key, source = process.env) => readOptional(key, source) === "true";
+const LOCAL_HOSTS = new Set(["localhost", "127.0.0.1"]);
+/**
+ * @function readOrigin
+ * @param key {string} the variable, like PACKS_URL
+ * @param fallback {string} the origin when it's unset
+ * @param source {EnvSource} usually process.env (the default)
+ * @returns {string} an origin (no path, query or hash): https, or http on localhost
+ * @throws {EnvError} naming (never printing) the variable when it's anything else
+ */
+export const readOrigin = (key, fallback, source = process.env) => {
+    const raw = readOptional(key, source);
+    if (raw === undefined)
+        return fallback;
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        throw invalidEnv([key]);
+    }
+    const secure = url.protocol === "https:" || (url.protocol === "http:" && LOCAL_HOSTS.has(url.hostname));
+    if (!secure || url.pathname !== "/" || url.search !== "" || url.hash !== "") {
+        throw invalidEnv([key]);
+    }
+    return url.origin;
+};

package/dist/env/osu-app.d.ts

@@ -0,0 +1,24 @@
+/**
+ * @file src/env/osu-app.ts
+ * @desc The five variables a Next app with MongoDB and osu! sign-in needs (the same block in
+ *       packs' and pools' src/env.ts), their SKIP_ENV_VALIDATION placeholders and which are
+ *       secrets. Pass them to createServerEnv, or extend the schema first.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Mon Sep 28, 2026
+ * @modified Mon Sep 28, 2026
+ */
+import { z } from "zod";
+/** MONGODB_URI, BETTER_AUTH_SECRET (32+), BETTER_AUTH_URL, OSU_CLIENT_ID (digits), OSU_CLIENT_SECRET. */
+export declare const osuAppEnvSchema: z.ZodObject<{
+    MONGODB_URI: z.ZodString;
+    BETTER_AUTH_SECRET: z.ZodString;
+    BETTER_AUTH_URL: z.ZodURL;
+    OSU_CLIENT_ID: z.ZodString;
+    OSU_CLIENT_SECRET: z.ZodString;
+}, z.core.$strip>;
+/** The validated variables. */
+export type OsuAppEnv = z.infer<typeof osuAppEnvSchema>;
+/** Used only under SKIP_ENV_VALIDATION=true. Nothing connects with these. */
+export declare const OSU_APP_PLACEHOLDERS: Readonly<OsuAppEnv>;
+/** The variables whose placeholder would be a known secret on a production server. */
+export declare const OSU_APP_SECRET_KEYS: readonly ["BETTER_AUTH_SECRET", "OSU_CLIENT_SECRET", "MONGODB_URI"];

package/dist/env/osu-app.js

@@ -0,0 +1,32 @@
+/**
+ * @file src/env/osu-app.ts
+ * @desc The five variables a Next app with MongoDB and osu! sign-in needs (the same block in
+ *       packs' and pools' src/env.ts), their SKIP_ENV_VALIDATION placeholders and which are
+ *       secrets. Pass them to createServerEnv, or extend the schema first.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Mon Sep 28, 2026
+ * @modified Mon Sep 28, 2026
+ */
+import { z } from "zod";
+/** MONGODB_URI, BETTER_AUTH_SECRET (32+), BETTER_AUTH_URL, OSU_CLIENT_ID (digits), OSU_CLIENT_SECRET. */
+export const osuAppEnvSchema = z.object({
+    MONGODB_URI: z.string().regex(/^mongodb(\+srv)?:\/\//),
+    BETTER_AUTH_SECRET: z.string().min(32),
+    BETTER_AUTH_URL: z.url(),
+    OSU_CLIENT_ID: z.string().regex(/^\d+$/),
+    OSU_CLIENT_SECRET: z.string().min(1),
+});
+/** Used only under SKIP_ENV_VALIDATION=true. Nothing connects with these. */
+export const OSU_APP_PLACEHOLDERS = Object.freeze({
+    MONGODB_URI: "mongodb://127.0.0.1:27017",
+    BETTER_AUTH_SECRET: "skip-env-validation-placeholder-secret-000",
+    BETTER_AUTH_URL: "http://localhost:3000",
+    OSU_CLIENT_ID: "0",
+    OSU_CLIENT_SECRET: "placeholder",
+});
+/** The variables whose placeholder would be a known secret on a production server. */
+export const OSU_APP_SECRET_KEYS = Object.freeze([
+    "BETTER_AUTH_SECRET",
+    "OSU_CLIENT_SECRET",
+    "MONGODB_URI",
+]);

package/dist/env/server-env.d.ts

@@ -0,0 +1,63 @@
+/**
+ * @file src/env/server-env.ts
+ * @desc Server environment, validated with zod on first use (not at import), so `next build` and
+ *       public pages build without auth variables. SKIP_ENV_VALIDATION=true (CI) swaps missing
+ *       values for placeholders nothing connects with; a production server (VERCEL_ENV=production
+ *       when VERCEL_ENV is set, else NODE_ENV=production; never during `next build`) refuses that
+ *       when a secret would be one of these public placeholders. Moved from packs and pools
+ *       (src/env.ts), whose mechanism was the same code around the same five variables.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Mon Sep 28, 2026
+ * @modified Mon Sep 28, 2026
+ */
+import type { z } from "zod";
+/** process.env, or a stand-in in tests. */
+export type EnvSource = Record<string, string | undefined>;
+/** Set in process.env by `next build` for the whole build, prerendering included. */
+export declare const BUILD_PHASE = "phase-production-build";
+/**
+ * @function isProductionServer
+ * @param source {EnvSource} usually process.env
+ * @returns {boolean} false during `next build`; VERCEL_ENV=production when VERCEL_ENV is set;
+ *          otherwise NODE_ENV=production
+ */
+export declare const isProductionServer: (source: EnvSource) => boolean;
+/**
+ * @function isEnvValidationSkipped
+ * @param source {EnvSource} usually process.env (the default)
+ * @returns {boolean} true in CI builds (SKIP_ENV_VALIDATION=true), where nothing may query the
+ *          database: public pages then prerender empty
+ */
+export declare const isEnvValidationSkipped: (source?: EnvSource) => boolean;
+/** A zod object of string variables. */
+export type EnvSchema = z.ZodObject<Record<string, z.ZodType<string | undefined>>>;
+/** createServerEnv's options. */
+export type ServerEnvOptions<S extends EnvSchema> = {
+    /** The variables every server request needs. */
+    schema: S;
+    /** Used only under SKIP_ENV_VALIDATION=true. Nothing may connect with these. */
+    placeholders: z.output<S>;
+    /** The variables whose placeholder, being in public source, would be a known secret. */
+    secretKeys: readonly (keyof z.output<S> & string)[];
+};
+/** What createServerEnv returns. */
+export type ServerEnv<T> = {
+    /** Every variable name in the schema. */
+    keys: readonly (keyof T & string)[];
+    /** Validates the variables, trimmed; throws an EnvError naming (never printing) each bad one. */
+    parse: (source: EnvSource) => T;
+    /** Validates only these variables (a page that needs just the database). */
+    pick: <K extends keyof T & string>(source: EnvSource, keys: readonly K[]) => Pick<T, K>;
+    /** process.env, parsed once and memoized. */
+    get: () => T;
+    /** Forgets the memoized value (tests). */
+    reset: () => void;
+    /** Throws when SKIP_ENV_VALIDATION would put a placeholder secret on a production server. */
+    assertNoPlaceholderSecrets: (source: EnvSource, keys?: readonly (keyof T & string)[]) => void;
+};
+/**
+ * @function createServerEnv
+ * @param options {ServerEnvOptions<S>} the schema, its placeholders and which keys are secrets
+ * @returns {ServerEnv<z.output<S>>} parse, pick, get (memoized), reset and the placeholder guard
+ */
+export declare const createServerEnv: <S extends EnvSchema>({ schema, placeholders, secretKeys, }: ServerEnvOptions<S>) => ServerEnv<z.output<S>>;

package/dist/env/server-env.js

@@ -0,0 +1,88 @@
+/**
+ * @file src/env/server-env.ts
+ * @desc Server environment, validated with zod on first use (not at import), so `next build` and
+ *       public pages build without auth variables. SKIP_ENV_VALIDATION=true (CI) swaps missing
+ *       values for placeholders nothing connects with; a production server (VERCEL_ENV=production
+ *       when VERCEL_ENV is set, else NODE_ENV=production; never during `next build`) refuses that
+ *       when a secret would be one of these public placeholders. Moved from packs and pools
+ *       (src/env.ts), whose mechanism was the same code around the same five variables.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Mon Sep 28, 2026
+ * @modified Mon Sep 28, 2026
+ */
+import { EnvError, invalidEnv } from "./errors.js";
+/** Set in process.env by `next build` for the whole build, prerendering included. */
+export const BUILD_PHASE = "phase-production-build";
+/**
+ * @function isProductionServer
+ * @param source {EnvSource} usually process.env
+ * @returns {boolean} false during `next build`; VERCEL_ENV=production when VERCEL_ENV is set;
+ *          otherwise NODE_ENV=production
+ */
+export const isProductionServer = (source) => {
+    if (source.NEXT_PHASE === BUILD_PHASE)
+        return false;
+    if (source.VERCEL_ENV)
+        return source.VERCEL_ENV === "production";
+    return source.NODE_ENV === "production";
+};
+/**
+ * @function isEnvValidationSkipped
+ * @param source {EnvSource} usually process.env (the default)
+ * @returns {boolean} true in CI builds (SKIP_ENV_VALIDATION=true), where nothing may query the
+ *          database: public pages then prerender empty
+ */
+export const isEnvValidationSkipped = (source = process.env) => source.SKIP_ENV_VALIDATION === "true";
+/**
+ * @function createServerEnv
+ * @param options {ServerEnvOptions<S>} the schema, its placeholders and which keys are secrets
+ * @returns {ServerEnv<z.output<S>>} parse, pick, get (memoized), reset and the placeholder guard
+ */
+export const createServerEnv = ({ schema, placeholders, secretKeys, }) => {
+    const keys = Object.freeze(Object.keys(schema.shape));
+    const values = placeholders;
+    const assertNoPlaceholderSecrets = (source, checked = secretKeys) => {
+        if (!isEnvValidationSkipped(source) || !isProductionServer(source))
+            return;
+        const found = checked.filter((key) => {
+            const value = source[key]?.trim();
+            return !value || value === values[key];
+        });
+        if (found.length === 0)
+            return;
+        throw new EnvError(`SKIP_ENV_VALIDATION is set on a production server, so ${found.join(", ")} would fall back to public placeholders. Set the real values and unset SKIP_ENV_VALIDATION.`);
+    };
+    const pick = (source, wanted) => {
+        const present = {};
+        for (const key of wanted) {
+            const value = source[key]?.trim();
+            if (value)
+                present[key] = value;
+        }
+        if (isEnvValidationSkipped(source)) {
+            assertNoPlaceholderSecrets(source, secretKeys.filter((key) => wanted.includes(key)));
+            const fallback = Object.fromEntries(wanted.map((key) => [key, values[key]]));
+            return { ...fallback, ...present };
+        }
+        const mask = Object.fromEntries(wanted.map((key) => [key, true]));
+        const picked = schema.pick(mask);
+        const parsed = picked.safeParse(present);
+        if (parsed.success)
+            return parsed.data;
+        throw invalidEnv([...new Set(parsed.error.issues.map((issue) => String(issue.path[0])))]);
+    };
+    let cached = null;
+    return {
+        keys,
+        parse: (source) => pick(source, keys),
+        pick,
+        get: () => {
+            cached ??= pick(process.env, keys);
+            return cached;
+        },
+        reset: () => {
+            cached = null;
+        },
+        assertNoPlaceholderSecrets,
+    };
+};

package/dist/mongo/client.d.ts

@@ -0,0 +1,56 @@
+/**
+ * @file src/mongo/client.ts
+ * @desc One MongoClient per process, built on first use (never at import, so builds and pages
+ *       without a database need no env). The database is always the one named here, whatever
+ *       the URI says. better-auth reads getDb(); Mongoose models live on getModelConnection(),
+ *       attached to the same client. The first connect runs the app's onConnect (index builds,
+ *       a privilege check, a backfill). State sits on globalThis so dev reloads don't leak
+ *       clients; a failed connect is never cached, so one DNS blip can't poison the process.
+ *       Moved from packs and pools (src/lib/db.ts), identical apart from the name, the global
+ *       key and pools' post-connect work.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Mon Sep 28, 2026
+ * @modified Mon Sep 28, 2026
+ */
+import { type Db, MongoClient } from "mongodb";
+import { type Connection } from "mongoose";
+/** Two apps share one M0 cluster (500 connections), each over many Vercel instances. */
+export declare const DEFAULT_MAX_POOL_SIZE = 5;
+/** Fail fast when the cluster is unreachable: a hung function is billed for every second. */
+export declare const DEFAULT_SERVER_SELECTION_TIMEOUT_MS = 5000;
+/** createMongo's options. */
+export type MongoOptions = {
+    /** The database every call uses, like "packs" or "pools". */
+    dbName: string;
+    /** The globalThis key the state lives under, like "__poolsMongo"; one per app. */
+    globalKey: string;
+    /** Reads MONGODB_URI (on first use, not at import). */
+    uri: () => string;
+    /** Connections per instance (default DEFAULT_MAX_POOL_SIZE). */
+    maxPoolSize?: number;
+    /** How long to look for a server (default DEFAULT_SERVER_SELECTION_TIMEOUT_MS). */
+    serverSelectionTimeoutMS?: number;
+    /** Runs once after the first successful connect; a throw fails that connect. */
+    onConnect?: (db: Db, client: MongoClient) => Promise<void>;
+};
+/** What createMongo returns. */
+export type Mongo = {
+    /** The shared client (connects lazily on first operation). */
+    getMongoClient: () => MongoClient;
+    /** The database on the shared client. */
+    getDb: () => Db;
+    /** The Mongoose connection models register on (usable after connectDb). */
+    getModelConnection: () => Connection;
+    /** Connects once, attaches Mongoose and runs onConnect; retried after a failure. */
+    connectDb: () => Promise<void>;
+    /** The database once connectDb has resolved. */
+    connectedDb: () => Promise<Db>;
+    /** Closes the client and forgets it (tests, CLIs). */
+    closeDb: () => Promise<void>;
+};
+/**
+ * @function createMongo
+ * @param options {MongoOptions} the database, the global key, the URI and the start-up work
+ * @returns {Mongo} getMongoClient, getDb, getModelConnection, connectDb, connectedDb, closeDb
+ */
+export declare const createMongo: ({ dbName, globalKey, uri, maxPoolSize, serverSelectionTimeoutMS, onConnect, }: MongoOptions) => Mongo;

package/dist/mongo/client.js

@@ -0,0 +1,72 @@
+/**
+ * @file src/mongo/client.ts
+ * @desc One MongoClient per process, built on first use (never at import, so builds and pages
+ *       without a database need no env). The database is always the one named here, whatever
+ *       the URI says. better-auth reads getDb(); Mongoose models live on getModelConnection(),
+ *       attached to the same client. The first connect runs the app's onConnect (index builds,
+ *       a privilege check, a backfill). State sits on globalThis so dev reloads don't leak
+ *       clients; a failed connect is never cached, so one DNS blip can't poison the process.
+ *       Moved from packs and pools (src/lib/db.ts), identical apart from the name, the global
+ *       key and pools' post-connect work.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Mon Sep 28, 2026
+ * @modified Mon Sep 28, 2026
+ */
+import { MongoClient } from "mongodb";
+import mongoose, {} from "mongoose";
+/** Two apps share one M0 cluster (500 connections), each over many Vercel instances. */
+export const DEFAULT_MAX_POOL_SIZE = 5;
+/** Fail fast when the cluster is unreachable: a hung function is billed for every second. */
+export const DEFAULT_SERVER_SELECTION_TIMEOUT_MS = 5000;
+/**
+ * @function createMongo
+ * @param options {MongoOptions} the database, the global key, the URI and the start-up work
+ * @returns {Mongo} getMongoClient, getDb, getModelConnection, connectDb, connectedDb, closeDb
+ */
+export const createMongo = ({ dbName, globalKey, uri, maxPoolSize = DEFAULT_MAX_POOL_SIZE, serverSelectionTimeoutMS = DEFAULT_SERVER_SELECTION_TIMEOUT_MS, onConnect, }) => {
+    const store = globalThis;
+    const createState = () => {
+        const client = new MongoClient(uri(), { maxPoolSize, serverSelectionTimeoutMS });
+        const base = mongoose.createConnection();
+        // Connection#useDb, not a React hook. The URI has no path, so pick the database here.
+        const models = base.useDb(dbName, { useCache: true });
+        return { client, base, models, ready: null };
+    };
+    const state = () => {
+        store[globalKey] ??= createState();
+        return store[globalKey];
+    };
+    const getDb = () => state().client.db(dbName);
+    const connectDb = async () => {
+        const current = state();
+        current.ready ??= current.client.connect().then(async () => {
+            if (current.base.readyState === 0)
+                current.base.setClient(current.client);
+            await onConnect?.(current.client.db(dbName), current.client);
+        });
+        try {
+            await current.ready;
+        }
+        catch (error) {
+            current.ready = null;
+            throw error;
+        }
+    };
+    return {
+        getMongoClient: () => state().client,
+        getDb,
+        getModelConnection: () => state().models,
+        connectDb,
+        connectedDb: async () => {
+            await connectDb();
+            return getDb();
+        },
+        closeDb: async () => {
+            const current = store[globalKey];
+            if (!current)
+                return;
+            store[globalKey] = undefined;
+            await current.client.close();
+        },
+    };
+};

package/dist/mongo/collections.d.ts

@@ -0,0 +1,16 @@
+/**
+ * @file src/mongo/collections.ts
+ * @desc The collection-name constants pattern both apps use (src/constants/db.ts): one frozen
+ *       object naming every collection, checked once at load, so a typo or two names for one
+ *       collection fails at start instead of writing somewhere nobody reads.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Mon Sep 28, 2026
+ * @modified Mon Sep 28, 2026
+ */
+/**
+ * @function defineCollections
+ * @param names {T} constant key to collection name, like { pools: "pools", rateLimits: "rate_limits" }
+ * @returns {Readonly<T>} the same names, frozen
+ * @throws {Error} naming the key whose collection name is invalid or used twice
+ */
+export declare const defineCollections: <const T extends Record<string, string>>(names: T) => Readonly<T>;

package/dist/mongo/collections.js

@@ -0,0 +1,29 @@
+/**
+ * @file src/mongo/collections.ts
+ * @desc The collection-name constants pattern both apps use (src/constants/db.ts): one frozen
+ *       object naming every collection, checked once at load, so a typo or two names for one
+ *       collection fails at start instead of writing somewhere nobody reads.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Mon Sep 28, 2026
+ * @modified Mon Sep 28, 2026
+ */
+/** MongoDB's collection name rules: no $, no NUL, not empty, not a system collection. */
+const COLLECTION_NAME = /^(?!system\.)[^$\0]{1,120}$/;
+/**
+ * @function defineCollections
+ * @param names {T} constant key to collection name, like { pools: "pools", rateLimits: "rate_limits" }
+ * @returns {Readonly<T>} the same names, frozen
+ * @throws {Error} naming the key whose collection name is invalid or used twice
+ */
+export const defineCollections = (names) => {
+    const seen = new Map();
+    for (const [key, name] of Object.entries(names)) {
+        if (!COLLECTION_NAME.test(name))
+            throw new Error(`defineCollections: ${key} isn't a valid name`);
+        const other = seen.get(name);
+        if (other)
+            throw new Error(`defineCollections: ${key} and ${other} both name "${name}"`);
+        seen.set(name, key);
+    }
+    return Object.freeze({ ...names });
+};