v3.0.0

[Sv443]

Major Changes:

• Add TieredCache class for a highly configurable cache based on DataStoreEngine instances (closes Tiered cache class #1)
• Make NanoUtils' multi methods' oneOf and allOf behave like an AND condition instead of an OR

Minor Changes:

• Add DataStore prop inMemoryCache to turn off the memory cache in data-intensive, non-latency-sensitive scenarios
• Add DataStoreSerializer property remapIds to support deserializing from stores with outdated IDs

Patch Changes:

• Make secsToTimeStr() support negative time and only throw if the number is NaN or not finite
• Implement Error classes DatedError, CustomError and new subclasses ScriptContextError and NetworkError throughout the library

[coveralls]

Pull Request Test Coverage Report for Build 21602974111

Details

• 88 of 94 (93.62%) changed or added relevant lines in 8 files are covered.
• 3 unchanged lines in 1 file lost coverage.
• Overall coverage decreased (-0.3%) to 95.026%

---

Changes Missing Coverage	Covered Lines	Changed/Added Lines	%
lib/DataStore.ts	18	20	90.0%
lib/DataStoreSerializer.ts	5	9	55.56%

Files with Coverage Reduction	New Missed Lines	%
lib/DataStoreEngine.ts	3	92.49%

Totals
Change from base Build 21601729307:	-0.3%
Covered Lines:	1139
Relevant Lines:	1163

---

💛 - Coveralls

[Copilot]

Pull request overview

This PR prepares the v3.0.0 release of the core library by refining the error model, enhancing the DataStore / DataStoreSerializer APIs, adjusting NanoEmitter multi-event semantics, and updating utilities, tests, and documentation accordingly.

Changes:

• Introduces a richer error hierarchy (DatedError, CustomError, ScriptContextError, NetworkError) and wires these through networking, storage, and serializer code, plus updated tests.
• Extends DataStore/DataStoreEngine/DataStoreSerializer with memoryCache, remapIds, stronger cloning/encoding semantics, and supporting tests & docs, including a new getCallStack() helper and improved secsToTimeStr() behavior (supports negatives, validates NaN/Infinity).
• Updates NanoEmitter.onMulti to treat oneOf and allOf as an AND condition, modernizes once() to return a Promise, reorganizes tests under lib/test, and tightens Vitest/TS configuration and project-wide documentation/instructions.

Reviewed changes

Copilot reviewed 35 out of 35 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
vitest.config.ts	Excludes lib/test/*.ts and some library entrypoints from coverage, keeping metrics focused on production code.
tsconfig.spec.json	Broadens the spec TS config to pick up all **/*.spec.ts and **/test/*.ts (though currently misusing files for globs).
lib/types.ts	Documents LooseUnion with a concrete example to clarify allowed values and type behavior.
lib/text.ts	Reworks secsToTimeStr() to support negative values, reject NaN/Infinity, and adjust zero-padding logic; keeps API surface the same.
lib/test/text.spec.ts	Points imports to ../text.ts, updates descriptions, and expands secsToTimeStr() tests for negative inputs and invalid-number errors.
lib/test/softExpect.ts	Adds a softExpect wrapper around Vitest’s expect() intended to log instead of throwing on soft assertions.
lib/test/misc.spec.ts	Adjusts imports to new paths, renames tests for clarity, uses softExpect for timing fuzziness, adds scheduleExit tests for Node/Deno/ScriptContextError, and adds comprehensive tests for getCallStack().
lib/test/math.spec.ts	Updates imports and extends tests for valsWithin() to match the new default decimal precision and edge-case handling.
lib/test/crypto.spec.ts	Points imports to ../crypto.ts to align with new test directory layout.
lib/test/colors.spec.ts	Updates imports for color helpers to ../colors.ts.
lib/test/array.spec.ts	Updates imports for array helpers to ../array.ts.
lib/test/NanoEmitter.spec.ts	Updates imports and extends tests to cover new onMulti AND semantics and once()’s Promise-based API.
lib/test/Errors.spec.ts	Replaces the old test file (moved from lib/Errors.spec.ts) and expands coverage to the new error types, verifying date, name, cause, and timestamp proximity using valsWithin().
lib/test/DirectAccessDataStore.ts	Adds a DataStore test subclass exposing internal engine and cache operations (direct_* helpers) to support more rigorous DataStore tests.
lib/test/Debouncer.spec.ts	Updates imports, uses pauseFor from the main misc module, and exercises Debouncer behavior including new once() semantics that now return a Promise.
lib/test/DataStoreSerializer.spec.ts	Updates imports and adds a “Migrates store IDs on deserialization” test scaffold to exercise the new remapIds option, though it currently only calls loadStoresData() without verifying remapping.
lib/test/DataStoreEngine.spec.ts	Points imports to the main engine, errors, and test DataStore helper, validating file engine behavior under the new error types.
lib/test/DataStore.spec.ts	Refactors to use DirectAccessDataStore, adds tests for migrating from UserUtils v9 format, invalid persistent data handling, and behavior when memoryCache is disabled.
lib/misc.ts	Switches fetchAdvanced to throw NetworkError, pauseFor to throw CustomError("AbortError", ...), scheduleExit to throw ScriptContextError, and adds a new getCallStack() helper with configurable format and line limit.
lib/math.ts	Changes valsWithin() to default to 1 decimal place and documents the behavior more precisely.
lib/TieredCache.ts	Replaces generic Error throws in the lyrics URL cache example with NetworkError to align with the new error hierarchy.
lib/NanoEmitter.ts	Documents and implements onMulti’s oneOf/allOf as AND semantics, adds validation for empty event sets, updates JSDoc on once() and onMulti(), and changes once() to return a Promise of emitted args while still supporting an optional callback.
lib/Errors.ts	Introduces CustomError, ScriptContextError, and NetworkError, and documents that all custom error classes extend DatedError.
lib/Errors.spec.ts	Removed in favor of the new, more comprehensive lib/test/Errors.spec.ts.
lib/DataStoreSerializer.ts	Extends options with remapIds, uses ScriptContextError when crypto APIs are absent, tightens error messaging by throwing DatedError for missing store IDs, and wires remapIds into deserializePartial.
lib/DataStoreEngine.ts	Enhances docs, uses DatedError/ScriptContextError for option and environment issues, clarifies serialization/encoding behavior, and improves FileStorageEngine to throw richer errors and return from deleteStorage().
lib/DataStore.ts	Adds EncodeTuple/DecodeTuple types, introduces the memoryCache option and behavior (including getData() throwing when disabled), uses deepCopy() instead of spread cloning, and updates migration/storage flows accordingly.
docs.md	Broad documentation refresh: adds sections for CustomError, ScriptContextError, NetworkError, getCallStack(), updates DataStore/DataStoreSerializer/NanoEmitter docs (including memoryCache, remapIds, and Promise-based once()), and corrects several descriptions, with a minor API name typo for JSON.stringify().
README.md	Syncs the public API overview with docs by adding CustomError, changing the const legend icon, and pointing to updated sections.
.github/instructions/base.instructions.md	Introduces project-wide contributor instructions for style, language support, comments, tests, documentation, and TS import/annotation conventions.
.changeset/soft-tigers-teach.md	Marks a major change clarifying that NanoEmitter ("NanoUtils") multi methods’ oneOf and allOf now act as an AND condition.
.changeset/rude-cars-wonder.md	Notes the rollout of DatedError, CustomError, ScriptContextError, and NetworkError throughout the library.
.changeset/pink-groups-sniff.md	Documents the secsToTimeStr() behavioral change to support negative times and validate only NaN/non-finite values.
.changeset/forty-animals-help.md	Announces the new DataStore memory-cache control, but currently refers to it as inMemoryCache instead of the implemented memoryCache.
.changeset/crazy-moose-wonder.md	Announces the new remapIds option on DataStoreSerializer for deserializing from legacy store IDs.

Comments suppressed due to low confidence (2)

lib/test/misc.spec.ts:201

• There are several new // @ts-ignore directives here, but the project instructions in .github/instructions/base.instructions.md explicitly state to never use @ts-ignore and to use @ts-expect-error only when absolutely necessary. Please replace these with narrowly-scoped @ts-expect-error (with a short justification) or adjust the typings so the ignores are not needed.
  lib/test/DataStoreSerializer.spec.ts:132
• The test "Migrates store IDs on deserialization" never calls deserialize/deserializePartial and does not assert anything about ID remapping, so the new remapIds behavior in DataStoreSerializer is effectively untested. To properly cover this feature, the test should deserialize data containing an old store ID and assert that it is applied to the new ID as configured in remapIds (and optionally that the original ID is no longer used).

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 35 out of 35 changed files in this pull request and generated 1 comment.

Comments suppressed due to low confidence (4)

lib/DataStore.ts:358

• This JSDoc still states that the in-memory cache remains usable via getData() after deleteData(), but with the new memoryCache option (and getData() throwing when it is disabled), this is no longer guaranteed. It would be more accurate to clarify that getData() is only usable here when memoryCache is enabled for this instance.

  /**
   * Call this method to clear all persistently stored data associated with this DataStore instance, including the storage container (if supported by the DataStoreEngine).  
   * The in-memory cache will be left untouched, so you may still access the data with {@linkcode getData()}  
   * Calling {@linkcode loadData()} or {@linkcode setData()} after this method was called will recreate persistent storage with the cached or default data.

lib/test/misc.spec.ts:178

• The use of // @ts-ignore here goes against the new project instructions in .github/instructions/base.instructions.md, which ask to avoid @ts-ignore and prefer @ts-expect-error only when absolutely necessary. Consider either tightening the typings (e.g. via a narrowed type or casting through unknown/any) or, if the suppression is unavoidable, switching this to a documented @ts-expect-error with a short justification.
  lib/test/misc.spec.ts:201
• These // @ts-ignore directives conflict with the repository instructions in .github/instructions/base.instructions.md, which discourage @ts-ignore in favor of @ts-expect-error only when strictly required. It would be better either to adjust the typing of globalThis.Deno / globalThis.process.exit for the test (e.g. via a narrowed helper or cast) or replace these with targeted @ts-expect-error comments that explain why the error is expected.
  lib/test/misc.spec.ts:212
• This additional // @ts-ignore also violates the project guideline to avoid @ts-ignore in favor of explicit typing or, where necessary, @ts-expect-error. For consistency with the rest of the codebase and .github/instructions/base.instructions.md, please either model the temporary globalThis.process state in the test types or convert this to a documented @ts-expect-error.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.