express-file-cluster 0.10.2 → 0.11.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (86) hide show
  1. package/dist/auth/index.cjs +4 -4
  2. package/dist/auth/index.d.cts +3 -1
  3. package/dist/auth/index.d.ts +3 -1
  4. package/dist/auth/index.js +3 -3
  5. package/dist/{chunk-V73R76I4.js → chunk-2IDRC7RK.js} +2 -1
  6. package/dist/{chunk-RETV3GKE.js → chunk-336IU55W.js} +2 -2
  7. package/dist/{chunk-7BC3AN7R.cjs → chunk-6WTMRZS7.cjs} +8 -8
  8. package/dist/{chunk-7BC3AN7R.cjs.map → chunk-6WTMRZS7.cjs.map} +1 -1
  9. package/dist/chunk-DGYPIIJE.cjs +845 -0
  10. package/dist/chunk-DGYPIIJE.cjs.map +1 -0
  11. package/dist/{chunk-TBIVIR6L.cjs → chunk-DTMDJGRW.cjs} +8 -8
  12. package/dist/{chunk-TBIVIR6L.cjs.map → chunk-DTMDJGRW.cjs.map} +1 -1
  13. package/dist/{chunk-MUVO7MGS.js → chunk-EJDZZ4KX.js} +2 -2
  14. package/dist/{chunk-IUZ6A7PB.cjs → chunk-GWMW6XY7.cjs} +13 -13
  15. package/dist/{chunk-IUZ6A7PB.cjs.map → chunk-GWMW6XY7.cjs.map} +1 -1
  16. package/dist/{chunk-Y4NKIXUL.cjs → chunk-IEF6AEK3.cjs} +13 -13
  17. package/dist/{chunk-Y4NKIXUL.cjs.map → chunk-IEF6AEK3.cjs.map} +1 -1
  18. package/dist/{chunk-BG4A7Z32.js → chunk-JBOMTZT5.js} +3 -3
  19. package/dist/chunk-LECHRAU3.js +845 -0
  20. package/dist/chunk-LECHRAU3.js.map +1 -0
  21. package/dist/{chunk-5LPRKZPB.js → chunk-O2E7H2XA.js} +2 -2
  22. package/dist/{chunk-C2FOZ7ME.js → chunk-OM2XJJWX.js} +2 -2
  23. package/dist/{chunk-JP36TLL4.cjs → chunk-QSIP7YLW.cjs} +3 -2
  24. package/dist/chunk-QSIP7YLW.cjs.map +1 -0
  25. package/dist/{chunk-Y75V5FCU.js → chunk-R6GPQZLI.js} +3 -3
  26. package/dist/{chunk-R2K7AFIB.cjs → chunk-SOU3PBJC.cjs} +89 -89
  27. package/dist/{chunk-R2K7AFIB.cjs.map → chunk-SOU3PBJC.cjs.map} +1 -1
  28. package/dist/{chunk-4GHK27JA.cjs → chunk-WHBSVYUY.cjs} +3 -3
  29. package/dist/{chunk-4GHK27JA.cjs.map → chunk-WHBSVYUY.cjs.map} +1 -1
  30. package/dist/cli/db-runner.cjs +24 -24
  31. package/dist/cli/db-runner.js +3 -3
  32. package/dist/cli/index.cjs +8 -8
  33. package/dist/cli/index.js +5 -5
  34. package/dist/docs/api-reference/ignite.md +4 -0
  35. package/dist/docs/api-reference/openapi.md +36 -0
  36. package/dist/docs/api-reference/testing.md +2 -0
  37. package/dist/docs/api-reference/websockets.md +23 -0
  38. package/dist/docs/cli/add.md +1 -1
  39. package/dist/docs/core-concepts/clustering.md +2 -0
  40. package/dist/docs/core-concepts/file-based-routing.md +2 -0
  41. package/dist/docs/guides/feature-matrix.md +9 -0
  42. package/dist/docs/guides/openapi.md +57 -0
  43. package/dist/docs/guides/validation.md +2 -0
  44. package/dist/docs/guides/websockets.md +60 -0
  45. package/dist/docs/index.md +3 -1
  46. package/dist/docs/skills/SKILL.md +4 -2
  47. package/dist/docs/skills/api-surface.md +10 -0
  48. package/dist/docs/skills/pre-flight.md +2 -0
  49. package/dist/docs/skills/routing-rules.md +4 -0
  50. package/dist/docs/skills/what-not-to-invent.md +2 -0
  51. package/dist/index.cjs +75 -53
  52. package/dist/index.cjs.map +1 -1
  53. package/dist/index.d.cts +3 -2
  54. package/dist/index.d.ts +3 -2
  55. package/dist/index.js +32 -11
  56. package/dist/index.js.map +1 -1
  57. package/dist/openapi-cjs.cjs +5 -0
  58. package/dist/{pgboss-backend-4X2YT4RB.js → pgboss-backend-PQW6I3VF.js} +3 -3
  59. package/dist/pgboss-backend-QVXISTLP.cjs +15 -0
  60. package/dist/{pgboss-backend-UXQ3O2WT.cjs.map → pgboss-backend-QVXISTLP.cjs.map} +1 -1
  61. package/dist/registry/index.json +1 -1
  62. package/dist/tasks/index.d.cts +3 -1
  63. package/dist/tasks/index.d.ts +3 -1
  64. package/dist/testing.cjs +16 -10
  65. package/dist/testing.cjs.map +1 -1
  66. package/dist/testing.d.cts +4 -1
  67. package/dist/testing.d.ts +4 -1
  68. package/dist/testing.js +12 -6
  69. package/dist/testing.js.map +1 -1
  70. package/dist/{types-CPMFTVXm.d.cts → types-D3QmZgeX.d.cts} +80 -2
  71. package/dist/{types-CPMFTVXm.d.ts → types-D3QmZgeX.d.ts} +80 -2
  72. package/package.json +6 -4
  73. package/dist/chunk-74BSJXWD.cjs +0 -220
  74. package/dist/chunk-74BSJXWD.cjs.map +0 -1
  75. package/dist/chunk-JP36TLL4.cjs.map +0 -1
  76. package/dist/chunk-KLWL7XSC.js +0 -220
  77. package/dist/chunk-KLWL7XSC.js.map +0 -1
  78. package/dist/pgboss-backend-UXQ3O2WT.cjs +0 -15
  79. /package/dist/{chunk-V73R76I4.js.map → chunk-2IDRC7RK.js.map} +0 -0
  80. /package/dist/{chunk-RETV3GKE.js.map → chunk-336IU55W.js.map} +0 -0
  81. /package/dist/{chunk-MUVO7MGS.js.map → chunk-EJDZZ4KX.js.map} +0 -0
  82. /package/dist/{chunk-BG4A7Z32.js.map → chunk-JBOMTZT5.js.map} +0 -0
  83. /package/dist/{chunk-5LPRKZPB.js.map → chunk-O2E7H2XA.js.map} +0 -0
  84. /package/dist/{chunk-C2FOZ7ME.js.map → chunk-OM2XJJWX.js.map} +0 -0
  85. /package/dist/{chunk-Y75V5FCU.js.map → chunk-R6GPQZLI.js.map} +0 -0
  86. /package/dist/{pgboss-backend-4X2YT4RB.js.map → pgboss-backend-PQW6I3VF.js.map} +0 -0
@@ -1,6 +1,6 @@
1
1
  "use strict";Object.defineProperty(exports, "__esModule", {value: true}); function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
2
2
 
3
- var _chunkJP36TLL4cjs = require('./chunk-JP36TLL4.cjs');
3
+ var _chunkQSIP7YLWcjs = require('./chunk-QSIP7YLW.cjs');
4
4
 
5
5
  // src/router/scan.ts
6
6
  var _fs = require('fs'); var _fs2 = _interopRequireDefault(_fs);
@@ -82,7 +82,7 @@ function compareSpecificity(a, b) {
82
82
  function scanDir(dir, base = dir, maxDepth = DEFAULT_MAX_DEPTH, _depth = 0) {
83
83
  if (!_fs2.default.existsSync(dir)) return [];
84
84
  if (_depth > maxDepth) {
85
- _chunkJP36TLL4cjs.getLogger.call(void 0, ).warn(`scanDir: max depth (${maxDepth}) reached at ${dir}, skipping subtree`);
85
+ _chunkQSIP7YLWcjs.getLogger.call(void 0, ).warn(`scanDir: max depth (${maxDepth}) reached at ${dir}, skipping subtree`);
86
86
  return [];
87
87
  }
88
88
  const entries = [];
@@ -113,4 +113,4 @@ function scanDir(dir, base = dir, maxDepth = DEFAULT_MAX_DEPTH, _depth = 0) {
113
113
 
114
114
 
115
115
  exports.scanDir = scanDir;
116
- //# sourceMappingURL=chunk-4GHK27JA.cjs.map
116
+ //# sourceMappingURL=chunk-WHBSVYUY.cjs.map
@@ -1 +1 @@
1
- {"version":3,"sources":["/home/runner/work/express-file-cluster/express-file-cluster/packages/core/dist/chunk-4GHK27JA.cjs","../src/router/scan.ts"],"names":[],"mappings":"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","file":"/home/runner/work/express-file-cluster/express-file-cluster/packages/core/dist/chunk-4GHK27JA.cjs","sourcesContent":[null,"import fs from 'node:fs';\nimport path from 'node:path';\nimport type { RouteEntry } from '../types.js';\nimport { getLogger } from '../logger.js';\n\nconst ROUTE_FILE_RE = /\\.(ts|js|mts|mjs|cts|cjs)$/;\nconst DYNAMIC_SEGMENT_RE = /\\[([^\\]]+)\\]/g;\n\n/** Maximum directory depth scanDir will recurse into by default. */\nconst DEFAULT_MAX_DEPTH = 10;\n\n// Match order within one position: static, then [id], then [[id]], then [...slug],\n// then [[...slug]]. Comparing these ranks segment by segment means a more specific\n// route always registers (and so matches) first.\nconst enum Rank {\n Static = 0,\n Dynamic = 1,\n Optional = 2,\n CatchAll = 3,\n OptionalCatchAll = 4,\n}\n\ninterface Segment {\n rank: Rank;\n /** Express-style display/path form: `users`, `:id`, `:id?`, `:slug*`, `:slug*?`. */\n display: string;\n name?: string;\n}\n\nfunction parseSegment(raw: string): Segment {\n let m: RegExpMatchArray | null;\n if ((m = raw.match(/^\\[\\[\\.\\.\\.([^\\]]+)\\]\\]$/)))\n return { rank: Rank.OptionalCatchAll, display: `:${m[1]}*?`, name: m[1]! };\n if ((m = raw.match(/^\\[\\.\\.\\.([^\\]]+)\\]$/)))\n return { rank: Rank.CatchAll, display: `:${m[1]}*`, name: m[1]! };\n if ((m = raw.match(/^\\[\\[([^\\]]+)\\]\\]$/)))\n return { rank: Rank.Optional, display: `:${m[1]}?`, name: m[1]! };\n if (raw.includes('['))\n return { rank: Rank.Dynamic, display: raw.replace(DYNAMIC_SEGMENT_RE, ':$1') };\n return { rank: Rank.Static, display: raw };\n}\n\nfunction segmentsOf(relativePath: string): Segment[] {\n const p = relativePath.replace(ROUTE_FILE_RE, '').replace(/(^|\\/)index$/, '');\n return p.split('/').filter(Boolean).map(parseSegment);\n}\n\nfunction filePathToUrlPath(relativePath: string): string {\n const segs = segmentsOf(relativePath);\n return segs.length === 0 ? '/' : '/' + segs.map((s) => s.display).join('/');\n}\n\nfunction extractParams(relativePath: string): string[] {\n const params: string[] = [];\n for (const raw of relativePath.split('/')) {\n const re = /\\[+(?:\\.\\.\\.)?([^\\]]+)\\]+/g;\n let match: RegExpExecArray | null;\n while ((match = re.exec(raw)) !== null) {\n if (match[1]) params.push(match[1]);\n }\n }\n return params;\n}\n\nfunction escapeRegExp(s: string): string {\n return s.replace(/[.*+?^${}()|[\\]\\\\]/g, '\\\\$&');\n}\n\n/**\n * Express 4's string paths can't express a multi-segment catch-all with a name, so\n * routes containing one are mounted on a RegExp; captures come back in segment order\n * and mount.ts maps them onto the names in `params`.\n */\nfunction buildPattern(segs: Segment[]): RegExp | undefined {\n const last = segs.length - 1;\n segs.forEach((s, i) => {\n if (i !== last && (s.rank === Rank.CatchAll || s.rank === Rank.OptionalCatchAll)) {\n throw new Error(`[EFC] Catch-all segment \"${s.display}\" must be the last path segment`);\n }\n });\n if (!segs.some((s) => s.rank >= Rank.CatchAll)) return undefined;\n\n let src = '';\n for (const s of segs) {\n switch (s.rank) {\n case Rank.Static:\n src += '/' + escapeRegExp(s.display);\n break;\n case Rank.Dynamic:\n src += '/' + escapeRegExp(s.display).replace(/:[A-Za-z0-9_$]+/g, '([^/]+?)');\n break;\n case Rank.Optional:\n src += '(?:/([^/]+?))?';\n break;\n case Rank.CatchAll:\n src += '/(.+?)';\n break;\n case Rank.OptionalCatchAll:\n src += '(?:/(.*?))?';\n break;\n }\n }\n return new RegExp(`^${src || ''}/?$`, 'i');\n}\n\nfunction compareSpecificity(a: Segment[], b: Segment[]): number {\n for (let i = 0; i < Math.min(a.length, b.length); i++) {\n const diff = a[i]!.rank - b[i]!.rank;\n if (diff !== 0) return diff;\n }\n return 0;\n}\n\n/**\n * Recursively scans `dir` for route files and returns a sorted list of\n * `RouteEntry` objects, most specific first: at each path position a static\n * segment beats `[id]`, which beats `[[id]]`, then `[...slug]`, then\n * `[[...slug]]`. Ties are sorted alphabetically.\n *\n * @param dir - Root directory to scan (must exist).\n * @param base - Base directory used to derive relative URL paths; defaults to `dir`.\n * @param maxDepth - Maximum recursion depth (default: 10). Guards against\n * circular symlinks or unexpectedly deep directory trees.\n * @param _depth - Internal current depth counter — do not pass externally.\n */\nexport function scanDir(\n dir: string,\n base: string = dir,\n maxDepth: number = DEFAULT_MAX_DEPTH,\n _depth: number = 0,\n): RouteEntry[] {\n if (!fs.existsSync(dir)) return [];\n if (_depth > maxDepth) {\n getLogger().warn(`scanDir: max depth (${maxDepth}) reached at ${dir}, skipping subtree`);\n return [];\n }\n\n const entries: RouteEntry[] = [];\n const items = fs.readdirSync(dir, { withFileTypes: true });\n\n for (const item of items) {\n const fullPath = path.join(dir, item.name);\n if (item.isDirectory()) {\n entries.push(...scanDir(fullPath, base, maxDepth, _depth + 1));\n } else if (ROUTE_FILE_RE.test(item.name)) {\n const relative = '/' + path.relative(base, fullPath).replace(/\\\\/g, '/');\n const segs = segmentsOf(relative);\n const pattern = buildPattern(segs);\n entries.push({\n urlPath: filePathToUrlPath(relative),\n filePath: fullPath,\n params: extractParams(relative),\n ...(pattern !== undefined && { pattern }),\n });\n }\n }\n\n // Most specific first (segment-by-segment rank), ties broken alphabetically.\n const rel = (e: RouteEntry) => '/' + path.relative(base, e.filePath).replace(/\\\\/g, '/');\n return entries.sort((a, b) => {\n const diff = compareSpecificity(segmentsOf(rel(a)), segmentsOf(rel(b)));\n return diff !== 0 ? diff : a.urlPath.localeCompare(b.urlPath);\n });\n}\n\nexport { filePathToUrlPath };\n"]}
1
+ {"version":3,"sources":["/home/runner/work/express-file-cluster/express-file-cluster/packages/core/dist/chunk-WHBSVYUY.cjs","../src/router/scan.ts"],"names":[],"mappings":"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","file":"/home/runner/work/express-file-cluster/express-file-cluster/packages/core/dist/chunk-WHBSVYUY.cjs","sourcesContent":[null,"import fs from 'node:fs';\nimport path from 'node:path';\nimport type { RouteEntry } from '../types.js';\nimport { getLogger } from '../logger.js';\n\nconst ROUTE_FILE_RE = /\\.(ts|js|mts|mjs|cts|cjs)$/;\nconst DYNAMIC_SEGMENT_RE = /\\[([^\\]]+)\\]/g;\n\n/** Maximum directory depth scanDir will recurse into by default. */\nconst DEFAULT_MAX_DEPTH = 10;\n\n// Match order within one position: static, then [id], then [[id]], then [...slug],\n// then [[...slug]]. Comparing these ranks segment by segment means a more specific\n// route always registers (and so matches) first.\nconst enum Rank {\n Static = 0,\n Dynamic = 1,\n Optional = 2,\n CatchAll = 3,\n OptionalCatchAll = 4,\n}\n\ninterface Segment {\n rank: Rank;\n /** Express-style display/path form: `users`, `:id`, `:id?`, `:slug*`, `:slug*?`. */\n display: string;\n name?: string;\n}\n\nfunction parseSegment(raw: string): Segment {\n let m: RegExpMatchArray | null;\n if ((m = raw.match(/^\\[\\[\\.\\.\\.([^\\]]+)\\]\\]$/)))\n return { rank: Rank.OptionalCatchAll, display: `:${m[1]}*?`, name: m[1]! };\n if ((m = raw.match(/^\\[\\.\\.\\.([^\\]]+)\\]$/)))\n return { rank: Rank.CatchAll, display: `:${m[1]}*`, name: m[1]! };\n if ((m = raw.match(/^\\[\\[([^\\]]+)\\]\\]$/)))\n return { rank: Rank.Optional, display: `:${m[1]}?`, name: m[1]! };\n if (raw.includes('['))\n return { rank: Rank.Dynamic, display: raw.replace(DYNAMIC_SEGMENT_RE, ':$1') };\n return { rank: Rank.Static, display: raw };\n}\n\nfunction segmentsOf(relativePath: string): Segment[] {\n const p = relativePath.replace(ROUTE_FILE_RE, '').replace(/(^|\\/)index$/, '');\n return p.split('/').filter(Boolean).map(parseSegment);\n}\n\nfunction filePathToUrlPath(relativePath: string): string {\n const segs = segmentsOf(relativePath);\n return segs.length === 0 ? '/' : '/' + segs.map((s) => s.display).join('/');\n}\n\nfunction extractParams(relativePath: string): string[] {\n const params: string[] = [];\n for (const raw of relativePath.split('/')) {\n const re = /\\[+(?:\\.\\.\\.)?([^\\]]+)\\]+/g;\n let match: RegExpExecArray | null;\n while ((match = re.exec(raw)) !== null) {\n if (match[1]) params.push(match[1]);\n }\n }\n return params;\n}\n\nfunction escapeRegExp(s: string): string {\n return s.replace(/[.*+?^${}()|[\\]\\\\]/g, '\\\\$&');\n}\n\n/**\n * Express 4's string paths can't express a multi-segment catch-all with a name, so\n * routes containing one are mounted on a RegExp; captures come back in segment order\n * and mount.ts maps them onto the names in `params`.\n */\nfunction buildPattern(segs: Segment[]): RegExp | undefined {\n const last = segs.length - 1;\n segs.forEach((s, i) => {\n if (i !== last && (s.rank === Rank.CatchAll || s.rank === Rank.OptionalCatchAll)) {\n throw new Error(`[EFC] Catch-all segment \"${s.display}\" must be the last path segment`);\n }\n });\n if (!segs.some((s) => s.rank >= Rank.CatchAll)) return undefined;\n\n let src = '';\n for (const s of segs) {\n switch (s.rank) {\n case Rank.Static:\n src += '/' + escapeRegExp(s.display);\n break;\n case Rank.Dynamic:\n src += '/' + escapeRegExp(s.display).replace(/:[A-Za-z0-9_$]+/g, '([^/]+?)');\n break;\n case Rank.Optional:\n src += '(?:/([^/]+?))?';\n break;\n case Rank.CatchAll:\n src += '/(.+?)';\n break;\n case Rank.OptionalCatchAll:\n src += '(?:/(.*?))?';\n break;\n }\n }\n return new RegExp(`^${src || ''}/?$`, 'i');\n}\n\nfunction compareSpecificity(a: Segment[], b: Segment[]): number {\n for (let i = 0; i < Math.min(a.length, b.length); i++) {\n const diff = a[i]!.rank - b[i]!.rank;\n if (diff !== 0) return diff;\n }\n return 0;\n}\n\n/**\n * Recursively scans `dir` for route files and returns a sorted list of\n * `RouteEntry` objects, most specific first: at each path position a static\n * segment beats `[id]`, which beats `[[id]]`, then `[...slug]`, then\n * `[[...slug]]`. Ties are sorted alphabetically.\n *\n * @param dir - Root directory to scan (must exist).\n * @param base - Base directory used to derive relative URL paths; defaults to `dir`.\n * @param maxDepth - Maximum recursion depth (default: 10). Guards against\n * circular symlinks or unexpectedly deep directory trees.\n * @param _depth - Internal current depth counter — do not pass externally.\n */\nexport function scanDir(\n dir: string,\n base: string = dir,\n maxDepth: number = DEFAULT_MAX_DEPTH,\n _depth: number = 0,\n): RouteEntry[] {\n if (!fs.existsSync(dir)) return [];\n if (_depth > maxDepth) {\n getLogger().warn(`scanDir: max depth (${maxDepth}) reached at ${dir}, skipping subtree`);\n return [];\n }\n\n const entries: RouteEntry[] = [];\n const items = fs.readdirSync(dir, { withFileTypes: true });\n\n for (const item of items) {\n const fullPath = path.join(dir, item.name);\n if (item.isDirectory()) {\n entries.push(...scanDir(fullPath, base, maxDepth, _depth + 1));\n } else if (ROUTE_FILE_RE.test(item.name)) {\n const relative = '/' + path.relative(base, fullPath).replace(/\\\\/g, '/');\n const segs = segmentsOf(relative);\n const pattern = buildPattern(segs);\n entries.push({\n urlPath: filePathToUrlPath(relative),\n filePath: fullPath,\n params: extractParams(relative),\n ...(pattern !== undefined && { pattern }),\n });\n }\n }\n\n // Most specific first (segment-by-segment rank), ties broken alphabetically.\n const rel = (e: RouteEntry) => '/' + path.relative(base, e.filePath).replace(/\\\\/g, '/');\n return entries.sort((a, b) => {\n const diff = compareSpecificity(segmentsOf(rel(a)), segmentsOf(rel(b)));\n return diff !== 0 ? diff : a.urlPath.localeCompare(b.urlPath);\n });\n}\n\nexport { filePathToUrlPath };\n"]}
@@ -2,7 +2,7 @@
2
2
 
3
3
 
4
4
 
5
- var _chunkR2K7AFIBcjs = require('../chunk-R2K7AFIB.cjs');
5
+ var _chunkSOU3PBJCcjs = require('../chunk-SOU3PBJC.cjs');
6
6
 
7
7
 
8
8
 
@@ -18,13 +18,13 @@ var _chunkM53GODCXcjs = require('../chunk-M53GODCX.cjs');
18
18
 
19
19
 
20
20
 
21
- var _chunkIUZ6A7PBcjs = require('../chunk-IUZ6A7PB.cjs');
21
+ var _chunkGWMW6XY7cjs = require('../chunk-GWMW6XY7.cjs');
22
22
  require('../chunk-AGOYTFRO.cjs');
23
23
 
24
24
 
25
25
 
26
26
 
27
- var _chunkJP36TLL4cjs = require('../chunk-JP36TLL4.cjs');
27
+ var _chunkQSIP7YLWcjs = require('../chunk-QSIP7YLW.cjs');
28
28
  require('../chunk-CGY7JU4Y.cjs');
29
29
 
30
30
  // src/cli/db-runner.ts
@@ -2261,14 +2261,14 @@ async function pullPostgres(pool, names = /* @__PURE__ */ new Map()) {
2261
2261
  const cols = colsOf(table);
2262
2262
  const notes = [];
2263
2263
  const underscored = cols.filter((c) => c.name.includes("_"));
2264
- const snake = underscored.length > 0 && underscored.every((c) => _chunkIUZ6A7PBcjs.snakeCase.call(void 0, _chunkM53GODCXcjs.camel.call(void 0, c.name)) === c.name);
2264
+ const snake = underscored.length > 0 && underscored.every((c) => _chunkGWMW6XY7cjs.snakeCase.call(void 0, _chunkM53GODCXcjs.camel.call(void 0, c.name)) === c.name);
2265
2265
  const fieldOf = (column) => snake ? _chunkM53GODCXcjs.camel.call(void 0, column) : column;
2266
2266
  const options = {};
2267
2267
  if (snake) options["naming"] = "snake_case";
2268
2268
  if (idKind !== "uuid") options["id"] = idKind;
2269
- const defaultTable = _chunkIUZ6A7PBcjs.tableNameFor.call(void 0, snake ? _chunkIUZ6A7PBcjs.snakeCase.call(void 0, name) : name);
2269
+ const defaultTable = _chunkGWMW6XY7cjs.tableNameFor.call(void 0, snake ? _chunkGWMW6XY7cjs.snakeCase.call(void 0, name) : name);
2270
2270
  if (defaultTable !== table) options["collection"] = table;
2271
- const tsColumn = (f) => cols.find((c) => c.name === (snake ? _chunkIUZ6A7PBcjs.snakeCase.call(void 0, f) : f));
2271
+ const tsColumn = (f) => cols.find((c) => c.name === (snake ? _chunkGWMW6XY7cjs.snakeCase.call(void 0, f) : f));
2272
2272
  const isTs = (c) => _optionalChain([c, 'optionalAccess', _19 => _19.type]) === "timestamp with time zone";
2273
2273
  const hasCreated = isTs(tsColumn("createdAt"));
2274
2274
  const hasUpdated = isTs(tsColumn("updatedAt"));
@@ -2325,7 +2325,7 @@ async function pullPostgres(pool, names = /* @__PURE__ */ new Map()) {
2325
2325
  def["default"] = /^'((?:[^']|'')*)'/.exec(d)[1].replace(/''/g, "'");
2326
2326
  else notes.push(`${field}: database default ${d} not carried over`);
2327
2327
  }
2328
- if ((snake ? _chunkIUZ6A7PBcjs.snakeCase.call(void 0, field) : field) !== col.name) def["column"] = col.name;
2328
+ if ((snake ? _chunkGWMW6XY7cjs.snakeCase.call(void 0, field) : field) !== col.name) def["column"] = col.name;
2329
2329
  const fk = tableFks.find((f) => f.columns.length === 1 && f.columns[0] === col.name);
2330
2330
  if (fk) {
2331
2331
  const target = modelName(fk.target);
@@ -2368,7 +2368,7 @@ async function pullPostgres(pool, names = /* @__PURE__ */ new Map()) {
2368
2368
  const of = target.idKind === "uuid" ? "uuid" : target.idKind === "bigserial" ? "bigint" : "integer";
2369
2369
  fields.push([fieldOf(j.column), { type: "array", of, ref: target.name }]);
2370
2370
  }
2371
- const fieldOfColumn = (c) => _nullishCoalesce(_optionalChain([fields, 'access', _31 => _31.find, 'call', _32 => _32(([f, d]) => (_nullishCoalesce(d["column"], () => ( (snake ? _chunkIUZ6A7PBcjs.snakeCase.call(void 0, f) : f)))) === c), 'optionalAccess', _33 => _33[0]]), () => ( fieldOf(c)));
2371
+ const fieldOfColumn = (c) => _nullishCoalesce(_optionalChain([fields, 'access', _31 => _31.find, 'call', _32 => _32(([f, d]) => (_nullishCoalesce(d["column"], () => ( (snake ? _chunkGWMW6XY7cjs.snakeCase.call(void 0, f) : f)))) === c), 'optionalAccess', _33 => _33[0]]), () => ( fieldOf(c)));
2372
2372
  const indexDefs = [];
2373
2373
  for (const idx of tableIndexes) {
2374
2374
  if (usedIndexes.has(idx.name)) continue;
@@ -2676,7 +2676,7 @@ async function importModels(root) {
2676
2676
  walk(_path2.default.join(root, "model"));
2677
2677
  walk(_path2.default.join(root, "models"));
2678
2678
  for (const f of files.sort()) await Promise.resolve().then(() => _interopRequireWildcard(require(_url.pathToFileURL.call(void 0, f).href)));
2679
- return _chunkIUZ6A7PBcjs.registeredModels.call(void 0, );
2679
+ return _chunkGWMW6XY7cjs.registeredModels.call(void 0, );
2680
2680
  }
2681
2681
  async function existingModels(dir) {
2682
2682
  const out = /* @__PURE__ */ new Map();
@@ -2691,9 +2691,9 @@ async function existingModels(dir) {
2691
2691
  console.log(_picocolors2.default.yellow(` ! ${f} didn't load (${err.message.split("\n")[0]})`));
2692
2692
  continue;
2693
2693
  }
2694
- for (const m of _chunkIUZ6A7PBcjs.registeredModels.call(void 0, )) if (!fileOf.has(m.name)) fileOf.set(m.name, file);
2694
+ for (const m of _chunkGWMW6XY7cjs.registeredModels.call(void 0, )) if (!fileOf.has(m.name)) fileOf.set(m.name, file);
2695
2695
  }
2696
- for (const m of _chunkIUZ6A7PBcjs.registeredModels.call(void 0, )) {
2696
+ for (const m of _chunkGWMW6XY7cjs.registeredModels.call(void 0, )) {
2697
2697
  const storage = await _optionalChain([m, 'access', _40 => _40.studio, 'optionalAccess', _41 => _41.storage, 'call', _42 => _42(), 'access', _43 => _43.catch, 'call', _44 => _44(() => void 0)]);
2698
2698
  if (storage && !out.has(storage)) out.set(storage, { name: m.name, file: fileOf.get(m.name) });
2699
2699
  }
@@ -2722,17 +2722,17 @@ function engineOf(url) {
2722
2722
  async function main() {
2723
2723
  const [command, raw] = process.argv.slice(2);
2724
2724
  const opts = JSON.parse(_nullishCoalesce(raw, () => ( "{}")));
2725
- _chunkJP36TLL4cjs.configureLogger.call(void 0, { level: "warn" });
2725
+ _chunkQSIP7YLWcjs.configureLogger.call(void 0, { level: "warn" });
2726
2726
  const url = _nullishCoalesce(opts.databaseUrl, () => ( process.env["DATABASE_URL"]));
2727
2727
  if (!url)
2728
2728
  throw new Error("[EFC] DATABASE_URL is not set (add it to .env or pass --database-url)");
2729
2729
  const engine = engineOf(url);
2730
- _chunkIUZ6A7PBcjs.setDbEngine.call(void 0, engine);
2731
- let client = engine === "mongodb" ? await _chunkR2K7AFIBcjs.connectMongo.call(void 0, url) : await _chunkJP36TLL4cjs.connectPostgres.call(void 0, url);
2732
- _chunkR2K7AFIBcjs.setDbClient.call(void 0, client);
2730
+ _chunkGWMW6XY7cjs.setDbEngine.call(void 0, engine);
2731
+ let client = engine === "mongodb" ? await _chunkSOU3PBJCcjs.connectMongo.call(void 0, url) : await _chunkQSIP7YLWcjs.connectPostgres.call(void 0, url);
2732
+ _chunkSOU3PBJCcjs.setDbClient.call(void 0, client);
2733
2733
  const close = async () => {
2734
2734
  if (engine === "mongodb") await client.close();
2735
- else await _chunkJP36TLL4cjs.closePostgres.call(void 0, );
2735
+ else await _chunkQSIP7YLWcjs.closePostgres.call(void 0, );
2736
2736
  };
2737
2737
  const migrations = _path2.default.join(opts.root, "migrations");
2738
2738
  const step = (verb) => (name) => console.log(` ${_picocolors2.default.cyan(verb)} ${name}`);
@@ -2765,7 +2765,7 @@ async function main() {
2765
2765
  break;
2766
2766
  }
2767
2767
  case "sync": {
2768
- _chunkIUZ6A7PBcjs.setAutoSync.call(void 0, false);
2768
+ _chunkGWMW6XY7cjs.setAutoSync.call(void 0, false);
2769
2769
  const models = await importModels(opts.root);
2770
2770
  if (models.length === 0) {
2771
2771
  console.log(
@@ -2800,16 +2800,16 @@ async function main() {
2800
2800
  );
2801
2801
  }
2802
2802
  await close();
2803
- client = engine === "mongodb" ? await _chunkR2K7AFIBcjs.connectMongo.call(void 0, shadowUrl(url, engine, shadow)) : await _chunkJP36TLL4cjs.connectPostgres.call(void 0, shadowUrl(url, engine, shadow));
2804
- _chunkR2K7AFIBcjs.setDbClient.call(void 0, client);
2803
+ client = engine === "mongodb" ? await _chunkSOU3PBJCcjs.connectMongo.call(void 0, shadowUrl(url, engine, shadow)) : await _chunkQSIP7YLWcjs.connectPostgres.call(void 0, shadowUrl(url, engine, shadow));
2804
+ _chunkSOU3PBJCcjs.setDbClient.call(void 0, client);
2805
2805
  try {
2806
- _chunkIUZ6A7PBcjs.setAutoSync.call(void 0, false);
2806
+ _chunkGWMW6XY7cjs.setAutoSync.call(void 0, false);
2807
2807
  const migrator = new Migrator(migrations, engine, client);
2808
- _chunkIUZ6A7PBcjs.setSyncSuppressed.call(void 0, true);
2808
+ _chunkGWMW6XY7cjs.setSyncSuppressed.call(void 0, true);
2809
2809
  try {
2810
2810
  await migrator.migrate();
2811
2811
  } finally {
2812
- _chunkIUZ6A7PBcjs.setSyncSuppressed.call(void 0, false);
2812
+ _chunkGWMW6XY7cjs.setSyncSuppressed.call(void 0, false);
2813
2813
  }
2814
2814
  const models = await importModels(opts.root);
2815
2815
  if (models.length === 0) {
@@ -2892,13 +2892,13 @@ async function main() {
2892
2892
  break;
2893
2893
  }
2894
2894
  case "pull": {
2895
- _chunkIUZ6A7PBcjs.setAutoSync.call(void 0, false);
2895
+ _chunkGWMW6XY7cjs.setAutoSync.call(void 0, false);
2896
2896
  const dir = _path2.default.resolve(process.cwd(), _nullishCoalesce(opts.out, () => ( _path2.default.join("src", "model"))));
2897
2897
  const existing = await existingModels(dir);
2898
2898
  const names = new Map([...existing].map(([table, m]) => [table, m.name]));
2899
2899
  const { models, skipped: notPulled } = engine === "postgresql" ? await pullPostgres(client, names) : await pullMongo(
2900
2900
  client,
2901
- (await _chunkR2K7AFIBcjs.loadMongoose.call(void 0, )).pluralize(),
2901
+ (await _chunkSOU3PBJCcjs.loadMongoose.call(void 0, )).pluralize(),
2902
2902
  {
2903
2903
  ...opts.sample !== void 0 && { sample: opts.sample },
2904
2904
  names
@@ -2,7 +2,7 @@ import {
2
2
  connectMongo,
3
3
  loadMongoose,
4
4
  setDbClient
5
- } from "../chunk-BG4A7Z32.js";
5
+ } from "../chunk-JBOMTZT5.js";
6
6
  import {
7
7
  camel,
8
8
  lcFirst,
@@ -18,13 +18,13 @@ import {
18
18
  setSyncSuppressed,
19
19
  snakeCase,
20
20
  tableNameFor
21
- } from "../chunk-RETV3GKE.js";
21
+ } from "../chunk-336IU55W.js";
22
22
  import "../chunk-XPY5TQDK.js";
23
23
  import {
24
24
  closePostgres,
25
25
  configureLogger,
26
26
  connectPostgres
27
- } from "../chunk-V73R76I4.js";
27
+ } from "../chunk-2IDRC7RK.js";
28
28
 
29
29
  // src/cli/db-runner.ts
30
30
  import pc from "picocolors";
@@ -1,20 +1,20 @@
1
1
  #!/usr/bin/env node
2
2
  "use strict"; function _interopRequireWildcard(obj) { if (obj && obj.__esModule) { return obj; } else { var newObj = {}; if (obj != null) { for (var key in obj) { if (Object.prototype.hasOwnProperty.call(obj, key)) { newObj[key] = obj[key]; } } } newObj.default = obj; return newObj; } } function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; } function _nullishCoalesce(lhs, rhsFn) { if (lhs != null) { return lhs; } else { return rhsFn(); } } function _optionalChain(ops) { let lastAccessLHS = undefined; let value = ops[0]; let i = 1; while (i < ops.length) { const op = ops[i]; const fn = ops[i + 1]; i += 2; if ((op === 'optionalAccess' || op === 'optionalCall') && value == null) { return undefined; } if (op === 'access' || op === 'optionalAccess') { lastAccessLHS = value; value = fn(value); } else if (op === 'call' || op === 'optionalCall') { value = fn((...args) => value.call(lastAccessLHS, ...args)); lastAccessLHS = undefined; } } return value; }
3
3
 
4
- var _chunk4GHK27JAcjs = require('../chunk-4GHK27JA.cjs');
4
+ var _chunkWHBSVYUYcjs = require('../chunk-WHBSVYUY.cjs');
5
5
 
6
6
 
7
- var _chunkTBIVIR6Lcjs = require('../chunk-TBIVIR6L.cjs');
7
+ var _chunkDTMDJGRWcjs = require('../chunk-DTMDJGRW.cjs');
8
8
 
9
9
 
10
10
  var _chunkM53GODCXcjs = require('../chunk-M53GODCX.cjs');
11
11
 
12
12
 
13
- var _chunkIUZ6A7PBcjs = require('../chunk-IUZ6A7PB.cjs');
13
+ var _chunkGWMW6XY7cjs = require('../chunk-GWMW6XY7.cjs');
14
14
  require('../chunk-AGOYTFRO.cjs');
15
15
  require('../chunk-RPL2IFWK.cjs');
16
16
  require('../chunk-H2PVWCWC.cjs');
17
- require('../chunk-JP36TLL4.cjs');
17
+ require('../chunk-QSIP7YLW.cjs');
18
18
 
19
19
 
20
20
  var _chunkCGY7JU4Ycjs = require('../chunk-CGY7JU4Y.cjs');
@@ -505,7 +505,7 @@ async function bullmqAdmin(redisUrl, queueName = "efc") {
505
505
  } catch (e2) {
506
506
  throw new Error("[EFC] bullmq is not installed. Run: npm install bullmq");
507
507
  }
508
- const queue = new bullmq.Queue(queueName, { connection: _chunkTBIVIR6Lcjs.parseRedisUrl.call(void 0, redisUrl) });
508
+ const queue = new bullmq.Queue(queueName, { connection: _chunkDTMDJGRWcjs.parseRedisUrl.call(void 0, redisUrl) });
509
509
  const failedJobs = async (ids2) => {
510
510
  if (ids2.length === 0) return queue.getFailed(0, -1);
511
511
  const jobs = await Promise.all(ids2.map((id) => queue.getJob(id)));
@@ -556,7 +556,7 @@ async function connect(opts) {
556
556
  if (backend === "bullmq") return bullmqAdmin(_nullishCoalesce(redisUrl, () => ( "redis://localhost:6379")), opts.queue);
557
557
  if (backend === "pg-boss") {
558
558
  if (!databaseUrl) throw new Error("[EFC] pg-boss needs DATABASE_URL (or --database-url)");
559
- const { pgBossAdmin } = await Promise.resolve().then(() => _interopRequireWildcard(require("../pgboss-backend-UXQ3O2WT.cjs")));
559
+ const { pgBossAdmin } = await Promise.resolve().then(() => _interopRequireWildcard(require("../pgboss-backend-QVXISTLP.cjs")));
560
560
  return pgBossAdmin(databaseUrl, opts.queue);
561
561
  }
562
562
  throw new Error(`[EFC] Unknown task backend: ${backend}`);
@@ -650,7 +650,7 @@ function routesCommand() {
650
650
  console.error(_picocolors2.default.red("[EFC] Could not find apiDir (expected src/api)"));
651
651
  process.exit(1);
652
652
  }
653
- const routes = _chunk4GHK27JAcjs.scanDir.call(void 0, apiDir);
653
+ const routes = _chunkWHBSVYUYcjs.scanDir.call(void 0, apiDir);
654
654
  if (routes.length === 0) {
655
655
  console.log(_picocolors2.default.yellow("No routes found."));
656
656
  return;
@@ -2138,7 +2138,7 @@ function importPrisma(source) {
2138
2138
  const fields = [];
2139
2139
  const relations = {};
2140
2140
  const table = _nullishCoalesce(unquote(arg(blocks(m, "@@map")[0])), () => ( m.name));
2141
- if (table !== _chunkIUZ6A7PBcjs.tableNameFor.call(void 0, m.name)) options["collection"] = table;
2141
+ if (table !== _chunkGWMW6XY7cjs.tableNameFor.call(void 0, m.name)) options["collection"] = table;
2142
2142
  const kind = idKind.get(m.name);
2143
2143
  if (kind !== "uuid") options["id"] = kind;
2144
2144
  if (blocks(m, "@@id").length) {
package/dist/cli/index.js CHANGED
@@ -1,20 +1,20 @@
1
1
  #!/usr/bin/env node
2
2
  import {
3
3
  scanDir
4
- } from "../chunk-5LPRKZPB.js";
4
+ } from "../chunk-O2E7H2XA.js";
5
5
  import {
6
6
  parseRedisUrl
7
- } from "../chunk-C2FOZ7ME.js";
7
+ } from "../chunk-OM2XJJWX.js";
8
8
  import {
9
9
  writeModels
10
10
  } from "../chunk-DN4TCGYB.js";
11
11
  import {
12
12
  tableNameFor
13
- } from "../chunk-RETV3GKE.js";
13
+ } from "../chunk-336IU55W.js";
14
14
  import "../chunk-XPY5TQDK.js";
15
15
  import "../chunk-3SWI46YK.js";
16
16
  import "../chunk-B6MB6HEG.js";
17
- import "../chunk-V73R76I4.js";
17
+ import "../chunk-2IDRC7RK.js";
18
18
 
19
19
  // src/cli/index.ts
20
20
  import fs10 from "fs";
@@ -553,7 +553,7 @@ async function connect(opts) {
553
553
  if (backend === "bullmq") return bullmqAdmin(redisUrl ?? "redis://localhost:6379", opts.queue);
554
554
  if (backend === "pg-boss") {
555
555
  if (!databaseUrl) throw new Error("[EFC] pg-boss needs DATABASE_URL (or --database-url)");
556
- const { pgBossAdmin } = await import("../pgboss-backend-4X2YT4RB.js");
556
+ const { pgBossAdmin } = await import("../pgboss-backend-PQW6I3VF.js");
557
557
  return pgBossAdmin(databaseUrl, opts.queue);
558
558
  }
559
559
  throw new Error(`[EFC] Unknown task backend: ${backend}`);
@@ -365,3 +365,7 @@ ignite({ port: 3000 })
365
365
  On a worker, the signal closes the HTTP server (in-flight requests finish), drains running task jobs, then exits. On the cluster primary it relays `SIGTERM` to every worker — so `docker stop` / Kubernetes, which signal only PID 1, still shut down gracefully — and force-exits after `timeoutMs + 2s` if a worker hangs. Repeated signals are ignored rather than killing a worker mid-drain.
366
366
 
367
367
  `logging.queries.metrics: true | { maxEntries?: number }` enables bounded per-process query counters and latency summaries (default off; enabled default limit 1000). Read/reset through `getQueryMetrics` / `resetQueryMetrics` from the main package; see [query metrics](../guides/logging.md#query-metrics).
368
+
369
+ ## Since 0.11.0: OpenAPI and WebSockets
370
+
371
+ `openapi?: boolean | OpenAPIOptions` opts into `/openapi.json` (or `path`) with route-derived OpenAPI 3.1 JSON. `websocket?: false | WebSocketOptions` configures file `WS` upgrades; they attach automatically when exported, unless disabled. Both features share global middleware. See [OpenAPI](./openapi.md) and [WebSockets](./websockets.md) for exact options and lifecycle.
@@ -0,0 +1,36 @@
1
+ # OpenAPI API (since 0.11.0)
2
+
3
+ Exported from `express-file-cluster`:
4
+
5
+ ```ts
6
+ generateOpenAPI(
7
+ routes: MountedRoute[] | string, // explicit API directory or already loaded metadata
8
+ options?: OpenAPIOptions & { basePath?: string },
9
+ ): Promise<OpenAPIDocument>
10
+ ```
11
+
12
+ `OpenAPIDocument` contains `openapi: '3.1.0'`, `info`, `paths`, `components.schemas`, and optional `servers`. A directory argument scans/imports route files. A loaded-route argument uses existing metadata. Generation uses HTTP methods, metadata and request schemas. It does not change validation or execute handlers.
13
+
14
+ `ignite({ openapi: true | OpenAPIOptions })` and `createTestApp({ openapi: true | OpenAPIOptions })` generate once and serve the document. Default: disabled.
15
+
16
+ | Option | Default | Purpose |
17
+ |---|---|---|
18
+ | `path?: string` | `/openapi.json` | Absolute static document URL; reserved before API routes. |
19
+ | `info?: { title; version; description? }` | project package metadata in ignite; EFC API/1.0.0 in standalone/testing | Required OpenAPI info. |
20
+ | `servers?: { url; description? }[]` | omitted | Deployment URLs. |
21
+ | `components?: Record<string, unknown>` | generated schemas | Explicit components such as security schemes; generated component names avoid collisions. |
22
+ | `schemaToJSONSchema?: (validator: Validator) => JSONSchema \| Promise<JSONSchema>` | Standard JSON Schema input conversion | Adapter for validators without the standard JSON Schema protocol. |
23
+
24
+ `JSONSchema = boolean | Record<string, unknown>`. `RouteMethodMeta` adds `summary`, `tags`, `operationId`, and `openapi: Record<string, unknown> & { hidden?: boolean }`. The explicit operation fields override generated defaults; author-supplied OpenAPI objects must be valid. Only `hidden` is stripped. IDs are normalized for optional path expansions and duplicates are rejected.
25
+
26
+ See [the guide](../guides/openapi.md) for conversion, security and catch-all semantics.
27
+
28
+ The CommonJS generator delegates asynchronously to the ESM implementation, preserving native ESM route imports (including top-level await). It has the same Promise return type in both formats.
29
+
30
+ Document URL collisions are checked against actual GET/HEAD route matchers before hidden operations are filtered. Equivalent optional path variants are collapsed using the first parameter binding; ambiguous templates across routes throw.
31
+
32
+ Query/params object combinators are expanded into parameter fields. Unions retain branch-specific fields as optional and require only fields required by every branch; intersections combine requirements. `x-efc-query-schema` points to the full query schema for cross-field constraints. Object query fields use `deepObject` with `explode: true`. Non-object parameter shapes require explicit `meta.METHOD.openapi.parameters`; generation otherwise reports the route and location instead of omitting inputs.
33
+
34
+ Array query parameters expose the bracketed wire name (`tags[]`), `style: form`, and `explode: true`; the request property remains `tags`. External field references are retained without fetching, and explicit local type hints enable object/array style inference. Uninspectable root parameter objects still require explicit operation parameters.
35
+
36
+ `requestBody.required` is inferred from whether the converted schema accepts `{}`, the missing-body value supplied by Express. Local refs and logical constraints are evaluated without running validators; unresolved external/dynamic references conservatively remain required. Explicit `meta.METHOD.openapi.requestBody` overrides this inference. Example-only bodies are optional.
@@ -24,3 +24,5 @@ This helper's `apiDir` is **not** a new `ignite()` option. `createTestApp` is ex
24
24
  The CommonJS `/testing` entry delegates to the ESM helper using native `import()`, so dynamically imported ESM routes share its authentication and request context. The Node/runner must support the route files' module format.
25
25
 
26
26
  The ESM and CommonJS builds share process-wide auth configuration, request AsyncLocalStorage and cache state. CommonJS `requireAuth` global middleware therefore sees helper auth options, preserves `getCurrentUser()` across awaits into ESM routes, and observes the same revocations. Model/queue fixtures are still configured separately.
27
+
28
+ Since 0.11.0: `openapi?: boolean | OpenAPIOptions` enables the same document endpoint for tests. For WS tests, use `http.createServer(app)` and `attachWebSockets(server, app)`, then close the server in cleanup. The helper itself still never starts a listener.
@@ -0,0 +1,23 @@
1
+ # WebSocket API (since 0.11.0)
2
+
3
+ ```ts
4
+ import { attachWebSockets, closeWebSockets } from 'express-file-cluster';
5
+ import type { WebSocketHandler, WebSocketOptions } from 'express-file-cluster';
6
+ ```
7
+
8
+ `WebSocketHandler = (socket: ws.WebSocket, request: express.Request) => void | Promise<void>`. Export it as `WS` from a route file. An invalid non-function `WS` export fails boot. File middleware runs before connection; `schema.WS` validates the HTTP handshake.
9
+
10
+ `attachWebSockets(server: http.Server, app: express.Express, options?: WebSocketOptions): ws.WebSocketServer` attaches upgrade handling once. Used automatically by ignite when WS routes exist, or explicitly with an EFC test app/custom server. It also integrates socket draining with `server.close()`.
11
+
12
+ `closeWebSockets(server: http.Server, timeoutMs = 1000): Promise<void>` sends 1001 and waits for clients to disconnect, terminating remaining peers at the deadline. Pending handshake sockets are destroyed immediately, including connections waiting in middleware. It is idempotent, and stops heartbeats. Calling it prevents further upgrades on that attachment.
13
+
14
+ | Option | Default | Behavior |
15
+ |---|---|---|
16
+ | `maxPayload?: number` | 1048576 | Integer inbound message byte limit from 1 through 2147483647. Compression is disabled. |
17
+ | `origins?: string[]` | same-origin | Exact HTTP(S) browser origins. Missing Origin is allowed; malformed/opaque origins are refused. |
18
+ | `heartbeatIntervalMs?: number` | 30000 | Integer ping/pong interval from 0 through 2147483647 ms; 0 disables. |
19
+ | `handshakeTimeoutMs?: number` | 10000 | Integer deadline from 1 through 2147483647 ms for upgrade middleware. |
20
+
21
+ `ignite({ websocket: false })` disables automatic attachment. No new import subpath is added. See [the guide](../guides/websockets.md) for middleware, authentication, async context, error handling, cluster boundaries and test cleanup.
22
+
23
+ Upgrades pipelined behind an unfinished HTTP response close the connection without throwing an uncaught socket-assignment error.
@@ -140,7 +140,7 @@ Wrong answers are asked again. A question is only asked for a variable the app d
140
140
 
141
141
  ```json
142
142
  {
143
- "registry": "0.10.2",
143
+ "registry": "0.11.0",
144
144
  "language": "typescript",
145
145
  "database": "postgresql",
146
146
  "modelApi": "defineTable",
@@ -112,3 +112,5 @@ Pass a custom timeout (milliseconds) as the second argument:
112
112
  ```ts
113
113
  gracefulShutdown(server, 30_000); // 30-second drain window
114
114
  ```
115
+
116
+ WebSockets (since 0.11.0): each worker owns its accepted connections. Broadcasts are worker-local unless the application uses pub/sub. Graceful worker shutdown closes sockets with 1001, waits for acknowledgments, and terminates unresponsive peers within its drain budget.
@@ -235,3 +235,5 @@ export const GET = async (req, res) => {
235
235
  5. Registers an `app.all()` catch for unimplemented methods that returns 405.
236
236
 
237
237
  `asyncWrap` wraps every handler in `Promise.resolve(...).catch(next)` so that thrown errors and rejected promises are forwarded to the Express error handler automatically.
238
+
239
+ Since 0.11.0: route files can also export a `WS` connection handler, sharing the file's middleware and params with HTTP methods. See [WebSockets](../guides/websockets.md). Opt-in [OpenAPI](../guides/openapi.md) documents loaded HTTP method/meta/schema exports.
@@ -56,3 +56,12 @@ What each model API does on which engine — and the test that proves it. Every
56
56
  | Query logging + N+1 warnings | ✓ | ✓ | ✓ | ✓ | `db/query-log.integration.test.ts: warns once per request about an N+1 pattern` |
57
57
  | `efc db studio --write` (through the model) | ✓ | ✓ | ✓ | ✓ | `db/studio.integration.test.ts: inserts, edits and deletes through the model` · `db/studio.integration.test.ts: writes through defineCollection` |
58
58
  | Same table from `defineModel` and `defineTable` | — | ✓ | ✓ | — | `db/table.integration.test.ts: defineModel and defineTable over the same table` |
59
+
60
+ ## HTTP contracts and WebSockets (since 0.11.0)
61
+
62
+ | Feature | Status | Evidence |
63
+ |---|---|---|
64
+ | OpenAPI 3.1 endpoint/offline generation, adapters, query/body contracts and optional paths | Implemented; opt-in | `openapi.test.ts: generates versioned paths, metadata, examples, JSON-schema parameters and request bodies from Zod` |
65
+ | File WS exports, middleware/auth/context, origin and payload limits, heartbeat and drain | Implemented; worker-local | `websocket.test.ts: shares real middleware, auth, decoded params and async request context, while HTTP coexists` |
66
+
67
+ No automatic auth-policy inference, message-schema validation, cross-worker broadcast bus or Swagger UI is included.
@@ -0,0 +1,57 @@
1
+ # OpenAPI generation (since 0.11.0)
2
+
3
+ Enable an OpenAPI 3.1 JSON document for your real HTTP routes:
4
+
5
+ ```ts
6
+ ignite({
7
+ ...config,
8
+ openapi: {
9
+ path: '/openapi.json',
10
+ info: { title: 'My API', version: '1.0.0' },
11
+ },
12
+ });
13
+ ```
14
+
15
+ `openapi: true` uses `/openapi.json` and the project's package name/version. It is off by default. Global middleware applies to the document endpoint too. Its URL is reserved before API routing; a conflicting GET or HEAD route fails startup, including hidden routes, dynamic matches, case variants and trailing slashes. Import the JSON into an OpenAPI viewer or client generator.
16
+
17
+ The generator reads HTTP method exports, `meta`, and each method's request `schema`. Existing validation behavior stays the same. Validators that implement [Standard JSON Schema](https://standardschema.dev/json-schema) convert automatically using their input representation (including recent Zod 4 versions). A Standard Schema validator without JSON Schema support needs the `schemaToJSONSchema(validator)` adapter; enabling OpenAPI without one reports which route/location could not be converted. The adapter may be async. Runtime validation does not require JSON Schema support when OpenAPI is off.
18
+
19
+ ```ts
20
+ // src/api/users/[id].ts
21
+ import { z } from 'zod';
22
+
23
+ export const schema = {
24
+ GET: { params: z.object({ id: z.string().uuid() }) },
25
+ };
26
+ export const meta = {
27
+ GET: {
28
+ summary: 'Get a user',
29
+ tags: ['users'],
30
+ response: { status: 200, body: { id: 'example-id', name: 'Jane' } },
31
+ },
32
+ };
33
+ export const GET = async (req, res) => {
34
+ res.json({ id: req.params.id, name: 'Jane' });
35
+ };
36
+ ```
37
+
38
+ Body schemas become JSON request bodies; object properties in query/params schemas become parameters. Named object schemas behind local `$ref` are resolved for parameter fields. Object unions/intersections (`anyOf`, `oneOf`, `allOf`) retain their fields; a union field is required only when every branch requires it. The operation’s `x-efc-query-schema` references the complete query schema, preserving constraints between fields that individual OpenAPI parameters cannot express. Non-object parameter schemas fail generation with the route/location; supply explicit `meta.METHOD.openapi.parameters` to document a custom representation. Object query fields use `style: deepObject` and `explode: true`, matching Express bracket syntax such as `?filter[name]=Alice`. Nested `$defs` and local JSON Schema pointers are rebased into components; explicit `$id` resource scopes keep their local-reference semantics. Example request headers/query/body and response status/body come from `meta`. A request-validation 400 response is documented. Response schemas, alternative content types and authorization requirements can be supplied explicitly with `meta.METHOD.openapi` (an OpenAPI Operation Object). Auth middleware is not inspected to infer security policy.
39
+
40
+ ```ts
41
+ // In ignite options:
42
+ openapi: {
43
+ components: { securitySchemes: { bearerAuth: { type: 'http', scheme: 'bearer' } } },
44
+ }
45
+ // In a route:
46
+ export const meta = {
47
+ GET: { openapi: { security: [{ bearerAuth: [] }] } },
48
+ };
49
+ ```
50
+
51
+ `meta.GET.openapi.hidden: true` omits an operation. `summary`, `tags`, `description` and `operationId` are also supported directly in `meta.GET`. Explicit IDs must be unique; optional URL expansions get an index suffix. The document includes `basePath`. Optional URL segments expand into separate paths so every documented path parameter is required, as [OpenAPI requires](https://spec.openapis.org/oas/v3.1.0). Equivalent optional expansions use Express’s greedy binding (`[[first]]/[[second]]` with one segment binds `first`); other routes with equivalent templates but different parameter names fail generation rather than emitting an invalid document. Catch-all paths carry `x-efc-catch-all: true`: their slash-separated URL semantics need client-specific handling. WebSocket-only routes do not appear as HTTP operations.
52
+
53
+ For offline use, call `await generateOpenAPI('/absolute/path/to/src/api', { basePath, ...options })`, then write the returned object as JSON. This scans and imports route modules but does not listen, execute handlers or boot services; use the same TS loader/build output as the app, and keep service startup out of route module top-level code. Advanced callers can pass loaded `MountedRoute[]` directly instead. Plain `scanDir()` entries do not contain loaded HTTP exports/schemas. The `/testing` helper accepts the same `openapi` option for document tests.
54
+
55
+ Array query fields use bracketed wire names (`tags[]`) with `style: form` and `explode: true`, so one item and repeated items both reach Express as arrays. For example, `?tags[]=one&tags[]=two` becomes `req.query.tags`. An empty array has no entries to serialize; use an optional query field when omission is allowed. External field `$ref` values are preserved without network requests; provide a local `type` hint or explicit operation parameters if their object/array serialization cannot be inferred. Root parameter objects still need an inspectable local shape or explicit parameters.
56
+
57
+ Request-body requiredness follows whether the converted JSON Schema accepts the empty object Express supplies for a missing body. Required properties keep the body mandatory; optional object bodies allow omission. Local references and logical schema combinations are considered without executing application validators. Unknown external/dynamic body references remain required conservatively. Use `meta.METHOD.openapi.requestBody` to override inference, especially when middleware changes the body or validation uses custom rules. A body example alone does not make a body required.
@@ -93,3 +93,5 @@ So authentication in `middlewares` still responds 401/403 before any 400 — una
93
93
  ## Model-level validation is separate
94
94
 
95
95
  `schema` validates the HTTP request. `defineModel` validates what you write to the database (types, `required`, `enum`, `min`/`max`, `match`, custom `validate`) and throws a `ModelValidationError` — also a 400 with `issues`. Use both: request schemas for the API contract, model rules for data integrity. See [Database](./database.md).
96
+
97
+ Since 0.11.0: `schema.WS` validates WebSocket handshake params/query through the same pipeline, before upgrade; message validation belongs in the handler. Opt-in OpenAPI conversion uses a separate Standard JSON Schema input protocol or an explicit adapter; Standard Schema validation alone does not guarantee JSON Schema conversion. See [OpenAPI](./openapi.md).
@@ -0,0 +1,60 @@
1
+ # File-based WebSockets (since 0.11.0)
2
+
3
+ Export `WS` from a route file. `ignite()` serves its upgrade on the same HTTP server and `basePath` as HTTP routes.
4
+
5
+ ```ts
6
+ // src/api/chat/[room].ts
7
+ import type { WebSocketHandler } from 'express-file-cluster';
8
+ import { requireAuth, getCurrentUser } from 'express-file-cluster/auth';
9
+
10
+ export const middlewares = [requireAuth];
11
+ export const WS: WebSocketHandler = (socket, req) => {
12
+ socket.on('message', (data, isBinary) => {
13
+ const user = getCurrentUser();
14
+ socket.send(JSON.stringify({ room: req.params.room, userId: user?.id, text: data.toString(), isBinary }));
15
+ });
16
+ };
17
+ ```
18
+
19
+ Connect to `ws://localhost:3000/v1/api/chat/general` (use `wss://` behind TLS). `WS` receives a [ws WebSocket](https://github.com/websockets/ws/blob/master/doc/ws.md) and the Express request. An HTTP `GET`/`POST` export can coexist in the same file. HTTP clients do not invoke `WS`, and upgrading an HTTP-only or unknown route returns 404.
20
+
21
+ Middleware response headers (including cookies and request IDs) are included in successful upgrades; protocol framing/negotiation headers remain owned by the WebSocket server. Global and file middleware, cookie parsing, request context and named/optional/catch-all params apply before upgrade. `requireAuth` checks cookies/bearer tokens and revocation during the handshake; auth failure is an HTTP 401/403/503 rather than a WebSocket connection. Use method-keyed `schema.WS` for query/params handshake validation. It does not validate message frames. `getCurrentUser()` and the request logger remain available in message/close/error callbacks and across awaits. Handle errors inside application event listeners; EFC catches errors thrown/rejected by the exported connection handler and closes with 1011.
22
+
23
+ Browser clients use cookies; the browser WebSocket API cannot set arbitrary Authorization headers. Authorization and session changes during an already established connection are application policy: recheck sensitive message operations or close affected sockets when sessions end. Handshake authentication is not repeated for every frame.
24
+
25
+ ```ts
26
+ ignite({
27
+ ...config,
28
+ websocket: {
29
+ origins: ['https://app.example.com'],
30
+ maxPayload: 1024 * 1024,
31
+ heartbeatIntervalMs: 30_000,
32
+ handshakeTimeoutMs: 10_000,
33
+ },
34
+ });
35
+ ```
36
+
37
+ Upgrades are enabled when a `WS` export exists. `websocket: false` disables them. Browser origins default to same-origin using Express's protocol/host; configure `trustProxy` correctly behind a proxy. An explicit origin list replaces this default. Opaque/malformed/cross-origin handshakes are rejected with 403. Clients without an Origin header (such as trusted Node clients) are allowed and still pass auth middleware.
38
+
39
+ `maxPayload` accepts integers from 1 through 2147483647 bytes; larger values fail configuration instead of overflowing the receiver’s limit. Both timer options also have a 2147483647 ms ceiling. Inbound messages default to a 1 MiB limit, compression is disabled, and heartbeat pings terminate unresponsive peers. Set `heartbeatIntervalMs: 0` to disable heartbeat. Pending middleware has a 10-second upgrade deadline; the HTTP `requestTimeout` may reject it earlier. Once upgraded, HTTP request timers are cleared.
40
+
41
+ Pipelined upgrades received while an earlier HTTP response still owns the connection close that connection safely.
42
+
43
+ `server.close()` immediately destroys pending handshake sockets, closes established sockets with code 1001 and terminates unresponsive peers after a drain interval. `gracefulShutdown(server)` drains WebSockets with HTTP/task shutdown, including signals forwarded to workers. Every cluster worker owns its connections; broadcasts through a server's `clients` set stay within that worker. Use application pub/sub for cross-worker/instance messages.
44
+
45
+ ## Testing and custom HTTP servers
46
+
47
+ ```ts
48
+ import http from 'node:http';
49
+ import { attachWebSockets } from 'express-file-cluster';
50
+ import { createTestApp } from 'express-file-cluster/testing';
51
+
52
+ const app = await createTestApp({ apiDir: '/absolute/path/to/api' });
53
+ const server = http.createServer(app);
54
+ const sockets = attachWebSockets(server, app);
55
+ server.listen(0);
56
+ // Connect a ws client; sockets.clients contains this server's connections.
57
+ // Close server in cleanup; upgraded sockets are drained too.
58
+ ```
59
+
60
+ The test helper itself still does not start a listener. `attachWebSockets` rejects duplicate attachment. Each server has its own limits, connections and heartbeat; app auth/cache state follows the process-wide isolation rules in the testing guide.