@maverickcer/env-cap 0.7.4 → 0.7.6
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.
- package/ADOPTION.md +106 -124
- package/AGENTS.md +94 -128
- package/CHANGELOG.md +42 -0
- package/CODE_REVIEW.md +69 -173
- package/CONTRIBUTING.md +57 -74
- package/GUIDE.md +405 -866
- package/README.md +112 -89
- package/RELEASING.md +81 -65
- package/SECURITY.md +76 -227
- package/SUPPORT.md +21 -45
- package/VERSIONING.md +69 -105
- package/benchmarks/READING-BENCHMARKS.md +103 -81
- package/benchmarks/README.md +12 -9
- package/benchmarks/WRITING-BENCHMARKS.md +90 -80
- package/benchmarks/performance-buildtime/BENCHMARKS.md +20 -20
- package/benchmarks/performance-runtime/BENCHMARKS.md +107 -107
- package/dist/.dts/_ipc/build-fs.d.ts +12 -17
- package/dist/.dts/_ipc/build-fs.d.ts.map +1 -1
- package/dist/.dts/_ipc/compiler-api.d.ts +6 -6
- package/dist/.dts/_ipc/display-path.d.ts +1 -1
- package/dist/.dts/_ipc/display-path.d.ts.map +1 -1
- package/dist/.dts/_ipc/generated-banner.d.ts +8 -8
- package/dist/.dts/_ipc/glob.d.ts +9 -8
- package/dist/.dts/_ipc/glob.d.ts.map +1 -1
- package/dist/.dts/_ipc/no-node-fs.d.ts +2 -2
- package/dist/.dts/_ipc/no-node-fs.d.ts.map +1 -1
- package/dist/.dts/_ipc/resolve-tsconfig-paths.d.ts +16 -16
- package/dist/.dts/_ipc/resolve-tsconfig-paths.d.ts.map +1 -1
- package/dist/.dts/_ipc/typescript.d.ts +4 -4
- package/dist/.dts/build/assemble-project.d.ts +14 -15
- package/dist/.dts/build/assemble-project.d.ts.map +1 -1
- package/dist/.dts/build/change-model.d.ts +14 -14
- package/dist/.dts/build/change-model.d.ts.map +1 -1
- package/dist/.dts/build/check-artifacts.d.ts +4 -4
- package/dist/.dts/build/check-artifacts.d.ts.map +1 -1
- package/dist/.dts/build/citation-verification.d.ts +13 -14
- package/dist/.dts/build/citation-verification.d.ts.map +1 -1
- package/dist/.dts/build/compatibility.d.ts +24 -24
- package/dist/.dts/build/compatibility.d.ts.map +1 -1
- package/dist/.dts/build/contract-model.d.ts +10 -10
- package/dist/.dts/build/contract-model.d.ts.map +1 -1
- package/dist/.dts/build/deep-equal.d.ts +2 -2
- package/dist/.dts/build/deep-freeze.d.ts +2 -2
- package/dist/.dts/build/dependency-graph.d.ts +48 -55
- package/dist/.dts/build/dependency-graph.d.ts.map +1 -1
- package/dist/.dts/build/dependency-model.d.ts +18 -18
- package/dist/.dts/build/dependency-model.d.ts.map +1 -1
- package/dist/.dts/build/discover.d.ts +11 -11
- package/dist/.dts/build/discover.d.ts.map +1 -1
- package/dist/.dts/build/docs.d.ts +34 -38
- package/dist/.dts/build/docs.d.ts.map +1 -1
- package/dist/.dts/build/env-example.d.ts +13 -13
- package/dist/.dts/build/env-example.d.ts.map +1 -1
- package/dist/.dts/build/errors.d.ts +8 -8
- package/dist/.dts/build/evidence-cache.d.ts +23 -23
- package/dist/.dts/build/evidence-cache.d.ts.map +1 -1
- package/dist/.dts/build/evidence-model.d.ts +3 -3
- package/dist/.dts/build/evidence-reference.d.ts +15 -15
- package/dist/.dts/build/evidence-reference.d.ts.map +1 -1
- package/dist/.dts/build/evidence-snapshot.d.ts +47 -53
- package/dist/.dts/build/evidence-snapshot.d.ts.map +1 -1
- package/dist/.dts/build/exclusive-group.d.ts +4 -4
- package/dist/.dts/build/exclusive-group.d.ts.map +1 -1
- package/dist/.dts/build/finding-model.d.ts +12 -12
- package/dist/.dts/build/finding-model.d.ts.map +1 -1
- package/dist/.dts/build/generate-documentation.d.ts +19 -19
- package/dist/.dts/build/generate-documentation.d.ts.map +1 -1
- package/dist/.dts/build/generate-env-artifacts.d.ts +43 -43
- package/dist/.dts/build/generate-env-artifacts.d.ts.map +1 -1
- package/dist/.dts/build/generate-evidence.d.ts +19 -19
- package/dist/.dts/build/generate-evidence.d.ts.map +1 -1
- package/dist/.dts/build/generate-manifest.d.ts +11 -12
- package/dist/.dts/build/generate-manifest.d.ts.map +1 -1
- package/dist/.dts/build/generate-usage.d.ts +23 -24
- package/dist/.dts/build/generate-usage.d.ts.map +1 -1
- package/dist/.dts/build/generated-banner.d.ts +5 -5
- package/dist/.dts/build/governance-fields.d.ts +7 -7
- package/dist/.dts/build/humanize-key.d.ts +1 -1
- package/dist/.dts/build/humanize-key.d.ts.map +1 -1
- package/dist/.dts/build/index.d.ts +20 -36
- package/dist/.dts/build/index.d.ts.map +1 -1
- package/dist/.dts/build/lifecycle-model.d.ts +90 -83
- package/dist/.dts/build/lifecycle-model.d.ts.map +1 -1
- package/dist/.dts/build/link.d.ts +38 -39
- package/dist/.dts/build/link.d.ts.map +1 -1
- package/dist/.dts/build/literal-eval.d.ts +2 -2
- package/dist/.dts/build/literal-eval.d.ts.map +1 -1
- package/dist/.dts/build/live-expirations.d.ts +14 -13
- package/dist/.dts/build/live-expirations.d.ts.map +1 -1
- package/dist/.dts/build/manifest.d.ts +6 -6
- package/dist/.dts/build/map-utils.d.ts +4 -4
- package/dist/.dts/build/merge-documentation.d.ts +9 -8
- package/dist/.dts/build/merge-documentation.d.ts.map +1 -1
- package/dist/.dts/build/ownership-model.d.ts +14 -15
- package/dist/.dts/build/ownership-model.d.ts.map +1 -1
- package/dist/.dts/build/parse.d.ts +20 -21
- package/dist/.dts/build/parse.d.ts.map +1 -1
- package/dist/.dts/build/reference-projections.d.ts +36 -38
- package/dist/.dts/build/reference-projections.d.ts.map +1 -1
- package/dist/.dts/build/resolution/resolve-import.d.ts +18 -14
- package/dist/.dts/build/resolution/resolve-import.d.ts.map +1 -1
- package/dist/.dts/build/resolution/resolve-package-schema.d.ts +26 -26
- package/dist/.dts/build/resolution/resolve-package-schema.d.ts.map +1 -1
- package/dist/.dts/build/resolution/resolve-within-root.d.ts +9 -9
- package/dist/.dts/build/sarif.d.ts +5 -5
- package/dist/.dts/build/sarif.d.ts.map +1 -1
- package/dist/.dts/build/scan-dependencies.d.ts +17 -16
- package/dist/.dts/build/scan-dependencies.d.ts.map +1 -1
- package/dist/.dts/build/sort-by-identity.d.ts +1 -1
- package/dist/.dts/build/source-position.d.ts +13 -13
- package/dist/.dts/build/tool-version.d.ts +1 -1
- package/dist/.dts/build/usage-report.d.ts +19 -19
- package/dist/.dts/build/usage-report.d.ts.map +1 -1
- package/dist/.dts/eslint-plugin/index.d.ts +16 -5
- package/dist/.dts/eslint-plugin/index.d.ts.map +1 -1
- package/dist/.dts/eslint-plugin/no-raw-process-env.d.ts +4 -4
- package/dist/.dts/evidence/define-projection.d.ts +15 -16
- package/dist/.dts/evidence/define-projection.d.ts.map +1 -1
- package/dist/.dts/evidence/index.d.ts +11 -15
- package/dist/.dts/evidence/index.d.ts.map +1 -1
- package/dist/.dts/helpers/index.d.ts +15 -18
- package/dist/.dts/helpers/index.d.ts.map +1 -1
- package/dist/.dts/helpers/validators.d.ts +2 -2
- package/dist/.dts/helpers/validators.d.ts.map +1 -1
- package/dist/.dts/node/index.d.ts +19 -0
- package/dist/.dts/node/index.d.ts.map +1 -1
- package/dist/.dts/runtime/create.d.ts +6 -3
- package/dist/.dts/runtime/create.d.ts.map +1 -1
- package/dist/.dts/runtime/document.d.ts +91 -97
- package/dist/.dts/runtime/document.d.ts.map +1 -1
- package/dist/.dts/runtime/errors.d.ts +5 -5
- package/dist/.dts/runtime/index.d.ts +11 -10
- package/dist/.dts/runtime/index.d.ts.map +1 -1
- package/dist/.dts/runtime/reset.d.ts +1 -1
- package/dist/.dts/runtime/types.d.ts +39 -24
- package/dist/.dts/runtime/types.d.ts.map +1 -1
- package/dist/.dts/runtime/validate.d.ts +15 -2
- package/dist/.dts/runtime/validate.d.ts.map +1 -1
- package/dist/.dts7/_ipc/build-fs.d.ts +48 -0
- package/dist/.dts7/_ipc/build-fs.d.ts.map +1 -0
- package/dist/.dts7/_ipc/compiler-api.d.ts +17 -0
- package/dist/.dts7/_ipc/compiler-api.d.ts.map +1 -0
- package/dist/.dts7/_ipc/display-path.d.ts +27 -0
- package/dist/.dts7/_ipc/display-path.d.ts.map +1 -0
- package/dist/.dts7/_ipc/generated-banner.d.ts +58 -0
- package/dist/.dts7/_ipc/generated-banner.d.ts.map +1 -0
- package/dist/.dts7/_ipc/glob.d.ts +23 -0
- package/dist/.dts7/_ipc/glob.d.ts.map +1 -0
- package/dist/.dts7/_ipc/no-node-fs.d.ts +21 -0
- package/dist/.dts7/_ipc/no-node-fs.d.ts.map +1 -0
- package/dist/.dts7/_ipc/resolve-tsconfig-paths.d.ts +134 -0
- package/dist/.dts7/_ipc/resolve-tsconfig-paths.d.ts.map +1 -0
- package/dist/.dts7/_ipc/typescript.d.ts +20 -0
- package/dist/.dts7/_ipc/typescript.d.ts.map +1 -0
- package/dist/.dts7/build/assemble-project.d.ts +46 -0
- package/dist/.dts7/build/assemble-project.d.ts.map +1 -0
- package/dist/.dts7/build/change-model.d.ts +63 -0
- package/dist/.dts7/build/change-model.d.ts.map +1 -0
- package/dist/.dts7/build/check-artifacts.d.ts +48 -0
- package/dist/.dts7/build/check-artifacts.d.ts.map +1 -0
- package/dist/.dts7/build/citation-verification.d.ts +61 -0
- package/dist/.dts7/build/citation-verification.d.ts.map +1 -0
- package/dist/.dts7/build/compatibility.d.ts +83 -0
- package/dist/.dts7/build/compatibility.d.ts.map +1 -0
- package/dist/.dts7/build/compiler-api.d.ts +12 -0
- package/dist/.dts7/build/compiler-api.d.ts.map +1 -0
- package/dist/.dts7/build/contract-model.d.ts +93 -0
- package/dist/.dts7/build/contract-model.d.ts.map +1 -0
- package/dist/.dts7/build/deep-equal.d.ts +9 -0
- package/dist/.dts7/build/deep-equal.d.ts.map +1 -0
- package/dist/.dts7/build/deep-freeze.d.ts +20 -0
- package/dist/.dts7/build/deep-freeze.d.ts.map +1 -0
- package/dist/.dts7/build/dependency-graph.d.ts +163 -0
- package/dist/.dts7/build/dependency-graph.d.ts.map +1 -0
- package/dist/.dts7/build/dependency-model.d.ts +81 -0
- package/dist/.dts7/build/dependency-model.d.ts.map +1 -0
- package/dist/.dts7/build/discover.d.ts +41 -0
- package/dist/.dts7/build/discover.d.ts.map +1 -0
- package/dist/.dts7/build/display-path.d.ts +6 -0
- package/dist/.dts7/build/display-path.d.ts.map +1 -0
- package/dist/.dts7/build/docs.d.ts +172 -0
- package/dist/.dts7/build/docs.d.ts.map +1 -0
- package/dist/.dts7/build/env-example.d.ts +85 -0
- package/dist/.dts7/build/env-example.d.ts.map +1 -0
- package/dist/.dts7/build/errors.d.ts +78 -0
- package/dist/.dts7/build/errors.d.ts.map +1 -0
- package/dist/.dts7/build/evidence-cache.d.ts +74 -0
- package/dist/.dts7/build/evidence-cache.d.ts.map +1 -0
- package/dist/.dts7/build/evidence-model.d.ts +50 -0
- package/dist/.dts7/build/evidence-model.d.ts.map +1 -0
- package/dist/.dts7/build/evidence-reference.d.ts +67 -0
- package/dist/.dts7/build/evidence-reference.d.ts.map +1 -0
- package/dist/.dts7/build/evidence-snapshot.d.ts +142 -0
- package/dist/.dts7/build/evidence-snapshot.d.ts.map +1 -0
- package/dist/.dts7/build/exclusive-group.d.ts +19 -0
- package/dist/.dts7/build/exclusive-group.d.ts.map +1 -0
- package/dist/.dts7/build/finding-model.d.ts +80 -0
- package/dist/.dts7/build/finding-model.d.ts.map +1 -0
- package/dist/.dts7/build/generate-documentation.d.ts +176 -0
- package/dist/.dts7/build/generate-documentation.d.ts.map +1 -0
- package/dist/.dts7/build/generate-env-artifacts.d.ts +191 -0
- package/dist/.dts7/build/generate-env-artifacts.d.ts.map +1 -0
- package/dist/.dts7/build/generate-evidence.d.ts +77 -0
- package/dist/.dts7/build/generate-evidence.d.ts.map +1 -0
- package/dist/.dts7/build/generate-manifest.d.ts +100 -0
- package/dist/.dts7/build/generate-manifest.d.ts.map +1 -0
- package/dist/.dts7/build/generate-usage.d.ts +94 -0
- package/dist/.dts7/build/generate-usage.d.ts.map +1 -0
- package/dist/.dts7/build/generated-banner.d.ts +43 -0
- package/dist/.dts7/build/generated-banner.d.ts.map +1 -0
- package/dist/.dts7/build/glob.d.ts +6 -0
- package/dist/.dts7/build/glob.d.ts.map +1 -0
- package/dist/.dts7/build/governance-fields.d.ts +34 -0
- package/dist/.dts7/build/governance-fields.d.ts.map +1 -0
- package/dist/.dts7/build/humanize-key.d.ts +14 -0
- package/dist/.dts7/build/humanize-key.d.ts.map +1 -0
- package/dist/.dts7/build/index.d.ts +89 -0
- package/dist/.dts7/build/index.d.ts.map +1 -0
- package/dist/.dts7/build/lifecycle-model.d.ts +181 -0
- package/dist/.dts7/build/lifecycle-model.d.ts.map +1 -0
- package/dist/.dts7/build/link.d.ts +222 -0
- package/dist/.dts7/build/link.d.ts.map +1 -0
- package/dist/.dts7/build/literal-eval.d.ts +24 -0
- package/dist/.dts7/build/literal-eval.d.ts.map +1 -0
- package/dist/.dts7/build/live-expirations.d.ts +48 -0
- package/dist/.dts7/build/live-expirations.d.ts.map +1 -0
- package/dist/.dts7/build/manifest.d.ts +31 -0
- package/dist/.dts7/build/manifest.d.ts.map +1 -0
- package/dist/.dts7/build/map-utils.d.ts +8 -0
- package/dist/.dts7/build/map-utils.d.ts.map +1 -0
- package/dist/.dts7/build/merge-documentation.d.ts +36 -0
- package/dist/.dts7/build/merge-documentation.d.ts.map +1 -0
- package/dist/.dts7/build/ownership-model.d.ts +58 -0
- package/dist/.dts7/build/ownership-model.d.ts.map +1 -0
- package/dist/.dts7/build/parse.d.ts +206 -0
- package/dist/.dts7/build/parse.d.ts.map +1 -0
- package/dist/.dts7/build/reference-projections.d.ts +168 -0
- package/dist/.dts7/build/reference-projections.d.ts.map +1 -0
- package/dist/.dts7/build/resolution/resolve-import.d.ts +62 -0
- package/dist/.dts7/build/resolution/resolve-import.d.ts.map +1 -0
- package/dist/.dts7/build/resolution/resolve-package-schema.d.ts +83 -0
- package/dist/.dts7/build/resolution/resolve-package-schema.d.ts.map +1 -0
- package/dist/.dts7/build/resolution/resolve-tsconfig-paths.d.ts +18 -0
- package/dist/.dts7/build/resolution/resolve-tsconfig-paths.d.ts.map +1 -0
- package/dist/.dts7/build/resolution/resolve-within-root.d.ts +35 -0
- package/dist/.dts7/build/resolution/resolve-within-root.d.ts.map +1 -0
- package/dist/.dts7/build/sarif.d.ts +66 -0
- package/dist/.dts7/build/sarif.d.ts.map +1 -0
- package/dist/.dts7/build/scan-dependencies.d.ts +71 -0
- package/dist/.dts7/build/scan-dependencies.d.ts.map +1 -0
- package/dist/.dts7/build/sort-by-identity.d.ts +14 -0
- package/dist/.dts7/build/sort-by-identity.d.ts.map +1 -0
- package/dist/.dts7/build/source-position.d.ts +69 -0
- package/dist/.dts7/build/source-position.d.ts.map +1 -0
- package/dist/.dts7/build/tool-version.d.ts +8 -0
- package/dist/.dts7/build/tool-version.d.ts.map +1 -0
- package/dist/.dts7/build/types.d.ts +7 -0
- package/dist/.dts7/build/types.d.ts.map +1 -0
- package/dist/.dts7/build/typescript.d.ts +6 -0
- package/dist/.dts7/build/typescript.d.ts.map +1 -0
- package/dist/.dts7/build/usage-report.d.ts +124 -0
- package/dist/.dts7/build/usage-report.d.ts.map +1 -0
- package/dist/.dts7/cli/filesystem.d.ts +7 -0
- package/dist/.dts7/cli/filesystem.d.ts.map +1 -0
- package/dist/.dts7/eslint-plugin/glob.d.ts +7 -0
- package/dist/.dts7/eslint-plugin/glob.d.ts.map +1 -0
- package/dist/.dts7/eslint-plugin/index.d.ts +38 -0
- package/dist/.dts7/eslint-plugin/index.d.ts.map +1 -0
- package/dist/.dts7/eslint-plugin/no-node-fs.d.ts +15 -0
- package/dist/.dts7/eslint-plugin/no-node-fs.d.ts.map +1 -0
- package/dist/.dts7/eslint-plugin/no-raw-process-env.d.ts +23 -0
- package/dist/.dts7/eslint-plugin/no-raw-process-env.d.ts.map +1 -0
- package/dist/.dts7/evidence/define-projection.d.ts +51 -0
- package/dist/.dts7/evidence/define-projection.d.ts.map +1 -0
- package/dist/.dts7/evidence/index.d.ts +19 -0
- package/dist/.dts7/evidence/index.d.ts.map +1 -0
- package/dist/.dts7/helpers/index.d.ts +132 -0
- package/dist/.dts7/helpers/index.d.ts.map +1 -0
- package/dist/.dts7/helpers/processors.d.ts +32 -0
- package/dist/.dts7/helpers/processors.d.ts.map +1 -0
- package/dist/.dts7/helpers/validators.d.ts +68 -0
- package/dist/.dts7/helpers/validators.d.ts.map +1 -0
- package/dist/.dts7/node/index.d.ts +21 -0
- package/dist/.dts7/node/index.d.ts.map +1 -0
- package/dist/.dts7/runtime/cache.d.ts +17 -0
- package/dist/.dts7/runtime/cache.d.ts.map +1 -0
- package/dist/.dts7/runtime/create.d.ts +23 -0
- package/dist/.dts7/runtime/create.d.ts.map +1 -0
- package/dist/.dts7/runtime/document.d.ts +214 -0
- package/dist/.dts7/runtime/document.d.ts.map +1 -0
- package/dist/.dts7/runtime/errors.d.ts +55 -0
- package/dist/.dts7/runtime/errors.d.ts.map +1 -0
- package/dist/.dts7/runtime/index.d.ts +25 -0
- package/dist/.dts7/runtime/index.d.ts.map +1 -0
- package/dist/.dts7/runtime/registry.d.ts +12 -0
- package/dist/.dts7/runtime/registry.d.ts.map +1 -0
- package/dist/.dts7/runtime/reset.d.ts +8 -0
- package/dist/.dts7/runtime/reset.d.ts.map +1 -0
- package/dist/.dts7/runtime/types.d.ts +190 -0
- package/dist/.dts7/runtime/types.d.ts.map +1 -0
- package/dist/.dts7/runtime/validate.d.ts +27 -0
- package/dist/.dts7/runtime/validate.d.ts.map +1 -0
- package/dist/{build-6XFHJFQK.js → build-UEENZEUX.js} +43 -42
- package/dist/build-UEENZEUX.js.map +1 -0
- package/dist/build.cjs +42 -41
- package/dist/build.cjs.map +1 -1
- package/dist/build.js +42 -41
- package/dist/build.js.map +1 -1
- package/dist/build.ts7.d.cts +1 -0
- package/dist/build.ts7.d.ts +1 -0
- package/dist/{chunk-RL5KFVUT.js → chunk-TBL3O7IG.js} +2 -2
- package/dist/cli/index.js +29 -28
- package/dist/cli/index.js.map +1 -1
- package/dist/eslint-plugin/index.cjs.map +1 -1
- package/dist/eslint-plugin/index.js.map +1 -1
- package/dist/eslint-plugin/index.ts7.d.cts +1 -0
- package/dist/eslint-plugin/index.ts7.d.ts +1 -0
- package/dist/evidence.cjs +1 -1
- package/dist/evidence.cjs.map +1 -1
- package/dist/evidence.js +1 -1
- package/dist/evidence.js.map +1 -1
- package/dist/evidence.ts7.d.cts +1 -0
- package/dist/evidence.ts7.d.ts +1 -0
- package/dist/helpers.cjs +4 -4
- package/dist/helpers.cjs.map +1 -1
- package/dist/helpers.js +4 -4
- package/dist/helpers.js.map +1 -1
- package/dist/helpers.ts7.d.cts +1 -0
- package/dist/helpers.ts7.d.ts +1 -0
- package/dist/index.cjs.map +1 -1
- package/dist/index.js.map +1 -1
- package/dist/index.ts7.d.cts +1 -0
- package/dist/index.ts7.d.ts +1 -0
- package/dist/node.ts7.d.cts +1 -0
- package/dist/node.ts7.d.ts +1 -0
- package/examples/README.md +46 -80
- package/package.json +43 -12
- package/schemas/contract-model.schema.json +7 -7
- package/schemas/env-cap-report.schema.json +88 -88
- package/skills/env-cap/SKILL.md +12 -13
- package/skills/env-cap/references/api.md +1 -1
- package/specs/architecture.md +147 -122
- package/specs/decisions/0001-runtime-documentation-separation.md +1 -1
- package/specs/decisions/0014-cross-package-schema-discovery.md +4 -1
- package/specs/decisions/0023-tsconfig-path-alias-resolution.md +4 -1
- package/specs/decisions/0049-typescript-7-scanner-uses-a-bundled-typescript-6.md +13 -8
- package/specs/generated-artifacts.md +91 -71
- package/specs/migrations/README.md +6 -6
- package/specs/migrations/from-centralized-schema.md +1 -1
- package/specs/migrations/from-t3-env.md +9 -9
- package/PROMPT.md +0 -89
- package/dist/build-6XFHJFQK.js.map +0 -1
- /package/dist/{chunk-RL5KFVUT.js.map → chunk-TBL3O7IG.js.map} +0 -0
|
@@ -0,0 +1,132 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Optional processors and validators for common cases (`@maverickcer/env-cap/helpers`), such as
|
|
3
|
+
* `processors.toNumber()` and `validators.range(1, 65535)`.
|
|
4
|
+
*
|
|
5
|
+
* A contract works the same without them: `createEnv` and `validateEnv` never import this module. Any
|
|
6
|
+
* function with the `Processor<T>` or `Validator<T>` shape plugs in the same way.
|
|
7
|
+
*
|
|
8
|
+
* The two objects are plain literals of named imports, not `export * as processors`. A bundler lowers
|
|
9
|
+
* `export * as` into a namespace helper call it cannot prove free of side effects. That call blocks
|
|
10
|
+
* tree-shaking in a consumer's own bundler, so importing `processors` alone would still ship
|
|
11
|
+
* `validators`. With plain literals, importing `processors` alone drops `validators` entirely.
|
|
12
|
+
*
|
|
13
|
+
* @packageDocumentation
|
|
14
|
+
*/
|
|
15
|
+
import { base64, parseJSON, split, toArray, toBigInt, toBoolean, toDate, toInteger, toLowerCase, toNumber, toRegExp, toString, toURL, toUpperCase, trim } from "./processors.js";
|
|
16
|
+
import { after, all, any, before, custom, email, endsWith, finite, future, includes, integer as integerValidator, length, matches, max, maxItems, maxLength, min, minItems, minLength, negative, not, oneOf, optional, past, positive, range, refine, required, safeInteger, unique, url as urlValidator, uuid, uuidVersion } from "./validators.js";
|
|
17
|
+
/**
|
|
18
|
+
* Convenience {@link runtime.Processor} implementations for common coercion
|
|
19
|
+
* patterns (e.g. `processors.toNumber()`).
|
|
20
|
+
*
|
|
21
|
+
* @remarks
|
|
22
|
+
* Naming matches `data-cap`'s `helpers.processors`: but these
|
|
23
|
+
* throw with a formatted `Error` message on invalid input, where data-cap's
|
|
24
|
+
* silently return `undefined`. Do not assume the same failure mode when
|
|
25
|
+
* moving between packages.
|
|
26
|
+
*/
|
|
27
|
+
export declare const processors: {
|
|
28
|
+
/** Decodes a base64 string into a `Buffer`. */
|
|
29
|
+
base64: typeof base64;
|
|
30
|
+
/** Parses a JSON string; passes non-string values through unchanged. */
|
|
31
|
+
parseJSON: typeof parseJSON;
|
|
32
|
+
/** Splits a string on `separator` into a trimmed string array; returns `[]` for non-string input. */
|
|
33
|
+
split: typeof split;
|
|
34
|
+
/** Splits a delimited string (or passes through an array) into items, running each through `processors` in order. */
|
|
35
|
+
toArray: typeof toArray;
|
|
36
|
+
/** Coerces a value to a `bigint`. */
|
|
37
|
+
toBigInt: typeof toBigInt;
|
|
38
|
+
/** Coerces common boolean-like strings (`true`/`1`/`yes`/`on`, and their opposites) into a real boolean. */
|
|
39
|
+
toBoolean: typeof toBoolean;
|
|
40
|
+
/** Parses a value into a `Date`. */
|
|
41
|
+
toDate: typeof toDate;
|
|
42
|
+
/** Coerces a value to a number and requires it to be an integer. */
|
|
43
|
+
toInteger: typeof toInteger;
|
|
44
|
+
/** Lowercases a string (coercing nullish values to `""` first). */
|
|
45
|
+
toLowerCase: typeof toLowerCase;
|
|
46
|
+
/** Coerces a value to a number, rejecting empty/whitespace-only strings instead of silently resolving to `0`. */
|
|
47
|
+
toNumber: typeof toNumber;
|
|
48
|
+
/** Compiles a value into a `RegExp`. */
|
|
49
|
+
toRegExp: typeof toRegExp;
|
|
50
|
+
/** Coerces a value to a string, treating nullish values as `""`. */
|
|
51
|
+
toString: typeof toString;
|
|
52
|
+
/** Parses a value into a `URL`, treating nullish values as `""` first. */
|
|
53
|
+
toURL: typeof toURL;
|
|
54
|
+
/** Uppercases a string (coercing nullish values to `""` first). */
|
|
55
|
+
toUpperCase: typeof toUpperCase;
|
|
56
|
+
/** Trims surrounding whitespace from a string (coercing nullish values to `""` first). */
|
|
57
|
+
trim: typeof trim;
|
|
58
|
+
};
|
|
59
|
+
/** Convenience {@link runtime.Validator} implementations for common validation patterns (e.g. `validators.range(1, 65535)`). */
|
|
60
|
+
export declare const validators: {
|
|
61
|
+
/** Passes when the date value is strictly after `date`. */
|
|
62
|
+
after: typeof after;
|
|
63
|
+
/** Passes only when every wrapped validator passes; returns the first failing message. */
|
|
64
|
+
all: typeof all;
|
|
65
|
+
/** Passes when at least one wrapped validator passes. */
|
|
66
|
+
any: typeof any;
|
|
67
|
+
/** Passes when the date value is strictly before `date`. */
|
|
68
|
+
before: typeof before;
|
|
69
|
+
/** Identity wrapper for a hand-written `Validator<T>`: no behavior change, just a fluent entry point alongside the other helpers. */
|
|
70
|
+
custom: typeof custom;
|
|
71
|
+
/** Passes for a plausibly-shaped email address (`local@domain`). */
|
|
72
|
+
email: typeof email;
|
|
73
|
+
/** Passes when the string ends with `suffix`. */
|
|
74
|
+
endsWith: typeof endsWith;
|
|
75
|
+
/** Alias for `oneOf`: passes when the value is one of the `allowed` values. */
|
|
76
|
+
enum: typeof oneOf;
|
|
77
|
+
/** Passes when the number is finite (rejects `Infinity`/`-Infinity`/`NaN`). */
|
|
78
|
+
finite: typeof finite;
|
|
79
|
+
/** Passes when the date is strictly after the current time. */
|
|
80
|
+
future: typeof future;
|
|
81
|
+
/** Passes when the string contains `text` as a substring. */
|
|
82
|
+
includes: typeof includes;
|
|
83
|
+
/** Passes when the number is an integer. */
|
|
84
|
+
integer: typeof integerValidator;
|
|
85
|
+
/** Passes when the string's length is exactly `expected`. */
|
|
86
|
+
length: typeof length;
|
|
87
|
+
/** Passes when the string matches `pattern`; `message` overrides the default failure text. */
|
|
88
|
+
matches: typeof matches;
|
|
89
|
+
/** Passes when the number is less than or equal to `maximum`. */
|
|
90
|
+
max: typeof max;
|
|
91
|
+
/** Passes when the array has at most `maximum` items. */
|
|
92
|
+
maxItems: typeof maxItems;
|
|
93
|
+
/** Passes when the string's length is at most `length`. */
|
|
94
|
+
maxLength: typeof maxLength;
|
|
95
|
+
/** Passes when the number is greater than or equal to `minimum`. */
|
|
96
|
+
min: typeof min;
|
|
97
|
+
/** Passes when the array has at least `minimum` items. */
|
|
98
|
+
minItems: typeof minItems;
|
|
99
|
+
/** Passes when the string's length is at least `length`. */
|
|
100
|
+
minLength: typeof minLength;
|
|
101
|
+
/** Passes when the number is strictly negative. */
|
|
102
|
+
negative: typeof negative;
|
|
103
|
+
/** Inverts a validator: passes when the wrapped validator fails, and vice versa. */
|
|
104
|
+
not: typeof not;
|
|
105
|
+
/** Passes when the value is one of the `allowed` values. */
|
|
106
|
+
oneOf: typeof oneOf;
|
|
107
|
+
/** Passes when the value is undefined, otherwise delegates to the provided validator. */
|
|
108
|
+
optional: typeof optional;
|
|
109
|
+
/** Passes when the date is strictly before the current time. */
|
|
110
|
+
past: typeof past;
|
|
111
|
+
/** Passes when the number is strictly positive. */
|
|
112
|
+
positive: typeof positive;
|
|
113
|
+
/** Passes when the number is within `[minimum, maximum]` inclusive. */
|
|
114
|
+
range: typeof range;
|
|
115
|
+
/** Runs the wrapped validator but replaces its failure message with `message`. */
|
|
116
|
+
refine: typeof refine;
|
|
117
|
+
/** Alias for `matches`: passes when the string matches `pattern`. */
|
|
118
|
+
regex: typeof matches;
|
|
119
|
+
/** Passes when the value is defined and, unless `allowEmptyString` is set, non-empty. */
|
|
120
|
+
required: typeof required;
|
|
121
|
+
/** Passes when the number is a safe integer (`Number.isSafeInteger`). */
|
|
122
|
+
safeInteger: typeof safeInteger;
|
|
123
|
+
/** Passes when every item in the array is unique. */
|
|
124
|
+
unique: typeof unique;
|
|
125
|
+
/** Passes when the string is a valid absolute URL. */
|
|
126
|
+
url: typeof urlValidator;
|
|
127
|
+
/** Passes when the string is a valid UUID of one of the given `versions` (default: any of 1-8). */
|
|
128
|
+
uuid: typeof uuid;
|
|
129
|
+
/** Shorthand for `uuid([version])`: passes only for that exact UUID version. */
|
|
130
|
+
uuidVersion: typeof uuidVersion;
|
|
131
|
+
};
|
|
132
|
+
//# sourceMappingURL=index.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/helpers/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,EACL,MAAM,EACN,SAAS,EACT,KAAK,EACL,OAAO,EACP,QAAQ,EACR,SAAS,EACT,MAAM,EACN,SAAS,EACT,WAAW,EACX,QAAQ,EACR,QAAQ,EACR,QAAQ,EACR,KAAK,EACL,WAAW,EACX,IAAI,EACL,MAAM,iBAAiB,CAAA;AACxB,OAAO,EACL,KAAK,EACL,GAAG,EACH,GAAG,EACH,MAAM,EACN,MAAM,EACN,KAAK,EACL,QAAQ,EACR,MAAM,EACN,MAAM,EACN,QAAQ,EACR,OAAO,IAAI,gBAAgB,EAC3B,MAAM,EACN,OAAO,EACP,GAAG,EACH,QAAQ,EACR,SAAS,EACT,GAAG,EACH,QAAQ,EACR,SAAS,EACT,QAAQ,EACR,GAAG,EACH,KAAK,EACL,QAAQ,EACR,IAAI,EACJ,QAAQ,EACR,KAAK,EACL,MAAM,EACN,QAAQ,EACR,WAAW,EACX,MAAM,EACN,GAAG,IAAI,YAAY,EACnB,IAAI,EACJ,WAAW,EACZ,MAAM,iBAAiB,CAAA;AAExB;;;;;;;;;GASG;AACH,eAAO,MAAM,UAAU;IACrB,+CAA+C;;IAE/C,wEAAwE;;IAExE,qGAAqG;;IAErG,qHAAqH;;IAErH,qCAAqC;;IAErC,4GAA4G;;IAE5G,oCAAoC;;IAEpC,oEAAoE;;IAEpE,mEAAmE;;IAEnE,iHAAiH;;IAEjH,wCAAwC;;IAExC,oEAAoE;;IAEpE,0EAA0E;;IAE1E,mEAAmE;;IAEnE,0FAA0F;;CAE3F,CAAA;AACD,gIAAgI;AAChI,eAAO,MAAM,UAAU;IACrB,2DAA2D;;IAE3D,0FAA0F;;IAE1F,yDAAyD;;IAEzD,4DAA4D;;IAE5D,qIAAqI;;IAErI,oEAAoE;;IAEpE,iDAAiD;;IAEjD,+EAA+E;;IAE/E,+EAA+E;;IAE/E,+DAA+D;;IAE/D,6DAA6D;;IAE7D,4CAA4C;;IAE5C,6DAA6D;;IAE7D,8FAA8F;;IAE9F,iEAAiE;;IAEjE,yDAAyD;;IAEzD,2DAA2D;;IAE3D,oEAAoE;;IAEpE,0DAA0D;;IAE1D,4DAA4D;;IAE5D,mDAAmD;;IAEnD,oFAAoF;;IAEpF,4DAA4D;;IAE5D,yFAAyF;;IAEzF,gEAAgE;;IAEhE,mDAAmD;;IAEnD,uEAAuE;;IAEvE,kFAAkF;;IAElF,qEAAqE;;IAErE,yFAAyF;;IAEzF,yEAAyE;;IAEzE,qDAAqD;;IAErD,sDAAsD;;IAEtD,mGAAmG;;IAEnG,gFAAgF;;CAEjF,CAAA"}
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
import type { Processor } from "../runtime/index.js";
|
|
2
|
+
/** Splits a delimited string (or passes through an array) into items, running each through `processors` in order. */
|
|
3
|
+
export declare function toArray<T>(separator?: string | RegExp, processors?: Processor<unknown>[]): Processor<T[]>;
|
|
4
|
+
/** Decodes a base64 string into a `Buffer`. */
|
|
5
|
+
export declare function base64(): Processor<Buffer>;
|
|
6
|
+
/** Coerces a value to a `bigint`. */
|
|
7
|
+
export declare function toBigInt(): Processor<bigint>;
|
|
8
|
+
/** Coerces common boolean-like strings (`true`/`1`/`yes`/`on`, and their opposites) into a real boolean. */
|
|
9
|
+
export declare function toBoolean(): Processor<boolean>;
|
|
10
|
+
/** Parses a value into a `Date`. */
|
|
11
|
+
export declare function toDate(): Processor<Date>;
|
|
12
|
+
/** Coerces a value to a number and requires it to be an integer. */
|
|
13
|
+
export declare function toInteger(): Processor<number>;
|
|
14
|
+
/** Parses a JSON string; passes non-string values through unchanged. */
|
|
15
|
+
export declare function parseJSON<T = unknown>(): Processor<T>;
|
|
16
|
+
/** Lowercases a string (coercing nullish values to `""` first). */
|
|
17
|
+
export declare function toLowerCase(): Processor<string>;
|
|
18
|
+
/** Coerces a value to a number, rejecting empty/whitespace-only strings instead of silently resolving to `0`. */
|
|
19
|
+
export declare function toNumber(): Processor<number>;
|
|
20
|
+
/** Compiles a value into a `RegExp`. */
|
|
21
|
+
export declare function toRegExp(): Processor<RegExp>;
|
|
22
|
+
/** Splits a string on `separator` into a trimmed string array; returns `[]` for non-string input. */
|
|
23
|
+
export declare function split(separator?: string): Processor<string[]>;
|
|
24
|
+
/** Coerces a value to a string, treating nullish values as `""`. */
|
|
25
|
+
export declare function toString(): Processor<string>;
|
|
26
|
+
/** Trims surrounding whitespace from a string (coercing nullish values to `""` first). */
|
|
27
|
+
export declare function trim(): Processor<string>;
|
|
28
|
+
/** Uppercases a string (coercing nullish values to `""` first). */
|
|
29
|
+
export declare function toUpperCase(): Processor<string>;
|
|
30
|
+
/** Parses a value into a `URL`, treating nullish values as `""` first. */
|
|
31
|
+
export declare function toURL(): Processor<URL>;
|
|
32
|
+
//# sourceMappingURL=processors.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"processors.d.ts","sourceRoot":"","sources":["../../../src/helpers/processors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAA;AAepD,qHAAqH;AACrH,wBAAgB,OAAO,CAAC,CAAC,EACvB,SAAS,GAAE,MAAM,GAAG,MAAY,EAChC,UAAU,GAAE,SAAS,CAAC,OAAO,CAAC,EAAO,GACpC,SAAS,CAAC,CAAC,EAAE,CAAC,CAYhB;AAED,+CAA+C;AAC/C,wBAAgB,MAAM,IAAI,SAAS,CAAC,MAAM,CAAC,CAQ1C;AAED,qCAAqC;AACrC,wBAAgB,QAAQ,IAAI,SAAS,CAAC,MAAM,CAAC,CAQ5C;AAED,4GAA4G;AAC5G,wBAAgB,SAAS,IAAI,SAAS,CAAC,OAAO,CAAC,CAS9C;AAED,oCAAoC;AACpC,wBAAgB,MAAM,IAAI,SAAS,CAAC,IAAI,CAAC,CAUxC;AAED,oEAAoE;AACpE,wBAAgB,SAAS,IAAI,SAAS,CAAC,MAAM,CAAC,CAU7C;AAED,wEAAwE;AACxE,wBAAgB,SAAS,CAAC,CAAC,GAAG,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,CAcrD;AAED,mEAAmE;AACnE,wBAAgB,WAAW,IAAI,SAAS,CAAC,MAAM,CAAC,CAE/C;AAED,iHAAiH;AACjH,wBAAgB,QAAQ,IAAI,SAAS,CAAC,MAAM,CAAC,CAc5C;AAED,wCAAwC;AACxC,wBAAgB,QAAQ,IAAI,SAAS,CAAC,MAAM,CAAC,CAQ5C;AAED,qGAAqG;AACrG,wBAAgB,KAAK,CAAC,SAAS,SAAM,GAAG,SAAS,CAAC,MAAM,EAAE,CAAC,CAM1D;AAED,oEAAoE;AACpE,wBAAgB,QAAQ,IAAI,SAAS,CAAC,MAAM,CAAC,CAK5C;AAED,0FAA0F;AAC1F,wBAAgB,IAAI,IAAI,SAAS,CAAC,MAAM,CAAC,CAExC;AAED,mEAAmE;AACnE,wBAAgB,WAAW,IAAI,SAAS,CAAC,MAAM,CAAC,CAE/C;AAED,0EAA0E;AAC1E,wBAAgB,KAAK,IAAI,SAAS,CAAC,GAAG,CAAC,CAStC"}
|
|
@@ -0,0 +1,68 @@
|
|
|
1
|
+
import type { Validator } from "../runtime/index.js";
|
|
2
|
+
/** Passes when the date value is strictly after `date`. */
|
|
3
|
+
export declare function after(date: Date): Validator<Date>;
|
|
4
|
+
/** Passes only when every wrapped validator passes; returns the first failing message. */
|
|
5
|
+
export declare function all<T>(...validators: Validator<T>[]): Validator<T>;
|
|
6
|
+
/** Passes when at least one wrapped validator passes. */
|
|
7
|
+
export declare function any<T>(...validators: Validator<T>[]): Validator<T>;
|
|
8
|
+
/** Passes when the date value is strictly before `date`. */
|
|
9
|
+
export declare function before(date: Date): Validator<Date>;
|
|
10
|
+
/** Identity wrapper for a hand-written `Validator<T>`: no behavior change, just a fluent entry point alongside the other helpers. */
|
|
11
|
+
export declare function custom<T>(validator: Validator<T>): Validator<T>;
|
|
12
|
+
/** Passes for a plausibly-shaped email address (`local@domain`). */
|
|
13
|
+
export declare function email(): Validator<string>;
|
|
14
|
+
/** Passes when the string ends with `suffix`. */
|
|
15
|
+
export declare function endsWith(suffix: string): Validator<string>;
|
|
16
|
+
/** Passes when the number is finite (rejects `Infinity`/`-Infinity`/`NaN`). */
|
|
17
|
+
export declare function finite(): Validator<number>;
|
|
18
|
+
/** Passes when the date is strictly after the current time. */
|
|
19
|
+
export declare function future(): Validator<Date>;
|
|
20
|
+
/** Passes when the string contains `text` as a substring. */
|
|
21
|
+
export declare function includes(text: string): Validator<string>;
|
|
22
|
+
/** Passes when the number is an integer. */
|
|
23
|
+
export declare function integer(): Validator<number>;
|
|
24
|
+
/** Passes when the string's length is exactly `expected`. */
|
|
25
|
+
export declare function length(expected: number): Validator<string>;
|
|
26
|
+
/** Passes when the string matches `pattern`; `message` overrides the default failure text. */
|
|
27
|
+
export declare function matches(pattern: RegExp, message?: string): Validator<string>;
|
|
28
|
+
/** Passes when the number is less than or equal to `maximum`. */
|
|
29
|
+
export declare function max(maximum: number): Validator<number>;
|
|
30
|
+
/** Passes when the array has at most `maximum` items. */
|
|
31
|
+
export declare function maxItems<T>(maximum: number): Validator<T[]>;
|
|
32
|
+
/** Passes when the string's length is at most `length`. */
|
|
33
|
+
export declare function maxLength(length: number): Validator<string>;
|
|
34
|
+
/** Passes when the number is greater than or equal to `minimum`. */
|
|
35
|
+
export declare function min(minimum: number): Validator<number>;
|
|
36
|
+
/** Passes when the array has at least `minimum` items. */
|
|
37
|
+
export declare function minItems<T>(minimum: number): Validator<T[]>;
|
|
38
|
+
/** Passes when the string's length is at least `length`. */
|
|
39
|
+
export declare function minLength(length: number): Validator<string>;
|
|
40
|
+
/** Passes when the number is strictly negative. */
|
|
41
|
+
export declare function negative(): Validator<number>;
|
|
42
|
+
/** Inverts a validator: passes when the wrapped validator fails, and vice versa. */
|
|
43
|
+
export declare function not<T>(validator: Validator<T>): Validator<T>;
|
|
44
|
+
/** Passes when the value is one of the `allowed` values. */
|
|
45
|
+
export declare function oneOf<T>(allowed: readonly T[]): Validator<T>;
|
|
46
|
+
/** Passes when the value is undefined, otherwise delegates to the provided validator. */
|
|
47
|
+
export declare function optional<T>(validator: Validator<T>): Validator<T | undefined>;
|
|
48
|
+
/** Passes when the date is strictly before the current time. */
|
|
49
|
+
export declare function past(): Validator<Date>;
|
|
50
|
+
/** Passes when the number is strictly positive. */
|
|
51
|
+
export declare function positive(): Validator<number>;
|
|
52
|
+
/** Passes when the number is within `[minimum, maximum]` inclusive. */
|
|
53
|
+
export declare function range(minimum: number, maximum: number): Validator<number>;
|
|
54
|
+
/** Runs the wrapped validator but replaces its failure message with `message`. */
|
|
55
|
+
export declare function refine<T>(validator: Validator<T>, message: string): Validator<T>;
|
|
56
|
+
/** Passes when the value is defined and, unless `allowEmptyString` is set, non-empty. */
|
|
57
|
+
export declare function required(allowEmptyString?: boolean): Validator<unknown>;
|
|
58
|
+
/** Passes when the number is a safe integer (`Number.isSafeInteger`). */
|
|
59
|
+
export declare function safeInteger(): Validator<number>;
|
|
60
|
+
/** Passes when every item in the array is unique. */
|
|
61
|
+
export declare function unique<T>(): Validator<T[]>;
|
|
62
|
+
/** Passes when the string is a valid absolute URL. */
|
|
63
|
+
export declare function url(): Validator<string>;
|
|
64
|
+
/** Passes when the string is a valid UUID of one of the given `versions` (default: any of 1-8). */
|
|
65
|
+
export declare function uuid(versions?: readonly number[]): Validator<string>;
|
|
66
|
+
/** Shorthand for `uuid([version])`: passes only for that exact UUID version. */
|
|
67
|
+
export declare function uuidVersion(number: number): Validator<string>;
|
|
68
|
+
//# sourceMappingURL=validators.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"validators.d.ts","sourceRoot":"","sources":["../../../src/helpers/validators.ts"],"names":[],"mappings":"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"}
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The Node file system adapter for the build entry (`@maverickcer/env-cap/node`).
|
|
3
|
+
*
|
|
4
|
+
* `@maverickcer/env-cap/build` never imports `node:fs` (ADR 0040), so every generator takes the file
|
|
5
|
+
* system as a required `fs` option. A Node build script passes `nodeBuildFileSystem`:
|
|
6
|
+
*
|
|
7
|
+
* ```ts
|
|
8
|
+
* import { generateEnvArtifacts } from "@maverickcer/env-cap/build"
|
|
9
|
+
* import { nodeBuildFileSystem } from "@maverickcer/env-cap/node"
|
|
10
|
+
*
|
|
11
|
+
* await generateEnvArtifacts({ fs: nodeBuildFileSystem, root, manifest: { ... } })
|
|
12
|
+
* ```
|
|
13
|
+
*
|
|
14
|
+
* Like `bin` and `./eslint-plugin`, this entry runs only in Node, and it is the one place the build
|
|
15
|
+
* path loads `node:fs/promises`. In another runtime, implement the `BuildFileSystem` type that
|
|
16
|
+
* `./build` exports instead.
|
|
17
|
+
*
|
|
18
|
+
* @packageDocumentation
|
|
19
|
+
*/
|
|
20
|
+
export { nodeBuildFileSystem } from "../cli/filesystem.js";
|
|
21
|
+
//# sourceMappingURL=index.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/node/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAA"}
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
import type { EnvValidationError } from "./errors.js";
|
|
2
|
+
import type { validateEnvResult } from "./types.js";
|
|
3
|
+
export interface CacheState {
|
|
4
|
+
/** ids of every contract validated as part of this initialization, so resetEnvCache() can clean up precisely. */
|
|
5
|
+
contractIds: Set<symbol>;
|
|
6
|
+
result?: validateEnvResult;
|
|
7
|
+
error?: EnvValidationError;
|
|
8
|
+
inFlight?: Promise<validateEnvResult>;
|
|
9
|
+
}
|
|
10
|
+
export declare function getState(): CacheState;
|
|
11
|
+
export declare function getContractValues(id: symbol): Readonly<Record<string, unknown>> | undefined;
|
|
12
|
+
export declare function setContractValues(id: symbol, values: Readonly<Record<string, unknown>>): void;
|
|
13
|
+
export declare function getContractError(id: symbol): EnvValidationError | undefined;
|
|
14
|
+
export declare function setContractError(id: symbol, error: EnvValidationError): void;
|
|
15
|
+
/** Clears cached state: the global status plus every contract validated as part of it. */
|
|
16
|
+
export declare function resetCache(): void;
|
|
17
|
+
//# sourceMappingURL=cache.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../../src/runtime/cache.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAA;AACrD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AAEnD,MAAM,WAAW,UAAU;IACzB,iHAAiH;IACjH,WAAW,EAAE,GAAG,CAAC,MAAM,CAAC,CAAA;IACxB,MAAM,CAAC,EAAE,iBAAiB,CAAA;IAC1B,KAAK,CAAC,EAAE,kBAAkB,CAAA;IAC1B,QAAQ,CAAC,EAAE,OAAO,CAAC,iBAAiB,CAAC,CAAA;CACtC;AAqBD,wBAAgB,QAAQ,IAAI,UAAU,CAErC;AAED,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,SAAS,CAE3F;AAED,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,IAAI,CAE7F;AAED,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,MAAM,GAAG,kBAAkB,GAAG,SAAS,CAE3E;AAED,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,kBAAkB,GAAG,IAAI,CAE5E;AAED,0FAA0F;AAC1F,wBAAgB,UAAU,IAAI,IAAI,CAMjC"}
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
import type { CreateEnvOptions, EnvContract, EnvSchema } from "./types.js";
|
|
2
|
+
/**
|
|
3
|
+
* Declares a feature's environment contract. Colocate this call with the
|
|
4
|
+
* feature that consumes the variables (e.g. `features/payments/env.schema.ts`).
|
|
5
|
+
*
|
|
6
|
+
* @remarks
|
|
7
|
+
* `createEnv` is runtime-only: `processor`/`validator`/`default` are the
|
|
8
|
+
* whole vocabulary, because they're the only fields {@link validateEnv} actually
|
|
9
|
+
* reads. Documentation (description, ownership, lifecycle, category, and
|
|
10
|
+
* everything else that only exists to generate docs) lives in a separate
|
|
11
|
+
* {@link documentEnv} call (see `document.ts`), which is entirely optional and
|
|
12
|
+
* never required for this to work.
|
|
13
|
+
*
|
|
14
|
+
* @returns An {@link EnvContract} exposing one read-only getter per key: there is no
|
|
15
|
+
* global env object, only per-feature contracts like `paymentsEnv.STRIPE_KEY`. Accessing a
|
|
16
|
+
* key throws until {@link validateEnv} has run successfully for the runtime this contract
|
|
17
|
+
* was passed to.
|
|
18
|
+
*
|
|
19
|
+
* The contract redacts itself under `console.log`, `String()`, `JSON.stringify` and template
|
|
20
|
+
* interpolation. Spreading it or calling `Object.entries()` on it reads every value, so do not.
|
|
21
|
+
*/
|
|
22
|
+
export declare function createEnv<S extends EnvSchema>(schema: S, options?: CreateEnvOptions): EnvContract<S>;
|
|
23
|
+
//# sourceMappingURL=create.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"create.d.ts","sourceRoot":"","sources":["../../../src/runtime/create.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAqB,gBAAgB,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AAI7F;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,SAAS,CAAC,CAAC,SAAS,SAAS,EAC3C,MAAM,EAAE,CAAC,EACT,OAAO,GAAE,gBAAqB,GAC7B,WAAW,CAAC,CAAC,CAAC,CA4ChB"}
|
|
@@ -0,0 +1,214 @@
|
|
|
1
|
+
import type { EnvSchema } from "./types.js";
|
|
2
|
+
/**
|
|
3
|
+
* Developer-supplied evidence assertions for one variable. They differ in kind from every field on
|
|
4
|
+
* {@link VariableDocs}, which are declared and never verified. `dynamicAccess` is re-checked against
|
|
5
|
+
* reality on every run (fresh / stale / missing). It lives apart, in `VariableDocs.evidence`, not
|
|
6
|
+
* beside `description`, `owner` and the rest. So the shape itself shows the different status, not
|
|
7
|
+
* only a doc comment. See ADR 0037.
|
|
8
|
+
*/
|
|
9
|
+
export interface VariableEvidenceDocs {
|
|
10
|
+
/**
|
|
11
|
+
* Citation(s) of where this variable is read dynamically, somewhere env-cap's static AST scan
|
|
12
|
+
* can't see (a shell script, a Docker entrypoint, a sibling service). Each entry is a
|
|
13
|
+
* `"<relative-path>:<line>:<column>"` citation.
|
|
14
|
+
*
|
|
15
|
+
* @remarks
|
|
16
|
+
* A developer's re-acknowledgment that access happens, never a claim that env-cap observed
|
|
17
|
+
* anything. It is tracked as its own fact and never folded into the AST-derived
|
|
18
|
+
* `VariableAccessStatus`. It is re-verified every run. A citation whose file is gone, or whose
|
|
19
|
+
* content has visibly changed since it was acknowledged, is flagged rather than trusted forever.
|
|
20
|
+
*/
|
|
21
|
+
dynamicAccess?: readonly string[];
|
|
22
|
+
}
|
|
23
|
+
/**
|
|
24
|
+
* Per-variable documentation. Every field is optional and unconstrained on purpose. With no
|
|
25
|
+
* required shape, documenting a variable never fights the type checker. A field the generator
|
|
26
|
+
* doesn't know yet is accepted, not rejected.
|
|
27
|
+
*/
|
|
28
|
+
export interface VariableDocs {
|
|
29
|
+
/** Human-readable explanation of what this variable is and what it controls. */
|
|
30
|
+
description?: string;
|
|
31
|
+
/** Who owns this variable (a team, a handle, whatever your org uses). Overrides the contract's own `owner` for this key. */
|
|
32
|
+
owner?: string;
|
|
33
|
+
/**
|
|
34
|
+
* How sensitive this variable's value is. Overrides the contract's own `sensitivity` for this
|
|
35
|
+
* key.
|
|
36
|
+
*
|
|
37
|
+
* @remarks
|
|
38
|
+
* Deliberately an open `string`, not a closed union. An org's sensitivity vocabulary is its own,
|
|
39
|
+
* and a level env-cap doesn't recognize is always honored, never dropped. The generator
|
|
40
|
+
* still reports a `NONSTANDARD_SENSITIVITY_LEVEL` finding (severity `info`, never blocking) for
|
|
41
|
+
* anything outside `secret`/`credential`/`pii`/`config`, so vocabulary drift stays visible
|
|
42
|
+
* without being enforced.
|
|
43
|
+
*/
|
|
44
|
+
sensitivity?: string;
|
|
45
|
+
/** ISO date string (e.g. "2026-06-01"): when this variable's current value stops being valid (a key rotation deadline, a sunset date, etc.). */
|
|
46
|
+
expiresAt?: string;
|
|
47
|
+
/** How to get a new value before/when it expires (e.g. "Rotate in the Stripe dashboard, then redeploy."). */
|
|
48
|
+
refreshInstructions?: string;
|
|
49
|
+
/**
|
|
50
|
+
* The kind of authenticator/secret this variable holds (e.g. "api-key", "oauth-client-secret",
|
|
51
|
+
* "database-password", "tls-certificate"). It feeds the "authenticator type" column of the NIST
|
|
52
|
+
* SP 800-53 IA-5 rotation-status report. IA-5 requires an organization-defined rotation period
|
|
53
|
+
* "by authenticator type," so a generator groups and labels by this field.
|
|
54
|
+
*
|
|
55
|
+
* @remarks
|
|
56
|
+
* Deliberately an open `string`, not a closed union, like {@link sensitivity}. An org's
|
|
57
|
+
* authenticator taxonomy is its own, and IA-5 itself names no fixed set of types.
|
|
58
|
+
*/
|
|
59
|
+
authenticatorType?: string;
|
|
60
|
+
/**
|
|
61
|
+
* How often this variable's value must be rotated, in organization-defined terms (e.g. "90
|
|
62
|
+
* days", "P90D", "6 months"). This is IA-5's "organization-defined time period" per authenticator
|
|
63
|
+
* type (the time-based half of IA-5's two-trigger rotation model). Paired with
|
|
64
|
+
* {@link lastRotatedAt}, it lets a generator compute whether rotation is current. Without it, a
|
|
65
|
+
* generator could only record that a period was declared. `lifecycle-model.ts`'s
|
|
66
|
+
* `computeRotationStatus()` shows how the two combine with {@link expiresAt}. The result is a
|
|
67
|
+
* policy-window judgement over declared metadata ("within the declared period"). It never states
|
|
68
|
+
* that a rotation happened or that a control is met. env-cap reads declarations; it does not
|
|
69
|
+
* check them against the secret store.
|
|
70
|
+
*/
|
|
71
|
+
rotationPeriod?: string;
|
|
72
|
+
/**
|
|
73
|
+
* ISO date string: the last time this variable's value was actually rotated. Paired with
|
|
74
|
+
* {@link rotationPeriod} to compute whether rotation is within the declared period. Independent of {@link expiresAt}, which
|
|
75
|
+
* states when the *current* value stops being valid, not when it was last changed. A value can
|
|
76
|
+
* be freshly rotated and still have a near-term `expiresAt` (a short-lived token). It can also be
|
|
77
|
+
* long overdue for rotation while its `expiresAt` (if any) is still comfortably in the future.
|
|
78
|
+
*/
|
|
79
|
+
lastRotatedAt?: string;
|
|
80
|
+
/**
|
|
81
|
+
* IA-5's event-based rotation triggers that apply to this variable (e.g. "suspected compromise",
|
|
82
|
+
* "personnel change", "system update"): the event-based half of IA-5's two-trigger rotation
|
|
83
|
+
* model. It sits beside the free-text {@link refreshInstructions} and does not replace it. This
|
|
84
|
+
* is a list a generator can render as its own column; `refreshInstructions` stays prose ("how to
|
|
85
|
+
* actually rotate it"). It is presence-only: env-cap cannot observe whether a listed event
|
|
86
|
+
* occurred. So declaring it never changes a computed rotation status by itself (see
|
|
87
|
+
* `lifecycle-model.ts`). It only makes the event-based trigger visible in generated output.
|
|
88
|
+
*/
|
|
89
|
+
rotationTriggerEvents?: readonly string[];
|
|
90
|
+
/**
|
|
91
|
+
* Explicit, actionable instructions for obtaining this variable's value the *first* time.
|
|
92
|
+
* `refreshInstructions` is "how to rotate it once you already have one"; this is "how to get
|
|
93
|
+
* one at all" (e.g. "Create a restricted API key in the Stripe dashboard under Developers ->
|
|
94
|
+
* API keys, scoped to read/write Charges."). It is a named field so it renders as its own
|
|
95
|
+
* labeled line in generated docs. A `metadata.setup`-style convention would get no dedicated
|
|
96
|
+
* rendering or type checking.
|
|
97
|
+
*/
|
|
98
|
+
setupInstructions?: string;
|
|
99
|
+
/** Documentation-level assertion that this variable must be set. Independent of how (or whether) a validator actually enforces it. */
|
|
100
|
+
required?: boolean;
|
|
101
|
+
/** Marks this variable as being phased out. Independent of `expiresAt` (a rotation/sunset date) and of the contract-level `active` switch (on/off, not a phase-out signal). */
|
|
102
|
+
deprecated?: boolean;
|
|
103
|
+
/** Why this variable is deprecated, and/or what to use instead. Only meaningful alongside `deprecated: true`. */
|
|
104
|
+
deprecatedReason?: string;
|
|
105
|
+
/** ISO date string: by when a deprecated variable must be removed. Only meaningful alongside `deprecated: true`. */
|
|
106
|
+
removeBy?: string;
|
|
107
|
+
/** The previous environment variable name this one replaces, if this declaration is the result of a rename. Lets the Change Model correlate a remove+add pair into a single rename entry instead of two unrelated changes. */
|
|
108
|
+
renamedFrom?: string;
|
|
109
|
+
/** Why this variable's value is collected/used: a framework-agnostic fact (pairs with `legalBasis`; a specific citation like a GDPR article belongs in `metadata` instead). Overrides the contract's own `purpose` for this key. */
|
|
110
|
+
purpose?: string;
|
|
111
|
+
/** The legal basis this variable's collection/use relies on: framework-agnostic (e.g. "user consent," "contractual necessity"), never a specific statute name. Overrides the contract's own `legalBasis` for this key. */
|
|
112
|
+
legalBasis?: string;
|
|
113
|
+
/** Descriptive retention policy (e.g. "delete after 90 days"). A policy statement, not a computed value: unlike `expiresAt`, nothing parses or evaluates this. Overrides the contract's own `retention` for this key. */
|
|
114
|
+
retention?: string;
|
|
115
|
+
/** Where this variable's value is/must be stored (a region, or a permitted set of regions). Overrides the contract's own `dataResidency` for this key. */
|
|
116
|
+
dataResidency?: string | string[];
|
|
117
|
+
/** Documentation-level assertion that this variable's handling must be auditable. Overrides the contract's own `auditRequired` for this key. */
|
|
118
|
+
auditRequired?: boolean;
|
|
119
|
+
/**
|
|
120
|
+
* Developer-supplied evidence assertions for this variable: verified over
|
|
121
|
+
* time, unlike every other field above, which is declared and never
|
|
122
|
+
* verified. Kept structurally separate for exactly that reason; see
|
|
123
|
+
* {@link VariableEvidenceDocs}.
|
|
124
|
+
*/
|
|
125
|
+
evidence?: VariableEvidenceDocs;
|
|
126
|
+
/**
|
|
127
|
+
* Structured, unsupported-key documentation: any primitive or object value, for anything that
|
|
128
|
+
* doesn't warrant its own named field. A key that has a named field above belongs in that field,
|
|
129
|
+
* not here.
|
|
130
|
+
*/
|
|
131
|
+
metadata?: Record<string, unknown>;
|
|
132
|
+
}
|
|
133
|
+
/**
|
|
134
|
+
* Contract-level documentation. Only the generator reads these fields; validation never does.
|
|
135
|
+
*
|
|
136
|
+
* @remarks
|
|
137
|
+
* Generic over `S`, the exact schema type {@link documentEnv} infers from its `schema` argument.
|
|
138
|
+
* That makes `variables` below a closed, checked map, not an open `Record<string, VariableDocs>`
|
|
139
|
+
* any string would satisfy. A typo'd or renamed key is a compile error, not a silent no-op. `S`
|
|
140
|
+
* defaults to the widest possible schema. So this type is still nameable on its own (e.g. in a
|
|
141
|
+
* helper function's parameter type) without narrowing to one specific contract.
|
|
142
|
+
*/
|
|
143
|
+
export interface ContractDocs<S extends EnvSchema = EnvSchema> {
|
|
144
|
+
/** Overrides the auto-generated label used in generated docs. Purely cosmetic. Wins over `createEnv()`'s own `name` option, which in turn wins over the exported binding name. */
|
|
145
|
+
name?: string;
|
|
146
|
+
/** Groups this contract under a heading in the generated docs' feature catalog. */
|
|
147
|
+
category?: string;
|
|
148
|
+
/** The generator throws if two *active* contracts declare the same `exclusiveGroup`: use it to mark interchangeable features (e.g. two database backends) as mutually exclusive. */
|
|
149
|
+
exclusiveGroup?: string;
|
|
150
|
+
/** When `false`, this contract is excluded from the generated manifest, docs' required section, and exclusiveGroup checks: it still appears, marked disabled, in the feature catalog. Defaults to `true`. */
|
|
151
|
+
active?: boolean;
|
|
152
|
+
/** Default owner for every variable in this contract that doesn't set its own `owner`. */
|
|
153
|
+
owner?: string;
|
|
154
|
+
/** Default sensitivity for every variable in this contract that doesn't set its own `sensitivity`: see {@link VariableDocs.sensitivity} for why this is an open `string`. */
|
|
155
|
+
sensitivity?: string;
|
|
156
|
+
/** Whole-contract/feature sunset date, ISO date string. */
|
|
157
|
+
expiresAt?: string;
|
|
158
|
+
/** Marks this whole contract/feature as being phased out. Independent of `active` (on/off, not a phase-out signal). */
|
|
159
|
+
deprecated?: boolean;
|
|
160
|
+
/** Why this contract is deprecated, and/or what to use instead. Only meaningful alongside `deprecated: true`. */
|
|
161
|
+
deprecatedReason?: string;
|
|
162
|
+
/** Default reason this contract's variables' values are collected/used: see {@link VariableDocs.purpose}. */
|
|
163
|
+
purpose?: string;
|
|
164
|
+
/** Default legal basis for this contract's variables: see {@link VariableDocs.legalBasis}. */
|
|
165
|
+
legalBasis?: string;
|
|
166
|
+
/** Default retention policy for this contract's variables: see {@link VariableDocs.retention}. */
|
|
167
|
+
retention?: string;
|
|
168
|
+
/** Default data residency for this contract's variables: see {@link VariableDocs.dataResidency}. */
|
|
169
|
+
dataResidency?: string | string[];
|
|
170
|
+
/** Default audit-required assertion for this contract's variables: see {@link VariableDocs.auditRequired}. */
|
|
171
|
+
auditRequired?: boolean;
|
|
172
|
+
/** Arbitrary contract-level documentation (e.g. `runbook`), rendered alongside this feature: see {@link VariableDocs.metadata}. */
|
|
173
|
+
metadata?: Record<string, unknown>;
|
|
174
|
+
/**
|
|
175
|
+
* Per-variable documentation, keyed by variable name. Keys are checked against `S`'s own keys
|
|
176
|
+
* at compile time. Documenting a variable that was renamed or removed from `schema` (or a plain
|
|
177
|
+
* typo) is therefore a type error here. The generator never has to report it as "stale" after
|
|
178
|
+
* the fact. A schema key absent from `variables` entirely is
|
|
179
|
+
* still valid (not every variable needs documentation). The generator reports it as
|
|
180
|
+
* undocumented.
|
|
181
|
+
*/
|
|
182
|
+
variables?: {
|
|
183
|
+
readonly [K in keyof S]?: VariableDocs;
|
|
184
|
+
};
|
|
185
|
+
}
|
|
186
|
+
/**
|
|
187
|
+
* Documents a schema for the generator: explains values, assigns ownership,
|
|
188
|
+
* and describes lifecycle, feeding the generated docs artifact and
|
|
189
|
+
* `.env.example`. Pass it the *same* schema object given to {@link createEnv}.
|
|
190
|
+
* The generator then statically links the two and verifies every variable is
|
|
191
|
+
* documented. TypeScript also checks `docs.variables`' keys against
|
|
192
|
+
* `schema`'s own keys, so the same object identity serves both the
|
|
193
|
+
* generator's static link and the type checker.
|
|
194
|
+
*
|
|
195
|
+
* @remarks
|
|
196
|
+
* A no-op at runtime by design: nothing passed here is retained anywhere,
|
|
197
|
+
* and this can never throw, no matter how malformed `schema`/`docs` are.
|
|
198
|
+
* Calling it is entirely optional: {@link createEnv} works identically whether or
|
|
199
|
+
* not a matching `documentEnv` call exists. The real "is everything
|
|
200
|
+
* documented?" check runs entirely inside {@link build.generateEnvManifest}'s
|
|
201
|
+
* static analysis. So does every artifact this data drives: the docs
|
|
202
|
+
* artifact's ownership matrix, dependency graph, lifecycle report and
|
|
203
|
+
* security review, and `.env.example`'s comments. At runtime this function
|
|
204
|
+
* only exists as a safe marker the AST parser can find, and gives you
|
|
205
|
+
* type-checked argument shapes while writing it.
|
|
206
|
+
*
|
|
207
|
+
* `S` is inferred from `schema`, never written out by hand. Pass the
|
|
208
|
+
* schema object literal (or a `const`-inferred reference to it) directly for
|
|
209
|
+
* the strongest inference. An explicitly-widened `schema: EnvSchema`
|
|
210
|
+
* annotation loses the per-key literal type, so `docs.variables` then
|
|
211
|
+
* accepts any string key.
|
|
212
|
+
*/
|
|
213
|
+
export declare function documentEnv<S extends EnvSchema>(schema: S, docs: ContractDocs<S>): void;
|
|
214
|
+
//# sourceMappingURL=document.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"document.d.ts","sourceRoot":"","sources":["../../../src/runtime/document.ts"],"names":[],"mappings":"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"}
|
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Every error type here is constructed only from: the variable name, the
|
|
3
|
+
* declaring contract's name, the failure kind, and a message string that the
|
|
4
|
+
* *developer's own* processor/validator produced. Raw or processed environment
|
|
5
|
+
* values are never read into an error: see the Security section in the README.
|
|
6
|
+
*
|
|
7
|
+
* Documentation (description, owner, etc.) never appears here, even when a
|
|
8
|
+
* {@link documentEnv} call exists for this variable: `documentEnv` is
|
|
9
|
+
* build-time-only and its data is never retained anywhere {@link validateEnv}
|
|
10
|
+
* could read it back out. This is a deliberate consequence of keeping the
|
|
11
|
+
* runtime minimal, not an oversight.
|
|
12
|
+
*/
|
|
13
|
+
/** One variable's processing or validation failure, as recorded by {@link validateEnv}. */
|
|
14
|
+
export interface VariableFailure {
|
|
15
|
+
/** The schema key that failed. */
|
|
16
|
+
readonly variable: string;
|
|
17
|
+
/** The declaring contract's `name` (see {@link CreateEnvOptions}). */
|
|
18
|
+
readonly contractName: string;
|
|
19
|
+
/** `import.meta.url` (or similar) passed to `createEnv`'s `source` option, if any. Falls back to `contractName` when absent. */
|
|
20
|
+
readonly source: string | undefined;
|
|
21
|
+
/** Which stage produced the failure. */
|
|
22
|
+
readonly kind: "processor" | "validator";
|
|
23
|
+
/** The error message from the developer's own processor/validator, or the thrown error's message. */
|
|
24
|
+
readonly message: string;
|
|
25
|
+
}
|
|
26
|
+
/**
|
|
27
|
+
* Thrown by {@link validateEnv} when one or more variables fail processing or
|
|
28
|
+
* validation. Aggregates every failure across every contract in the batch:
|
|
29
|
+
* the caller sees the whole picture in one error, not one-at-a-time.
|
|
30
|
+
*
|
|
31
|
+
* @remarks
|
|
32
|
+
* `code` is a stable, Stable-tier discriminant for programmatic handling:
|
|
33
|
+
* prefer it over `.name`/`instanceof` when a message-independent switch is needed.
|
|
34
|
+
*/
|
|
35
|
+
export declare class EnvValidationError extends Error {
|
|
36
|
+
/** Stable discriminant for programmatic handling; always `"ENV_VALIDATION_FAILED"`. */
|
|
37
|
+
readonly code = "ENV_VALIDATION_FAILED";
|
|
38
|
+
/** Every variable failure across every contract in the batch. */
|
|
39
|
+
readonly failures: readonly VariableFailure[];
|
|
40
|
+
constructor(failures: readonly VariableFailure[]);
|
|
41
|
+
}
|
|
42
|
+
/**
|
|
43
|
+
* Thrown when a contract's value is accessed via property access before
|
|
44
|
+
* {@link validateEnv} has completed successfully for it.
|
|
45
|
+
*
|
|
46
|
+
* @remarks
|
|
47
|
+
* `code` is a stable, Stable-tier discriminant for programmatic handling:
|
|
48
|
+
* prefer it over `.name`/`instanceof` when a message-independent switch is needed.
|
|
49
|
+
*/
|
|
50
|
+
export declare class EnvNotReadyError extends Error {
|
|
51
|
+
/** Stable discriminant for programmatic handling; always `"ENV_NOT_READY"`. */
|
|
52
|
+
readonly code = "ENV_NOT_READY";
|
|
53
|
+
constructor(contractName: string, key: string);
|
|
54
|
+
}
|
|
55
|
+
//# sourceMappingURL=errors.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../src/runtime/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,2FAA2F;AAC3F,MAAM,WAAW,eAAe;IAC9B,kCAAkC;IAClC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,sEAAsE;IACtE,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAC7B,gIAAgI;IAChI,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAA;IACnC,wCAAwC;IACxC,QAAQ,CAAC,IAAI,EAAE,WAAW,GAAG,WAAW,CAAA;IACxC,qGAAqG;IACrG,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CACzB;AAwBD;;;;;;;;GAQG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;IAC3C,uFAAuF;IACvF,QAAQ,CAAC,IAAI,2BAA0B;IACvC,iEAAiE;IACjE,QAAQ,CAAC,QAAQ,EAAE,SAAS,eAAe,EAAE,CAAA;gBAEjC,QAAQ,EAAE,SAAS,eAAe,EAAE;CAMjD;AAED;;;;;;;GAOG;AACH,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,+EAA+E;IAC/E,QAAQ,CAAC,IAAI,mBAAkB;gBAEnB,YAAY,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM;CAS9C"}
|