v3.1.0

release: v3.1.0 (#76)

Release: v3.1.0 — Minor: Built-in Environment Snapshot

✨ NEW FEATURE — api.slothlet.env: FROZEN ENVIRONMENT SNAPSHOT
• Add api.slothlet.env — a frozen copy of process.env captured once at initialization time and exposed through the protected slothlet namespace
• Every module in the instance can access it via self.slothlet.env without reaching for the mutable global process.env
• Snapshot is Object.freeze()'d — mutation attempts throw in strict mode and are silently ignored in sloppy mode
• New env.include config option accepts a string[] allowlist to restrict which keys are captured; empty array, non-array values, and non-string entries all fall back to capturing the full snapshot
• Keys listed in include that do not exist in process.env at init time produce no placeholder in the snapshot
• Snapshot is captured on the first load() call and is never replaced on subsequent api.slothlet.reload() calls — always reflects the environment at instance creation time

✨ NEW — TypeScript declarations for env
• Add env?: SlothletEnvConfig to SlothletOptions and env: Readonly<Record<string, string | undefined>> to SlothletAPI in types/src/slothlet.d.mts
• Update constructor JSDoc across all internal type declaration files

🐛 BUG FIX — NON-STRING include ENTRIES NOT FILTERED BEFORE ALLOWLIST CHECK
• _captureEnvSnapshot() received raw config.env before normalizeEnv() had filtered it, so an include array of only non-string entries produced an empty {} instead of falling back to the full snapshot
• Fix: apply the same typeof === 'string' filter inside _captureEnvSnapshot() and only activate the allowlist path when the filtered list is non-empty

🐛 BUG FIX — __proto__ ENV KEY SILENTLY DISCARDED WHEN USING include
• Using {} as the reduce accumulator caused acc["__proto__"] = value to invoke the __proto__ setter on Object.prototype, silently discarding the value for any env variable literally named __proto__
• Fix: switch accumulator to Object.create(null) so __proto__ is stored as an own data property; spread path ({ ...process.env }) was already unaffected

🐛 BUG FIX — POSIX C LOCALE TRIGGERS UNKNOWN-LANGUAGE WARNING
• On Linux CI systems LANG=C (POSIX C locale) caused setLanguage('c') to be called with no matching language file, emitting a noisy console.warn on every test that imported the i18n module
• Fix: add 'c' and 'posix' to the explicit locale→language map so both resolve to 'en-us'

🔧 FIX — CI VERSION BUMP DELETED src/
• The CI version-bump workflow ran build:ci (which ends with ci:cleanup-src) before committing, sweeping the entire src/ directory into the bump commit
• Fix: restore all 48 src/ files from the feature commit; version corrected from 3.0.1 to 3.1.0

Technical Implementation:

• src/slothlet.mjs: this.envSnapshot = null in constructor; _captureEnvSnapshot(envConfig) uses Object.create(null) accumulator, inline typeof === 'string' filter, and Object.freeze(); load() guard ensures single capture
• src/lib/helpers/config.mjs: normalizeEnv(env) returns { include: string[] } for valid non-empty string arrays, null otherwise; included in transformConfig() return value
• src/lib/builders/api_builder.mjs: env: slothlet.envSnapshot added to createSlothletNamespace()
• src/lib/i18n/translations.mjs: 'c' and 'posix' mapped to 'en-us' in locale detection
• types/src/slothlet.d.mts: SlothletEnvConfig interface and env on SlothletOptions / SlothletAPI; constructor JSDoc updated across 14 internal declaration files

Testing Coverage:
21 tests in tests/vitests/suites/core/env-snapshot.test.vitest.mjs covering: snapshot presence and shape, frozen status, full snapshot content, include allowlist (9 sub-cases: valid list, empty array, non-array, non-string entries, all-non-string fallback, __proto__ key regression, nonexistent keys, mixed entries), reload immutability, and all four mode×runtime matrix combinations (eager/lazy × async/live).

Files Changed: 39 files — 862 insertions, 32 deletions

src/slothlet.mjs                                       |  59 ++-
src/lib/builders/api_builder.mjs                       |  35 ++-
src/lib/helpers/config.mjs                             |  44 ++-
src/lib/i18n/translations.mjs                          |   2 +
tests/vitests/suites/core/env-snapshot.test.vitest.mjs | 301 +++ (new)
types/src/slothlet.d.mts                               |  10 ++-
types/src/lib/helpers/config.d.mts                     |  33 +++ (new)
types/src/lib/builders/api_builder.d.mts               |   9 ++-
types/src/lib/builders/api-assignment.d.mts            |   9 ++-
types/src/lib/builders/builder.d.mts                   |  12 ++-
types/src/lib/builders/modes-processor.d.mts           |   6 ++-
types/src/lib/handlers/api-cache-manager.d.mts         |   6 ++-
types/src/lib/handlers/api-manager.d.mts               |  13 ++-
types/src/lib/handlers/hook-manager.d.mts              |   5 ++-
types/src/lib/handlers/lifecycle.d.mts                 |   4 ++-
types/src/lib/handlers/materialize-manager.d.mts       |   6 ++-
types/src/lib/handlers/metadata.d.mts                  |   5 ++-
types/src/lib/modes/eager.d.mts                        |   6 ++-
types/src/lib/modes/lazy.d.mts                         |   6 ++-
types/src/lib/processors/flatten.d.mts                 |   5 ++-
[*.map files — 14 updated]
package.json                                           |   2 +-
docs/changelog/v3/v3.1.0.md                            | 164 +++ (new)
docs/changelog/v3/v3.0.1.md                            |  99 +++ (new)
README.md                                              |  23 +--

Full Changelog: v3.0.1...v3.1.0

👥 Contributors

• @Shinrai