@sv443-network/coreutils 0.0.1 → 2.0.0

package/CHANGELOG.md

@@ -1,11 +1,40 @@
+# @sv443-network/coreutils
+
+## 2.0.0
+
+### Major Changes
+
+- 273fa5a: Removed the boolean property `__ds-${id}-enc` from the `DataStore` and `DataStoreEngine` classes.
+  Now the key `__ds-${id}-enf` will hold the encoding format identifier string, or `null` if not set (will get created on the next write call).
+  This will make it possible to switch the encoding format without compatibility issues.
+  This functionality is not officially supported yet, but can be achieved manually by calling the storage API methods of `storeInstance.engine`
+
+### Minor Changes
+
+- 29fb048: Added `overflowVal()` to conform a value to an over- & undeflowing range
+- 91cbe9c: Added optional abstract method `DataStoreEngine.deleteStorage()` for deleting the data storage container itself. If implemented in subclasses, it will be called from the method `DataStore.deleteData()`
+- 3cae1cb: Added `dataStoreOptions` constructor prop to the DataStoreEngine subclasses to enable them to be used standalone.
+- f6465b5: Added method `NanoEmitter.onMulti()` to listen to when multiple events have emitted, with fine grained options
+
+## 1.0.0
+
+This is the initial release of CoreUtils. Most features have been originally ported from [version 9.4.1 of `@sv443-network/userutils`](https://github.com/Sv443-Network/UserUtils/tree/v9.4.1)  
+Parts of the code have been overhauled, and some features have been added:
+
 - Additions:
-  - array:
-    - Added `takeRandomItemIndex()`
-- BREAKING CHANGES:
-  - Reworked DataStore
-    - Encoding with `deflate-raw` will now be enabled by default. Set `compressionFormat: null` to disable it.
-    - Added `DataStoreEngine` base class to create a persistent storage engine
-    - Added `FileStorageEngine` for file-based storage in the backend and `BrowserStorageEngine` for browser API based storage
-    - The global key `__ds_fmt_ver` will now contain a global version number for DataStore-internal format integrity
-  - crypto:
-    - renamed `ab2str()` to `abtoa()` and `str2ab()` to `atoab()` to match `btoa()` and `atob()`
+  - Added [`capitalize()`](https://github.com/Sv443-Network/CoreUtils/blob/main/docs.md#function-capitalize) to capitalize the first letter of a string.
+  - Added [`setImmediateInterval()`](https://github.com/Sv443-Network/CoreUtils/blob/main/docs.md#function-setimmediateinterval) to set an interval that runs immediately, then again on a fixed _interval._
+  - Added [`setImmediateTimeoutLoop()`](https://github.com/Sv443-Network/CoreUtils/blob/main/docs.md#function-setimmediatetimeoutloop) to set a recursive `setTimeout()` loop with a fixed _delay._
+  - Added [`takeRandomItemIndex()`](https://github.com/Sv443-Network/CoreUtils/blob/main/docs.md#function-takerandomitemindex), as a mutating counterpart to [`randomItemIndex()`](https://github.com/Sv443-Network/CoreUtils/blob/main/docs.md#function-randomitemindex)
+  - Added [`truncStr()`](https://github.com/Sv443-Network/CoreUtils/blob/main/docs.md#function-truncstr) to truncate a string to a given length, optionally adding an ellipsis.
+  - Added [`valsWithin()`](https://github.com/Sv443-Network/CoreUtils/blob/main/docs.md#function-valswithin) to check if two values, rounded at the given decimal, are within a certain range of each other.
+  - Added [`scheduleExit()`](https://github.com/Sv443-Network/CoreUtils/blob/main/docs.md#function-scheduleexit) to schedule a Node/Deno process to exit with the given code, after the microtask queue is empty or after the given timeout.
+- **BREAKING CHANGES:**
+  - Reworked `DataStore`
+    - The constructor now needs an `engine` property that is an instance of a [`DataStoreEngine`](https://github.com/Sv443-Network/CoreUtils/blob/main/docs.md#class-datastoreengine.)
+    - Encoding with `deflate-raw` will now be enabled by default. Set `compressionFormat: null` to disable it and restore the previous behavior.
+    - Added [`DataStoreEngine` class](https://github.com/Sv443-Network/CoreUtils/blob/main/docs.md#class-datastoreengine) with two implementations available out-of-the-box; [`FileStorageEngine`](https://github.com/Sv443-Network/CoreUtils/blob/main/docs.md#class-filestorageengine) and [`BrowserStorageEngine`](https://github.com/Sv443-Network/CoreUtils/blob/main/docs.md#class-browserstorageengine), for Node/Deno and browser environments respectively. Userscripts need to use [`BrowserStorageEngine`.](https://github.com/Sv443-Network/CoreUtils/blob/main/docs.md#class-browserstorageengine)
+    - Added shorthand property `compressionFormat` as an alternative to the properties `encodeData` and `decodeData`
+    - The global key `__ds_fmt_ver` will now contain a global version number for DataStore-internal format integrity.
+  - Renamed `ab2str()` to `abtoa()` and `str2ab()` to `atoab()` to match the naming of `atob()` and `btoa()`
+  - Renamed `purifyObj()` to `pureObj()`

package/README.md

@@ -1,15 +1,10 @@
-> [!IMPORTANT]  
-> This library is not ready to be used yet. Please check back in a couple weeks.
-
-<br><br>
-
 <div align="center" style="text-align: center;">
 
 # CoreUtils
 Cross-platform, general-purpose, JavaScript core library for Node, Deno and the browser.  
 Intended to be used in conjunction with [`@sv443-network/userutils`](https://github.com/Sv443-Network/UserUtils) and [`@sv443-network/djsutils`](https://github.com/Sv443-Network/DJSUtils), but can be used independently as well.
 
-### [Documentation](./docs.md#readme) &bull; [Features](#features) &bull; [Installation](#installation) &bull; [License](#license)
+### [Documentation](./docs.md#readme) &bull; [Features](#features) &bull; [Installation](#installation) &bull; [License](./LICENSE.txt) &bull; [Changelog](./CHANGELOG.md)
 
 </div>
 <br>
@@ -39,12 +34,14 @@ Intended to be used in conjunction with [`@sv443-network/userutils`](https://git
   - 🟧 [`class DataStore`](./docs.md#class-datastore) - The main class for the data store
     - 🔷 [`type DataStoreOptions`](./docs.md#type-datastoreoptions) - Options for the data store
     - 🔷 [`type DataMigrationsDict`](./docs.md#type-datamigrationsdict) - Dictionary of data migration functions
+    - 🔷 [`type DataStoreData`](./docs.md#type-datastoredata) - The type of the serializable data
   - 🟧 [`class DataStoreSerializer`](./docs.md#class-datastoreserializer) - Serializes and deserializes data for multiple DataStore instances
     - 🔷 [`type DataStoreSerializerOptions`](./docs.md#type-datastoreserializeroptions) - Options for the DataStoreSerializer
     - 🔷 [`type LoadStoresDataResult`](./docs.md#type-loadstoresdataresult) - Result of calling [`loadStoresData()`](./docs.md#datastoreserializer-loadstoresdata)
     - 🔷 [`type SerializedDataStore`](./docs.md#type-serializeddatastore) - Meta object and serialized data of a DataStore instance
     - 🔷 [`type StoreFilter`](./docs.md#type-storefilter) - Filter for selecting data stores
   - 🟧 [`class DataStoreEngine`](./docs.md#class-datastoreengine) - Base class for DataStore storage engines, which handle the data storage
+    - 🔷 [`type DataStoreEngineDSOptions`](./docs.md#type-datastoreenginedsoptions) - Reduced version of [`DataStoreOptions`](./docs.md#type-datastoreoptions)
   - [Storage Engines:](./docs.md#storage-engines)
     - 🟧 [`class BrowserStorageEngine`](./docs.md#class-browserstorageengine) - Storage engine for browser environments (localStorage, sessionStorage)
       - 🔷 [`type BrowserStorageEngineOptions`](./docs.md#browserstorageengineoptions) - Options for the browser storage engine
@@ -68,6 +65,7 @@ Intended to be used in conjunction with [`@sv443-network/userutils`](https://git
   - 🟣 [`function formatNumber()`](./docs.md#function-formatnumber) - Formats a number to a string using the given locale and format identifier
     - 🔷 [`type NumberFormat`](./docs.md#type-numberformat) - Number format identifier
   - 🟣 [`function mapRange()`](./docs.md#function-maprange) - Maps a number from one range to another
+  - 🟣 [`function overflowVal()`](./docs.md#function-overflowVal) - Makes sure a number is in a range by over- & underflowing it
   - 🟣 [`function randRange()`](./docs.md#function-randrange) - Returns a random number in the given range
   - 🟣 [`function roundFixed()`](./docs.md#function-roundfixed) - Rounds the given number to the given number of decimal places
   - 🟣 [`function valsWithin()`](./docs.md#function-valswithin) - Checks if the given numbers are within a certain range of each other
@@ -84,6 +82,7 @@ Intended to be used in conjunction with [`@sv443-network/userutils`](https://git
   - 🟣 [`function pureObj()`](./docs.md#function-pureobj) - Applies an object's props to a null object (object without prototype chain) or just returns a new null object
   - 🟣 [`function setImmediateInterval()`](./docs.md#function-setimmediateinterval) - Like `setInterval()`, but instantly calls the callback and supports passing an [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal)
   - 🟣 [`function setImmediateTimeoutLoop()`](./docs.md#function-setimmediatetimeoutloop) - Like a recursive `setTimeout()` loop, but instantly calls the callback and supports passing an [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal)
+  - 🟣 [`function scheduleExit()`](./docs.md#function-scheduleexit) - Schedules a process exit after the next event loop tick, to allow operations like IO writes to finish.
 - [**NanoEmitter:**](./docs.md#nanoemitter)
   - 🟧 [`class NanoEmitter`](./docs.md#class-nanoemitter) - Simple, lightweight event emitter class that can be used in both FP and OOP, inspired by [`EventEmitter` from `node:events`](https://nodejs.org/api/events.html#class-eventemitter), based on [`nanoevents`](https://npmjs.com/package/nanoevents)
     - 🔷 [`type NanoEmitterOptions`](./docs.md#type-nanoemitteroptions) - Options for the [`NanoEmitter` class](./docs.md#class-nanoemitter)
@@ -94,7 +93,7 @@ Intended to be used in conjunction with [`@sv443-network/userutils`](https://git
     - 🟩 [`const defaultPbChars`](./docs.md#const-defaultpbchars) - Default characters for the progress bar
     - 🔷 [`type ProgressBarChars`](./docs.md#type-progressbarchars) - Type for the progress bar characters object
   - 🟣 [`function joinArrayReadable()`](./docs.md#function-joinarrayreadable) - Joins the given array into a string, using the given separators and last separator
-  - 🟣 [`function secsToTimeStr()`](./docs.md#function-sectostimestr) - Turns the given number of seconds into a string in the format `(hh:)mm:ss` with intelligent zero-padding
+  - 🟣 [`function secsToTimeStr()`](./docs.md#function-secstotimestr) - Turns the given number of seconds into a string in the format `(hh:)mm:ss` with intelligent zero-padding
   - 🟣 [`function truncStr()`](./docs.md#function-truncstr) - Truncates the given string to the given length
 <!-- - *[**TieredCache:**](./docs.md#tieredcache)
   - 🟧 *[`class TieredCache`](./docs.md#class-tieredcache) - A multi-tier cache that uses multiple storage engines with different expiration times
@@ -126,7 +125,7 @@ Intended to be used in conjunction with [`@sv443-network/userutils`](https://git
 > 🟣 = function  
 > 🟧 = class  
 > 🔷 = type  
-> 🔶 = const
+> 🟩 = const
 
 <br>
 
@@ -138,4 +137,48 @@ pnpm i @sv443-network/coreutils
 yarn add @sv443-network/coreutils
 npx jsr install @sv443-network/coreutils
 deno add jsr:@sv443-network/coreutils
-```
+```
+- If you are in a DOM environment, you can include the UMD bundle using your favorite CDN (after inserting the version number):
+```html
+<script src="https://cdn.jsdelivr.net/npm/@sv443-network/coreutils@INSERT_VERSION_HERE/dist/CoreUtils.min.umd.js"></script>
+<script src="https://unpkg.com/@sv443-network/coreutils@INSERT_VERSION_HERE/dist/CoreUtils.min.umd.js"></script>
+<script src="https://esm.sh/@sv443-network/coreutils@INSERT_VERSION_HERE/dist/CoreUtils.min.umd.js"></script>
+```
+- Then, import parts of the library as needed:
+```ts
+// >> EcmaScript Modules (ESM):
+
+// - import parts of the library:
+import { randomItem } from "@sv443-network/coreutils";
+// - or import the full library:
+import * as CoreUtils from "@sv443-network/coreutils";
+// - or import raw TS files, after installing via JSR:
+import { DataStore } from "jsr:@sv443-network/coreutils/lib/DataStore.ts";
+
+// >> CommonJS (CJS):
+
+// - import parts of the library:
+const { debounce } = require("@sv443-network/coreutils");
+// - or import the full library:
+const CoreUtils = require("@sv443-network/coreutils");
+
+// >> Universal Module Definition (UMD):
+
+// - to make the global variable `CoreUtils` available, import this file:
+// "@sv443-network/coreutils/dist/CoreUtils.min.umd.js"
+// - or import the library on your HTML page:
+// <script src="https://cdn.jsdelivr.net/npm/@sv443-network/coreutils@INSERT_VERSION_HERE/dist/CoreUtils.min.umd.js"></script>
+// (make sure to insert the version number above. Use 'latest' (not recommended) or a specific version, e.g. '9.4.3')
+```
+
+<br><br>
+
+<div align="center" style="text-align: center;">
+
+Made with ❤️ by [Sv443](https://github.com/Sv443)  
+If you like this userscript, please consider [supporting the development](https://github.com/sponsors/Sv443)  
+  
+© 2025 Sv443 & Sv443 Network  
+[MIT license](./LICENSE.txt)
+
+</div>