@sv443-network/coreutils 3.5.1 → 3.6.0

package/dist/lib/DataStoreSerializer.d.ts

@@ -2,7 +2,7 @@
  * @module DataStoreSerializer  
  * This module contains the DataStoreSerializer class, which allows you to import and export serialized DataStore data - [see the documentation for more info](https://github.com/Sv443-Network/UserUtils/blob/main/docs.md#datastoreserializer)  
  */
-import type { DataStore } from "./DataStore.ts";
+import type { DataStore, DataStoreData } from "./DataStore.ts";
 /** Options for the DataStoreSerializer class */
 export type DataStoreSerializerOptions = {
     /** Whether to add a checksum to the exported data. Defaults to `true` */
@@ -11,13 +11,18 @@ export type DataStoreSerializerOptions = {
     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[]>;
+    /**
+     * Controls the type of the `data` property on {@linkcode SerializedDataStore} objects.  
+     * When this is set to `false`, `data` will be the raw data object instead of a string, regardless of whether {@linkcode DataStoreSerializer.serialize()} or {@linkcode DataStoreSerializer.serializePartial()} are called with their `stringify` / `stringified` parameter set to `true` or `false`.  
+     */
+    stringifyData?: boolean;
 };
 /** Meta object and serialized data of a DataStore instance */
-export type SerializedDataStore = {
+export type SerializedDataStore<TData extends string | DataStoreData = string> = {
     /** The ID of the DataStore instance */
     id: string;
     /** The serialized data */
-    data: string;
+    data: TData;
     /** The format version of the data */
     formatVersion: number;
     /** Whether the data is encoded */
@@ -48,10 +53,10 @@ export declare class DataStoreSerializer {
     protected options: Required<DataStoreSerializerOptions>;
     constructor(stores: DataStore<any, boolean>[], options?: DataStoreSerializerOptions);
     /**
-     * Calculates the checksum of a string. Uses {@linkcode computeHash()} with SHA-256 and digests as a hex string by default.  
+     * Calculates the checksum of a string or {@linkcode DataStoreData} object. Uses {@linkcode computeHash()} with SHA-256 and digests as a hex string by default.  
      * Override this in a subclass if a custom checksum method is needed.  
      */
-    protected calcChecksum(input: string): Promise<string>;
+    protected calcChecksum(input: string | DataStoreData): Promise<string>;
     /**
      * Serializes only a subset of the data stores into a string.  
      * @param stores An array of store IDs or functions that take a store ID and return a boolean  
@@ -65,14 +70,14 @@ export declare class DataStoreSerializer {
      * @param useEncoding Whether to encode the data using each DataStore's `encodeData()` method  
      * @param stringified Whether to return the result as a string or as an array of `SerializedDataStore` objects  
      */
-    serializePartial(stores: StoreFilter, useEncoding?: boolean, stringified?: false): Promise<SerializedDataStore[]>;
+    serializePartial(stores: StoreFilter, useEncoding?: boolean, stringified?: false): Promise<SerializedDataStore<string | DataStoreData>[]>;
     /**
      * Serializes only a subset of the data stores into a string.  
      * @param stores An array of store IDs or functions that take a store ID and return a boolean  
      * @param useEncoding Whether to encode the data using each DataStore's `encodeData()` method  
      * @param stringified Whether to return the result as a string or as an array of `SerializedDataStore` objects  
      */
-    serializePartial(stores: StoreFilter, useEncoding?: boolean, stringified?: boolean): Promise<string | SerializedDataStore[]>;
+    serializePartial(stores: StoreFilter, useEncoding?: boolean, stringified?: boolean): Promise<string | SerializedDataStore<string | DataStoreData>[]>;
     /**
      * Serializes the data stores into a string.  
      * @param useEncoding Whether to encode the data using each DataStore's `encodeData()` method  
@@ -84,7 +89,7 @@ export declare class DataStoreSerializer {
      * @param useEncoding Whether to encode the data using each DataStore's `encodeData()` method  
      * @param stringified Whether to return the result as a string or as an array of `SerializedDataStore` objects  
      */
-    serialize(useEncoding?: boolean, stringified?: false): Promise<SerializedDataStore[]>;
+    serialize(useEncoding?: boolean, stringified?: false): Promise<SerializedDataStore<string | DataStoreData>[]>;
     /**
      * Deserializes the data exported via {@linkcode serialize()} and imports only a subset into the DataStore instances.  
      * Also triggers the migration process if the data format has changed.  

package/dist/lib/NanoEmitter.d.ts

@@ -7,6 +7,13 @@ import type { Prettify } from "./types.ts";
 export interface NanoEmitterOptions {
     /** If set to true, allows emitting events through the public method emit() */
     publicEmit: boolean;
+    /**
+     * When provided, the emitter will remember the last arguments of each listed event.  
+     * Any listener attached via `on()` or `once()` after the event has already fired will  
+     * be immediately called / resolved with the cached arguments (catch-up behaviour).  
+     * Only works for emissions that go through the public `emit()` or the protected `emitEvent()` method.  
+     */
+    catchUpEvents?: PropertyKey[];
 }
 type NanoEmitterOnMultiTriggerOptions<TEvtMap extends EventsMap, TKey extends keyof TEvtMap = keyof TEvtMap> = {
     /** 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. */
@@ -25,14 +32,22 @@ export type NanoEmitterOnMultiOptions<TEvtMap extends EventsMap, TKey extends ke
 } & NanoEmitterOnMultiTriggerOptions<TEvtMap, TKey> & (Pick<Required<NanoEmitterOnMultiTriggerOptions<TEvtMap, TKey>>, "oneOf"> | Pick<Required<NanoEmitterOnMultiTriggerOptions<TEvtMap, TKey>>, "allOf">)>;
 /**
  * Class that can be extended or instantiated by itself to create a lightweight event emitter with helper methods and a strongly typed event map.  
- * If extended from, you can use `this.events.emit()` to emit events, even if the `emit()` method doesn't work because `publicEmit` is not set to true in the constructor.  
+ * If extended from, prefer using `this.emitEvent()` over `this.events.emit()` — it updates the catch-up memory for any events listed in `catchUpEvents`.  
  */
 export declare class NanoEmitter<TEvtMap extends EventsMap = DefaultEvents> {
     protected readonly events: Emitter<TEvtMap>;
     protected eventUnsubscribes: Unsubscribe[];
     protected emitterOptions: NanoEmitterOptions;
+    /** Stores the last arguments for each event listed in `catchUpEvents` */
+    protected catchUpMemory: Map<PropertyKey, unknown[]>;
     /** Creates a new instance of NanoEmitter - a lightweight event emitter with helper methods and a strongly typed event map */
     constructor(options?: Partial<NanoEmitterOptions>);
+    /**
+     * Emits an event on this instance, bypassing the `publicEmit` guard.  
+     * Prefer this over `this.events.emit()` in subclasses — it updates catch-up memory  
+     * for any event listed in `catchUpEvents` so late listeners can still receive the last value.  
+     */
+    protected emitEvent<TKey extends keyof TEvtMap>(event: TKey, ...args: Parameters<TEvtMap[TKey]>): void;
     /**
      * Subscribes to an event and calls the callback when it's emitted.  
      * @param event The event to subscribe to. Use `as "_"` in case your event names aren't thoroughly typed (like when using a template literal, e.g. \`event-${val}\` as "_")  

package/dist/lib/misc.d.ts

@@ -6,24 +6,32 @@ import type { ListLike, Prettify, Stringifiable } from "./types.ts";
 /**
  * A ValueGen value is either its type, a promise that resolves to its type, or a function that returns its type, either synchronous or asynchronous.  
  * ValueGen allows for the utmost flexibility when applied to any type, as long as {@linkcode consumeGen()} is used to get the final value.  
+ * The optional `TFn` parameter allows specifying the function variant's signature, enabling parametrized consumption via {@linkcode consumeGen()}.  
  * @template TValueType The type of the value that the ValueGen should yield  
+ * @template TFn The function signature for the function variant - defaults to a no-arg function for backwards compatibility  
  */
-export type ValueGen<TValueType> = TValueType | Promise<TValueType> | (() => TValueType | Promise<TValueType>);
+export type ValueGen<TValueType, TFn extends (...args: any[]) => TValueType | Promise<TValueType> = () => TValueType | Promise<TValueType>> = TValueType | Promise<TValueType> | TFn;
 /**
  * Turns a {@linkcode ValueGen} into its final value.  
+ * @param args Optional arguments forwarded to the function, if the ValueGen is a parametrized function  
  * @template TValueType The type of the value that the ValueGen should yield  
+ * @template TFn The function signature for the function variant - inferred automatically  
  */
-export declare function consumeGen<TValueType>(valGen: ValueGen<TValueType>): Promise<TValueType>;
+export declare function consumeGen<TValueType, TFn extends (...args: any[]) => TValueType | Promise<TValueType> = () => TValueType | Promise<TValueType>>(valGen: ValueGen<TValueType, TFn>, ...args: Parameters<TFn>): Promise<TValueType>;
 /**
  * A StringGen value is either a string, anything that can be converted to a string, or a function that returns one of the previous two, either synchronous or asynchronous, or a promise that returns a string.  
  * StringGen allows for the utmost flexibility when dealing with strings, as long as {@linkcode consumeStringGen()} is used to get the final string.  
+ * The optional `TFn` parameter allows specifying the function variant's signature, enabling parametrized consumption via {@linkcode consumeStringGen()}.  
+ * @template TFn The function signature for the function variant - defaults to a no-arg function for backwards compatibility  
  */
-export type StringGen = ValueGen<Stringifiable>;
+export type StringGen<TFn extends (...args: any[]) => Stringifiable | Promise<Stringifiable> = () => Stringifiable | Promise<Stringifiable>> = ValueGen<Stringifiable, TFn>;
 /**
  * Turns a {@linkcode StringGen} into its final string value.  
+ * @param args Optional arguments forwarded to the function, if the StringGen is a parametrized function  
  * @template TStrUnion The union of strings that the StringGen should yield - this allows for finer type control compared to {@linkcode consumeGen()}  
+ * @template TFn The function signature for the function variant - inferred automatically  
  */
-export declare function consumeStringGen<TStrUnion extends string>(strGen: StringGen): Promise<TStrUnion>;
+export declare function consumeStringGen<TStrUnion extends string, TFn extends (...args: any[]) => Stringifiable | Promise<Stringifiable> = () => Stringifiable | Promise<Stringifiable>>(strGen: StringGen<TFn>, ...args: Parameters<TFn>): Promise<TStrUnion>;
 /** Options for the `fetchAdvanced()` function */
 export type FetchAdvancedOpts = Prettify<Partial<{
     /** Timeout in milliseconds after which the fetch call will be canceled with an AbortController signal */
@@ -50,6 +58,11 @@ export declare function pauseFor(time: number, signal?: AbortSignal, rejectOnAbo
  * If no object is passed, it will return an empty object without prototype chain.  
  */
 export declare function pureObj<TObj extends object>(obj?: TObj): TObj;
+/**
+ * Transforms an object's enumerable, own, string-keyed properties into getters that return the original values.  
+ * Set `asCopy` to true to return a new object with the getterified properties instead of a live view of the original object.  
+ */
+export declare function getterifyObj<TObj extends object>(obj: TObj, asCopy?: boolean): TObj;
 /**
  * Works similarly to `setInterval()`, but the callback is also called immediately and can be aborted with an `AbortSignal`.  
  * Uses `setInterval()` internally, which might cause overlapping calls if the callback's synchronous execution takes longer than the given interval time.  

package/dist/lib/types.d.ts

@@ -35,7 +35,7 @@ export type NonEmptyString<TString extends string> = TString extends "" ? never
 /** String constant that decides which set of number formatting options to use */
 export type NumberFormat = "short" | "long";
 /**
- * Makes the structure of a type more readable by expanding it.  
+ * Makes the structure of a type more readable by expanding other types merged via intersections.  
  * This can be useful for debugging or for improving the readability of complex types.  
  */
 export type Prettify<T> = {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sv443-network/coreutils",
   "libName": "@sv443-network/coreutils",
-  "version": "3.5.1",
+  "version": "3.6.0",
   "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",