@codecorn/empty-session-reaper

Tiny middleware to prune _or debug_ empty sessions (cookie-only + your rules) and keep Prisma/Redis stores lean.
Agnostic core — no app-specific keys inside. Bring your own policy via options.

---

Features

- 🧹 Prune sessions that are “empty” under your rules.
- 🔎 Debug with dry-run + logger; optional session mutation logger.
- 🧩 Agnostic: pass allowlists, predicates, denylists — no hardcoded keys.
- 🧪 Store-agnostic: Prisma/SQL, Redis, etc.
- ⚙️ Composable predicates (emptyObject, equals, oneOf, and, or, flashEmptyOrOneOf).
- 🧰 Optional preset: cookieFlash() — beginner-friendly.
- 🧯 Safe by design: no env access, tiny footprint.

---

Install

``bash
npm i @codecorn/empty-session-reaper
`

$3

`js
// ✅ CommonJS (require)
const {
wireEmptySessionReaper,
predicates,
buildAllowedKeys,
wireSessionMutationLogger, // optional: logs added/removed keys
} = require("@codecorn/empty-session-reaper");
const { cookieFlash } = require("@codecorn/empty-session-reaper/presets");
`

`ts
// ✅ ESM / TypeScript
import {
wireEmptySessionReaper,
predicates as P,
buildAllowedKeys,
wireSessionMutationLogger, // optional
} from "@codecorn/empty-session-reaper";
import { cookieFlash } from "@codecorn/empty-session-reaper/presets";
`

---

Usage A — minimal “cookie + empty flash”

`ts
// Meaning of buildAllowedKeys(input, expandBase, base):
// - base: starting list (default: ['cookie'])
// - input: extra keys to allow (e.g., ['flash'])
// - expandBase:
// true => merge base + input (e.g., ['cookie'] + ['flash'] -> ['cookie','flash'])
// false => use input only (e.g., ['flash'])
wireEmptySessionReaper(app, {
logger: (m, meta) => console.debug(m, meta),

allowedKeys: buildAllowedKeys(["flash"], true, ["cookie"]),
// ↑ allowlist = merge base ['cookie'] + ['flash'] → ['cookie','flash']
maxKeys: 2,

keyPredicates: {
// flash is harmless if it's an empty object {}
flash: P.emptyObject,
},
});
`

Usage B — advanced custom policy (full control)

`ts
const isLoginFlash = (flash: any) => {
if (!flash || typeof flash !== "object") return false;
const ks = Object.keys(flash);
if (ks.length !== 1) return false;
const arr = Array.isArray((flash as any)[ks[0]]) ? (flash as any)[ks[0]] : [];
return arr.length === 1 && /^please sign in\.?$/i.test(String(arr[0] || ""));
};

wireEmptySessionReaper(app, {
logger: (m, meta) => console.debug(m, meta),

allowedKeys: ["cookie", "flash", "url", "flag"],
maxKeys: 4,

disallowedKeyPatterns: [/^csrf/i, /^token/i, /^user/i],

keyPredicates: {
flash: (v) => P.emptyObject(v) || isLoginFlash(v),
url: (v) => ["/", "/login", "/signin"].includes(String(v || "")),
flag: P.oneOf([false, "auto"]),
},

isSessionPrunable: (s) => {
const url = String((s as any).url || "");
return !(/\.(env|git)\b/i.test(url) || /\/upload\/\./i.test(url));
},
});
`

Usage C — optional preset cookieFlash

`ts
const preset = cookieFlash({
// flashKey: 'flash',
// flashField: 'error',
// loginMessages: [/^please sign in\.?$/i, /^access denied$/i],
// extraAllowedKeys: ['url'],
// maxKeys: 3,
// disallowedKeyPatterns: [/^csrf/i, /^token/i],
// extraPredicates: { url: (v) => ['/', '/login'].includes(String(v || '')) },
// finalCheck: (s) => !/\.env\b/i.test(String((s as any).url || '')),
});
wireEmptySessionReaper(app, { logger: console.debug, ...preset });
`

---

Bonus: Session mutation logger (discover origins)

`ts
// Place AFTER session(...) and BEFORE the reaper:
wireSessionMutationLogger(app, {
logger: (label, meta) => console.debug(label, meta),
includeValues: false, // true to also log shallow values (use redact to mask)
redact: (k, v) => (/(token|secret|pass)/i.test(k) ? "[redacted]" : v),
label: "session mutation",
});
`

> Logs { path, added: [...], removed: [...] } on each response where the session keys changed.

---

API (core)

`txt
createEmptySessionReaper(opts) -> (req, res, next) => void
Create the middleware with your pruning policy.

wireEmptySessionReaper(app, opts) -> middleware
Mounts the middleware on the app and returns it.

buildAllowedKeys(input?: string[], expandBase?: boolean, base?: string[]) -> string[]
Helper to compose allowlists.
- base: starting list (default: ["cookie"])
- input: extra allowed keys (e.g., ["flash"])
- expandBase:
true -> merge base + input
false -> use input only

predicates:
- emptyObject(v)
- equals(x)
- oneOf([a,b,c])
- and(p1,p2,...)
- or(p1,p2,...)
- flashEmptyOrOneOf(field='error', messages=[/^please sign in\.?$/i])

createSessionMutationLogger(opts) -> middleware
wireSessionMutationLogger(app, opts) -> middleware
lookUpSessMutation(app, opts) -> alias of wireSessionMutationLogger
``

---

📝 License

MIT © CodeCorn™

Distributed under the MIT license.

Credits

- Cousìn (co-author & review) — _PYTORCHIA FOR LIFE_
- Federico Girolami (CodeCorn) — Maintainer

---

👤 Maintainer

👨‍💻 Federico Girolami

Full Stack Developer | System Integrator | Digital Solution Architect 🚀

📫 Get in Touch

🌐 Website: codecorn.it (Under Construction)

📧 Email: f.girolami@codecorn.it

🐙 GitHub: github.com/fgirolami29

---

$3

Pull requests are welcome. For major changes, please open an issue first to discuss what you’d like to change.

> Powered by CodeCorn™ 🚀

---