@sv443-network/coreutils 2.0.3 → 3.0.1

package/dist/lib/DataStore.d.ts

@@ -3,11 +3,15 @@
  * This module contains the DataStore class, which is a general purpose, sync and async persistent database for JSON-serializable data - [see the documentation for more info](https://github.com/Sv443-Network/CoreUtils/blob/main/docs.md#class-datastore)  
  */
 import type { DataStoreEngine } from "./DataStoreEngine.ts";
-import type { LooseUnion, Prettify, SerializableVal } from "./types.ts";
+import type { LooseUnion, Prettify } from "./types.ts";
 /** Function that takes the data in the old format and returns the data in the new format. Also supports an asynchronous migration. */
 type MigrationFunc = (oldData: any) => any | Promise<any>;
 /** Dictionary of format version numbers and the function that migrates to them from the previous whole integer */
 export type DataMigrationsDict = Record<number, MigrationFunc>;
+/** Tuple of a compression format identifier and a function to use to encode the data */
+export type EncodeTuple = [format: LooseUnion<CompressionFormat> | null, encode: (data: string) => string | Promise<string>];
+/** Tuple of a compression format identifier and a function to use to decode the data */
+export type DecodeTuple = [format: LooseUnion<CompressionFormat> | null, decode: (data: string) => string | Promise<string>];
 /** Options for the DataStore instance */
 export type DataStoreOptions<TData extends DataStoreData> = Prettify<{
     /**
@@ -36,7 +40,7 @@ export type DataStoreOptions<TData extends DataStoreData> = Prettify<{
      *  
      * - ⚠️ Don't reuse the same engine instance for multiple DataStores, unless it explicitly supports it!  
      */
-    engine: (() => DataStoreEngine<TData>) | DataStoreEngine<TData>;
+    engine: (() => DataStoreEngine) | DataStoreEngine;
     /**
      * A dictionary of functions that can be used to migrate data from older versions to newer ones.  
      * The keys of the dictionary should be the format version that the functions can migrate to, from the previous whole integer value.  
@@ -52,12 +56,19 @@ export type DataStoreOptions<TData extends DataStoreData> = Prettify<{
      * To migrate IDs manually, use the method {@linkcode DataStore.migrateId()} instead.  
      */
     migrateIds?: string | string[];
+    /**
+     * Whether to keep a copy of the data in memory for synchronous read access. Defaults to `true`.  
+     *  
+     * - ⚠️ If turned off, {@linkcode DataStore.getData()} will throw an error and only {@linkcode DataStore.loadData()} can be used to access the data.  
+     *   This may be useful if multiple sources are modifying the data, or the data is very large and you want to save memory, but it will make accessing the data slower, especially when combined with compression.  
+     */
+    memoryCache?: boolean;
 } & ({
     encodeData?: never;
     decodeData?: never;
     /**
      * The format to use for compressing the data. Defaults to `deflate-raw`. Explicitly set to `null` to store data uncompressed.  
-     * - ⚠️ Use either this property, or both `encodeData` and `decodeData`, but not all three!  
+     * - ⚠️ Use either this property, or both `encodeData` and `decodeData`, but not a combination of the three!  
      */
     compressionFormat?: CompressionFormat | null;
 } | {
@@ -70,7 +81,7 @@ export type DataStoreOptions<TData extends DataStoreData> = Prettify<{
      * You can make use of the [`compress()` function](https://github.com/Sv443-Network/CoreUtils/blob/main/docs.md#function-compress) here to make the data use up less space at the cost of a little bit of performance.  
      * @param data The input data as a serialized object (JSON string)  
      */
-    encodeData: [format: LooseUnion<CompressionFormat> | null, encode: (data: string) => string | Promise<string>];
+    encodeData: EncodeTuple;
     /**
      * Tuple of a compression format identifier and a function to use to decode the data after reading it from persistent storage.  
      * Set the identifier to `null` or `"identity"` to indicate that no traditional compression is used.  
@@ -80,11 +91,15 @@ export type DataStoreOptions<TData extends DataStoreData> = Prettify<{
      * You can make use of the [`decompress()` function](https://github.com/Sv443-Network/CoreUtils/blob/main/docs.md#function-decompress) here to make the data use up less space at the cost of a little bit of performance.  
      * @returns The resulting data as a valid serialized object (JSON string)  
      */
-    decodeData: [format: LooseUnion<CompressionFormat> | null, decode: (data: string) => string | Promise<string>];
+    decodeData: DecodeTuple;
     compressionFormat?: never;
 })>;
-/** Generic type that represents the serializable data structure saved in a {@linkcode DataStore} instance. */
-export type DataStoreData<TData extends SerializableVal = SerializableVal> = Record<string, SerializableVal | TData>;
+/**
+ * Generic type that represents the serializable data structure saved in a {@linkcode DataStore} instance.  
+ * - ⚠️ Uses `object` instead of an index signature so that interfaces without an explicit index signature can be used as `TData`.  
+ *   Make sure to only use JSON-serializable types here, otherwise unexpected behavior may occur!  
+ */
+export type DataStoreData = object;
 /**
  * Manages a hybrid synchronous & asynchronous persistent JSON database that is cached in memory and persistently saved across sessions using one of the preset DataStoreEngines or your own one.  
  * Supports migrating data from older format versions to newer ones and populating the cache with default data if no persistent data is found.  
@@ -96,7 +111,8 @@ export type DataStoreData<TData extends SerializableVal = SerializableVal> = Rec
  * - ⚠️ The data is stored as a JSON string, so only data compatible with [`JSON.stringify()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify) can be used. Circular structures and complex objects (containing functions, symbols, etc.) will either throw an error on load and save or cause otherwise unexpected behavior. Properties with a value of `undefined` will be removed from the data prior to saving it, so use `null` instead.  
  * - ⚠️ Make sure to call {@linkcode loadData()} at least once after creating an instance, or the returned data will be the same as `options.defaultData`  
  *  
- * @template TData The type of the data that is saved in persistent storage for the currently set format version (FIXME:will be automatically inferred from `defaultData` if not provided)  
+ * @template TData The type of the data that is saved in persistent storage for the currently set format version  
+ * (TODO:FIXME: will be automatically inferred from `defaultData` if not provided)  
  */
 export declare class DataStore<TData extends DataStoreData> {
     readonly id: string;
@@ -105,7 +121,8 @@ export declare class DataStore<TData extends DataStoreData> {
     readonly encodeData: DataStoreOptions<TData>["encodeData"];
     readonly decodeData: DataStoreOptions<TData>["decodeData"];
     readonly compressionFormat: Exclude<DataStoreOptions<TData>["compressionFormat"], undefined>;
-    readonly engine: DataStoreEngine<TData>;
+    readonly memoryCache: boolean;
+    readonly engine: DataStoreEngine;
     options: DataStoreOptions<TData>;
     /**
      * Whether all first-init checks should be done.  
@@ -114,9 +131,9 @@ export declare class DataStore<TData extends DataStoreData> {
      */
     protected firstInit: boolean;
     /** In-memory cached copy of the data that is saved in persistent storage used for synchronous read access. */
-    private cachedData;
-    private migrations?;
-    private migrateIds;
+    protected cachedData: TData;
+    protected migrations?: DataMigrationsDict;
+    protected migrateIds: string[];
     /**
      * Creates an instance of DataStore to manage a sync & async database that is cached in memory and persistently saved across sessions.  
      * Supports migrating data from older versions to newer ones and populating the cache with default data if no persistent data is found.  
@@ -136,6 +153,7 @@ export declare class DataStore<TData extends DataStoreData> {
     /**
      * Returns a copy of the data from the in-memory cache.  
      * Use {@linkcode loadData()} to get fresh data from persistent storage (usually not necessary since the cache should always exactly reflect persistent storage).  
+     * ⚠️ If `memoryCache` was set to `false` in the constructor options, this method will throw an error.  
      */
     getData(): TData;
     /** Saves the data synchronously to the in-memory cache and asynchronously to the persistent storage */

package/dist/lib/DataStoreEngine.d.ts

@@ -6,16 +6,16 @@
 import type { DataStoreData, DataStoreOptions } from "./DataStore.ts";
 import type { Prettify, SerializableVal } from "./types.ts";
 /** Contains the only properties of {@linkcode DataStoreOptions} that are relevant to the {@linkcode DataStoreEngine} class. */
-export type DataStoreEngineDSOptions<TData extends DataStoreData> = Prettify<Pick<DataStoreOptions<TData>, "decodeData" | "encodeData" | "id">>;
-export interface DataStoreEngine<TData extends DataStoreData> {
+export type DataStoreEngineDSOptions<TData extends DataStoreData = DataStoreData> = Prettify<Pick<DataStoreOptions<TData>, "decodeData" | "encodeData" | "id">>;
+export interface DataStoreEngine<TData extends DataStoreData = DataStoreData> {
     /** Deletes all data in persistent storage, including the data container itself (e.g. a file or a database) */
     deleteStorage?(): Promise<void>;
 }
 /**
  * Base class for creating {@linkcode DataStore} storage engines.  
- * This acts as an interchangeable API for writing and reading persistent data in various environments.  
+ * This acts as an interchangeable API for writing and reading persistent JSON-serializable data in various environments.  
  */
-export declare abstract class DataStoreEngine<TData extends DataStoreData> {
+export declare abstract class DataStoreEngine<TData extends DataStoreData = DataStoreData> {
     protected dataStoreOptions: DataStoreEngineDSOptions<TData>;
     constructor(options?: DataStoreEngineDSOptions<TData>);
     /** Called by DataStore on creation, to pass its options. Only call this if you are using this instance standalone! */
@@ -26,7 +26,7 @@ export declare abstract class DataStoreEngine<TData extends DataStoreData> {
     abstract setValue(name: string, value: SerializableVal): Promise<void>;
     /** Deletes a value from persistent storage */
     abstract deleteValue(name: string): Promise<void>;
-    /** Serializes the given object to a string, optionally encoded with `options.encodeData` if {@linkcode useEncoding} is set to true */
+    /** Serializes the given object to a string, optionally encoded with `options.encodeData` if {@linkcode useEncoding} is not set to false and the `encodeData` and `decodeData` options are set */
     serializeData(data: TData, useEncoding?: boolean): Promise<string>;
     /** Deserializes the given string to a JSON object, optionally decoded with `options.decodeData` if {@linkcode useEncoding} is set to true */
     deserializeData(data: string, useEncoding?: boolean): Promise<TData>;
@@ -49,18 +49,18 @@ export type BrowserStorageEngineOptions = {
     dataStoreOptions?: DataStoreEngineDSOptions<DataStoreData>;
 };
 /**
- * Storage engine for the {@linkcode DataStore} class that uses the browser's LocalStorage or SessionStorage to store data.  
+ * Storage engine for the {@linkcode DataStore} class that uses the browser's LocalStorage or SessionStorage to store JSON-serializable data.  
  *  
  * - ⚠️ Requires a DOM environment  
- * - ⚠️ Don't reuse engines across multiple {@linkcode DataStore} instances  
+ * - ⚠️ Don't reuse engine instances, always create a new one for each {@linkcode DataStore} instance  
  */
-export declare class BrowserStorageEngine<TData extends DataStoreData> extends DataStoreEngine<TData> {
+export declare class BrowserStorageEngine<TData extends DataStoreData = DataStoreData> extends DataStoreEngine<TData> {
     protected options: BrowserStorageEngineOptions & Required<Pick<BrowserStorageEngineOptions, "type">>;
     /**
      * Creates an instance of `BrowserStorageEngine`.  
      *  
      * - ⚠️ Requires a DOM environment  
-     * - ⚠️ Don't reuse engines across multiple {@linkcode DataStore} instances  
+     * - ⚠️ Don't reuse engine instances, always create a new one for each {@linkcode DataStore} instance  
      */
     constructor(options?: BrowserStorageEngineOptions);
     /** Fetches a value from persistent storage */
@@ -81,19 +81,19 @@ export type FileStorageEngineOptions = {
     dataStoreOptions?: DataStoreEngineDSOptions<DataStoreData>;
 };
 /**
- * Storage engine for the {@linkcode DataStore} class that uses a JSON file to store data.  
+ * Storage engine for the {@linkcode DataStore} class that uses a JSON file to store JSON-serializable data.  
  *  
  * - ⚠️ Requires Node.js or Deno with Node compatibility (v1.31+)  
- * - ⚠️ Don't reuse engines across multiple {@linkcode DataStore} instances  
+ * - ⚠️ Don't reuse engine instances, always create a new one for each {@linkcode DataStore} instance  
  */
-export declare class FileStorageEngine<TData extends DataStoreData> extends DataStoreEngine<TData> {
+export declare class FileStorageEngine<TData extends DataStoreData = DataStoreData> extends DataStoreEngine<TData> {
     protected options: FileStorageEngineOptions & Required<Pick<FileStorageEngineOptions, "filePath">>;
     private fileAccessQueue;
     /**
      * Creates an instance of `FileStorageEngine`.  
      *  
      * - ⚠️ Requires Node.js or Deno with Node compatibility (v1.31+)  
-     * - ⚠️ Don't reuse engines across multiple {@linkcode DataStore} instances  
+     * - ⚠️ Don't reuse engine instances, always create a new one for each {@linkcode DataStore} instance  
      */
     constructor(options?: FileStorageEngineOptions);
     /** Reads the file contents */

package/dist/lib/DataStoreSerializer.d.ts

@@ -9,6 +9,8 @@ export type DataStoreSerializerOptions = {
     addChecksum?: boolean;
     /** Whether to ensure the integrity of the data when importing it by throwing an error (doesn't throw when the checksum property doesn't exist). Defaults to `true` */
     ensureIntegrity?: boolean;
+    /** If provided, all stores with an ID in the value's array will be remapped to the key's ID when deserialization is called. If they don't match a DataStore instance's ID, nothing will happen. */
+    remapIds?: Record<string, string[]>;
 };
 /** Meta object and serialized data of a DataStore instance */
 export type SerializedDataStore = {

package/dist/lib/Errors.d.ts

@@ -7,15 +7,27 @@ export declare class DatedError extends Error {
     readonly date: Date;
     constructor(message: string, options?: ErrorOptions);
 }
-/** Error while validating checksum */
+/** Error while validating checksum - extends {@linkcode DatedError} */
 export declare class ChecksumMismatchError extends DatedError {
     constructor(message: string, options?: ErrorOptions);
 }
-/** Error while migrating data */
+/** Custom error class that can have a custom name - extends {@linkcode DatedError} */
+export declare class CustomError extends DatedError {
+    constructor(name: string, message: string, options?: ErrorOptions);
+}
+/** Error while migrating data - extends {@linkcode DatedError} */
 export declare class MigrationError extends DatedError {
     constructor(message: string, options?: ErrorOptions);
 }
-/** Error while validating data */
+/** Error while validating data - extends {@linkcode DatedError} */
 export declare class ValidationError extends DatedError {
     constructor(message: string, options?: ErrorOptions);
 }
+/** Error related to script context (e.g. trying to access APIs that aren't supported by the executing JS engine) - extends {@linkcode DatedError} */
+export declare class ScriptContextError extends DatedError {
+    constructor(message: string, options?: ErrorOptions);
+}
+/** Error related to networking - extends {@linkcode DatedError} */
+export declare class NetworkError extends DatedError {
+    constructor(message: string, options?: ErrorOptions);
+}

package/dist/lib/NanoEmitter.d.ts

@@ -9,16 +9,16 @@ export interface NanoEmitterOptions {
     publicEmit: boolean;
 }
 type NanoEmitterOnMultiTriggerOptions<TEvtMap extends EventsMap, TKey extends keyof TEvtMap = keyof TEvtMap> = {
-    /** Calls the callback when one of the given events is emitted */
+    /** Calls the callback when one of the given events is emitted. Either one of or both of `oneOf` and `allOf` need to be set. If both are set, they behave like an "AND" condition. */
     oneOf?: TKey[];
-    /** Calls the callback when all of the given events are emitted */
+    /** Calls the callback when all of the given events are emitted. Either one of or both of `oneOf` and `allOf` need to be set. If both are set, they behave like an "AND" condition. */
     allOf?: TKey[];
 };
 /** Options for the {@linkcode NanoEmitter.onMulti()} method */
 export type NanoEmitterOnMultiOptions<TEvtMap extends EventsMap, TKey extends keyof TEvtMap = keyof TEvtMap> = Prettify<{
     /** If true, the callback will be called only once for the first event (or set of events) that match the criteria */
     once?: boolean;
-    /** If provided, can be used to abort the subscription if the signal is aborted */
+    /** If provided, can be used to cancel the subscription if the signal is aborted */
     signal?: AbortSignal;
     /** The callback to call when the event with the given name is emitted */
     callback: (event: TKey, ...args: Parameters<TEvtMap[TKey]>) => void;
@@ -80,11 +80,12 @@ export declare class NanoEmitter<TEvtMap extends EventsMap = DefaultEvents> {
      * `callback` (required) is the function that will be called when the conditions are met.  
      *  
      * Set `once` to true to call the callback only once for the first event (or set of events) that match the criteria, then stop listening.  
-     * If `signal` is provided, the subscription will be aborted when the given signal is aborted.  
+     * If `signal` is provided, the subscription will be canceled when the given signal is aborted.  
      *  
      * If `oneOf` is used, the callback will be called when any of the matching events are emitted.  
      * If `allOf` is used, the callback will be called after all of the matching events are emitted at least once, then any time any of them are emitted.  
-     * You may use a combination of the above two options, but at least one of them must be provided.  
+     * If both `oneOf` and `allOf` are used together, the callback will be called when any of the `oneOf` events are emitted AND all of the `allOf` events have been emitted at least once.  
+     * At least one of `oneOf` or `allOf` must be provided.  
      *  
      * @returns Returns a function that can be called to unsubscribe all listeners created by this call. Alternatively, pass an `AbortSignal` to all options objects to achieve the same effect or for finer control.  
      */

package/dist/lib/math.d.ts

@@ -61,5 +61,5 @@ export declare function randRange(max: number, enhancedEntropy?: boolean): numbe
  * ```  
  */
 export declare function roundFixed(num: number, fractionDigits: number): number;
-/** Rounds the given values at the given decimal place (same as in {@linkcode roundFixed()}) and checks if they are within the given range (0.5 by default) */
+/** Rounds the given values at the given decimal place (same as in {@linkcode roundFixed()}, 1 decimal place by default) and checks if they are within the given range (0.5 by default) */
 export declare function valsWithin(a: number, b: number, dec?: number, withinRange?: number): boolean;

package/dist/lib/misc.d.ts

@@ -71,3 +71,9 @@ export declare function setImmediateTimeoutLoop(callback: () => void | unknown |
  * @throws An error if no exit method is available (e.g. in browser environments)  
  */
 export declare function scheduleExit(code?: number, timeout?: number): void;
+/**
+ * Returns the current call stack, starting at the caller of this function.  
+ * @param asArray Whether to return the stack as an array of strings or a single string. Defaults to true.  
+ * @param lines The number of lines to return from the stack. Defaults to Infinity (all of them).  
+ */
+export declare function getCallStack<TAsArray extends boolean = true>(asArray?: TAsArray, lines?: number): TAsArray extends true ? string[] : string;

package/dist/lib/{TestDataStore.d.ts → test/DirectAccessDataStore.d.ts}

@@ -1,12 +1,13 @@
-import { DataStore, type DataStoreData } from "./DataStore.ts";
-import type { SerializableVal } from "./types.ts";
+import { DataStore, type DataStoreData } from "../DataStore.ts";
+import type { SerializableVal } from "../types.ts";
 /**
  * A DataStore wrapper subclass that exposes internal methods for testing via the `direct_` prefixed methods.  
  */
-export declare class TestDataStore<TData extends DataStoreData> extends DataStore<TData> {
+export declare class DirectAccessDataStore<TData extends DataStoreData> extends DataStore<TData> {
     direct_getValue<TValue extends SerializableVal = string>(name: string, defaultValue: TValue): Promise<string | TValue>;
     direct_setValue(name: string, value: SerializableVal): Promise<void>;
     direct_renameKey(oldName: string, newName: string): Promise<void>;
     direct_deleteValue(name: string): Promise<void>;
     direct_setFirstInit(value: boolean): void;
+    direct_getMemData(): TData;
 }

package/dist/lib/test/softExpect.d.ts

@@ -0,0 +1,11 @@
+import { type Assertion } from "vitest";
+/**
+ * Run an assertion in "soft" mode: catch assertion errors and log them instead of throwing.  
+ *  
+ * @example ```ts  
+ * softExpect(() => expect(actual).toBe(42));  
+ * softExpect(actual, e => e.toBe(42), "optional message");  
+ * ```  
+ */
+export declare function softExpect(assertion: () => void | unknown): void;
+export declare function softExpect<T>(actual: T, assertion: (expectation: Assertion<T>) => void | unknown, message?: string): void;

package/dist/lib/types.d.ts

@@ -13,6 +13,13 @@ export type ListLike = unknown[] | {
 /**
  * A type that offers autocomplete for the passed union but also allows any arbitrary value of the same type to be passed.  
  * Supports unions of strings, numbers and objects.  
+ * @example ```ts  
+ * type MyUnion = LooseUnion<"foo" | "bar" | "baz">;  
+ *  
+ * const a: MyUnion = "foo"; // Valid  
+ * const b: MyUnion = "qux"; // Also valid, even though "qux" is not part of the union  
+ * const c: MyUnion = 123;   // Not valid, because it's not the same type  
+ * ```  
  */
 export type LooseUnion<TUnion extends string | number | object> = (TUnion) | (TUnion extends string ? (string & {}) : (TUnion extends number ? (number & {}) : (TUnion extends Record<keyof any, unknown> ? (object & {}) : never)));
 /** Any class reference that can be instantiated with `new` */

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sv443-network/coreutils",
   "libName": "@sv443-network/coreutils",
-  "version": "2.0.3",
+  "version": "3.0.1",
   "description": "Cross-platform, general-purpose, JavaScript core library for Node, Deno and the browser. Intended to be used in conjunction with `@sv443-network/userutils` and `@sv443-network/djsutils`, but can be used independently as well.",
   "main": "dist/CoreUtils.cjs",
   "module": "dist/CoreUtils.mjs",
@@ -76,6 +76,9 @@
     "/CHANGELOG.md",
     "/LICENSE.txt"
   ],
+  "publishConfig": {
+    "provenance": true
+  },
   "scripts": {
     "lint": "eslint . && tsc --noEmit",
     "format": "eslint . --fix",