Skip to content

AGENTS.md

Latest commit

 

History

History
21 lines (17 loc) · 2.44 KB

AGENTS.md

File metadata and controls

21 lines (17 loc) · 2.44 KB
Raw

AGENTS.md

CommonJS Express middleware/handler utility library published to npm.

Commands

  • npm run build — esbuild bundles index.js into dist/bundle.js (packages: "external", minified). dist/ is gitignored, so rebuild after editing src/ or index.js; main: "dist/bundle.js".
  • npm test — stub no-op (echo ... && exit 0). There are no real tests; verify by building and manually exercising handlers.
  • npm run docs — generates API docs from JSDoc (jsdoc-to-mdx, config.json) into docs/docs/api; pages like getting-started.md/installation.md are hand-written. The docs/ tree is a separate Docusaurus project (npm ci && npm run build there).
  • npm run dev — just runs node index.js (loads every handler, exports them, exits). No server to run.

Structure & conventions

  • Single entry point: index.js re-exports every handler. Any new handler must be added to index.js exports.
  • One handler per file at src/<name>.handler.js (e.g. src/async.handler.js), CommonJS named exports. Some files export several helpers (log.handler.js: transports, initLogger, streamHandler, logHandler; password.handler.js: hashHandler, passwordHandler). Every export must be re-exported from index.js. Double quotes, 2-space indent, arrow functions, terminal semicolons.
  • Every export needs a JSDoc block (@function, @param, @example) — it is the source for generated docs.
  • No linter, formatter, or type checker is configured; match existing style manually.

Gotchas

  • DB/queue connection handlers are real, async connection initializers (initRedis, initPostgres, initMongo, initQueue), each taking a config object and returning a Promise. Don't run them casually — they connect live and reject/throw on missing config or failed connect (they no longer call process.exit). postgresHandler/mongoHandler legacy names are gone; initMongo returned Value differs (mongoose connection).
  • All deps (mongoose, redis, pg, bcrypt, socket.io, etc.) are regular dependencies and stay external in the bundle; the npm CLI handles install.
  • authenticationHandler/tokenHandler use jsonwebtoken (JWT_SECRET-style env config); redis.handler requires a url in config.
  • Docs site is published via GitHub Pages on push to master (.github/workflows/deploy.yml); npm publish runs on release creation (.github/workflows/npm-publish.yml, needs NPM_TOKEN). Default branch is master.