@guillaume-docquier/tools-ts 5.1.1 → 6.0.0

package/README.md

@@ -109,12 +109,23 @@ consistent.
 | `asyncNoop`       | Asynchronous no-op function.               | You need a safe default async callback or hook that resolves immediately.       |
 | `omit`            | Runtime equivalent of `Omit<TType, TKey>`. | You need to remove keys from an object.                                         |
 
-### Measurement
+### Profiling
 
-Use these helpers for lightweight operational visibility, not for rigorous
-benchmarking.
+Use these helpers for quick profiling.
 
 | Export                  | What it is                                      | Use it when                                                                          |
 | ----------------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------ |
-| `Measure.executionTime` | Wraps sync or async work and logs elapsed time. | You need quick timing instrumentation around a named operation.                      |
-| `Measure.memoryUsage`   | Logs process memory usage in megabytes.         | You need a snapshot of Node.js process memory for diagnostics or runtime visibility. |
+| `Profile.executionTime` | Wraps sync or async work and logs elapsed time. | You need quick timing instrumentation around a named operation.                      |
+| `Profile.memoryUsage`   | Logs process memory usage in megabytes.         | You need a snapshot of Node.js process memory for diagnostics or runtime visibility. |
+
+### Measurements
+
+| Export | What it is                                                          | Use it when                                                  |
+| ------ | ------------------------------------------------------------------- | ------------------------------------------------------------ |
+| `Time` | Represent a time value with a unit and contains conversion methods. | You want to represent time and abstract away the units used. |
+
+### Date manipulations
+
+| Export               | What it is                                 | Use it when                                                           |
+| -------------------- | ------------------------------------------ | --------------------------------------------------------------------- |
+| `Datetime.increment` | Increments a date by a set amount of Time. | You need to increment time. Plays nicely with the `Time` measurement. |

package/dist/Datetime.d.ts

@@ -0,0 +1,11 @@
+import { Time } from "./measurements/Time.js";
+export declare const Datetime: {
+    /**
+     * Increments a date by x seconds
+     * A unit agnostic utility would be useful here
+     */
+    increment: ({ date, time }: {
+        date: Date;
+        time: Time;
+    }) => Date;
+};

package/dist/Datetime.js

@@ -0,0 +1,11 @@
+import { Time, UnitOfTime } from "./measurements/Time.js";
+export const Datetime = {
+    /**
+     * Increments a date by x seconds
+     * A unit agnostic utility would be useful here
+     */
+    increment: ({ date, time }) => {
+        return new Date(date.getTime() + Time.in(time, UnitOfTime.MILLISECONDS));
+    },
+};
+//# sourceMappingURL=Datetime.js.map

package/dist/Datetime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Datetime.js","sourceRoot":"","sources":["../src/Datetime.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAA;AAEzD,MAAM,CAAC,MAAM,QAAQ,GAAG;IACtB;;;OAGG;IACH,SAAS,EAAE,CAAC,EAAE,IAAI,EAAE,IAAI,EAA8B,EAAQ,EAAE;QAC9D,OAAO,IAAI,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,GAAG,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,UAAU,CAAC,YAAY,CAAC,CAAC,CAAA;IAC1E,CAAC;CACF,CAAA"}

package/dist/{Measure.d.ts → Profile.d.ts}

@@ -1,7 +1,7 @@
 type BasicLogger = {
     info: (message: string, context?: Record<string, unknown>) => void;
 };
-export declare const Measure: {
+export declare const Profile: {
     executionTime: typeof executionTime;
     /**
      * Prints the current memory usage using {@link https://nodejs.org/api/process.html#processmemoryusage process.memoryUsage()}.

package/dist/{Measure.js → Profile.js}

@@ -1,4 +1,4 @@
-export const Measure = {
+export const Profile = {
     // You can't overload while defining object properties, which is why the function implementation is not inlined
     executionTime,
     /**
@@ -50,4 +50,4 @@ function logExecutionTime(label, startedAt, logger) {
 function bytesToMb(bytes) {
     return `${Math.round(bytes / 1024 / 1024).toFixed(2)} MB`;
 }
-//# sourceMappingURL=Measure.js.map
+//# sourceMappingURL=Profile.js.map

package/dist/{Measure.js.map → Profile.js.map}

@@ -1 +1 @@
-{"version":3,"file":"Measure.js","sourceRoot":"","sources":["../src/Measure.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,MAAM,OAAO,GAAG;IACrB,+GAA+G;IAC/G,aAAa;IAEb;;OAEG;IACH,WAAW,CAAC,SAAsB,OAAO;QACvC,MAAM,WAAW,GAAG,OAAO,CAAC,WAAW,EAAE,CAAA,CAAC,gBAAgB;QAE1D,MAAM,CAAC,IAAI,CAAC,cAAc,EAAE;YAC1B;;;;;eAKG;YACH,GAAG,EAAE,SAAS,CAAC,WAAW,CAAC,GAAG,CAAC;YAC/B;;eAEG;YACH,SAAS,EAAE,SAAS,CAAC,WAAW,CAAC,SAAS,CAAC;YAC3C;;eAEG;YACH,QAAQ,EAAE,SAAS,CAAC,WAAW,CAAC,QAAQ,CAAC;YACzC;;eAEG;YACH,QAAQ,EAAE,SAAS,CAAC,WAAW,CAAC,QAAQ,CAAC;YACzC;;eAEG;YACH,YAAY,EAAE,SAAS,CAAC,WAAW,CAAC,YAAY,CAAC;SAClD,CAAC,CAAA;IACJ,CAAC;CACF,CAAA;AAYD,SAAS,aAAa,CAAI,KAAa,EAAE,MAAsC,EAAE,SAAsB,OAAO;IAC5G,MAAM,SAAS,GAAG,WAAW,CAAC,GAAG,EAAE,CAAA;IACnC,MAAM,MAAM,GAAG,MAAM,EAAE,CAAA;IACvB,IAAI,MAAM,YAAY,OAAO,EAAE,CAAC;QAC9B,OAAO,MAAM,CAAC,OAAO,CAAC,GAAG,EAAE;YACzB,gBAAgB,CAAC,KAAK,EAAE,SAAS,EAAE,MAAM,CAAC,CAAA;QAC5C,CAAC,CAAC,CAAA;IACJ,CAAC;IAED,gBAAgB,CAAC,KAAK,EAAE,SAAS,EAAE,MAAM,CAAC,CAAA;IAC1C,OAAO,MAAM,CAAA;AACf,CAAC;AAED,SAAS,gBAAgB,CAAC,KAAa,EAAE,SAAiB,EAAE,MAAmB;IAC7E,MAAM,CAAC,IAAI,CAAC,GAAG,KAAK,KAAK,CAAC,WAAW,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,CAAA;AAC1E,CAAC;AAED,SAAS,SAAS,CAAC,KAAa;IAC9B,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,GAAG,IAAI,GAAG,IAAI,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,CAAA;AAC3D,CAAC"}
+{"version":3,"file":"Profile.js","sourceRoot":"","sources":["../src/Profile.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,MAAM,OAAO,GAAG;IACrB,+GAA+G;IAC/G,aAAa;IAEb;;OAEG;IACH,WAAW,CAAC,SAAsB,OAAO;QACvC,MAAM,WAAW,GAAG,OAAO,CAAC,WAAW,EAAE,CAAA,CAAC,gBAAgB;QAE1D,MAAM,CAAC,IAAI,CAAC,cAAc,EAAE;YAC1B;;;;;eAKG;YACH,GAAG,EAAE,SAAS,CAAC,WAAW,CAAC,GAAG,CAAC;YAC/B;;eAEG;YACH,SAAS,EAAE,SAAS,CAAC,WAAW,CAAC,SAAS,CAAC;YAC3C;;eAEG;YACH,QAAQ,EAAE,SAAS,CAAC,WAAW,CAAC,QAAQ,CAAC;YACzC;;eAEG;YACH,QAAQ,EAAE,SAAS,CAAC,WAAW,CAAC,QAAQ,CAAC;YACzC;;eAEG;YACH,YAAY,EAAE,SAAS,CAAC,WAAW,CAAC,YAAY,CAAC;SAClD,CAAC,CAAA;IACJ,CAAC;CACF,CAAA;AAYD,SAAS,aAAa,CAAI,KAAa,EAAE,MAAsC,EAAE,SAAsB,OAAO;IAC5G,MAAM,SAAS,GAAG,WAAW,CAAC,GAAG,EAAE,CAAA;IACnC,MAAM,MAAM,GAAG,MAAM,EAAE,CAAA;IACvB,IAAI,MAAM,YAAY,OAAO,EAAE,CAAC;QAC9B,OAAO,MAAM,CAAC,OAAO,CAAC,GAAG,EAAE;YACzB,gBAAgB,CAAC,KAAK,EAAE,SAAS,EAAE,MAAM,CAAC,CAAA;QAC5C,CAAC,CAAC,CAAA;IACJ,CAAC;IAED,gBAAgB,CAAC,KAAK,EAAE,SAAS,EAAE,MAAM,CAAC,CAAA;IAC1C,OAAO,MAAM,CAAA;AACf,CAAC;AAED,SAAS,gBAAgB,CAAC,KAAa,EAAE,SAAiB,EAAE,MAAmB;IAC7E,MAAM,CAAC,IAAI,CAAC,GAAG,KAAK,KAAK,CAAC,WAAW,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,CAAA;AAC1E,CAAC;AAED,SAAS,SAAS,CAAC,KAAa;IAC9B,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,GAAG,IAAI,GAAG,IAAI,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,CAAA;AAC3D,CAAC"}

package/dist/entry.tools-ts.d.ts

@@ -9,7 +9,7 @@ export { asArray } from "./asArray.js";
 export { omit } from "./omit.js";
 export { Assert } from "./Assert.js";
 export { Result, type Success, type Failure } from "./Result.js";
-export { Measure } from "./Measure.js";
+export { Profile } from "./Profile.js";
 export { Range } from "./Range.js";
 export { TypeGuard } from "./TypeGuard.js";
 export { setTimeoutAsync } from "./setTimeoutAsync.js";
@@ -27,3 +27,5 @@ export { debounce } from "./debounce.js";
 export { Sort } from "./Sort.js";
 export { createRng, type Rng, type Generator } from "./rng/rng.js";
 export { mulberry32Prng } from "./rng/mulberry32prng.js";
+export { Datetime } from "./Datetime.js";
+export { Time, UnitOfTime } from "./measurements/Time.js";

package/dist/entry.tools-ts.js

@@ -8,7 +8,7 @@ export { asArray } from "./asArray.js";
 export { omit } from "./omit.js";
 export { Assert } from "./Assert.js";
 export { Result } from "./Result.js";
-export { Measure } from "./Measure.js";
+export { Profile } from "./Profile.js";
 export { Range } from "./Range.js";
 export { TypeGuard } from "./TypeGuard.js";
 export { setTimeoutAsync } from "./setTimeoutAsync.js";
@@ -22,4 +22,6 @@ export { debounce } from "./debounce.js";
 export { Sort } from "./Sort.js";
 export { createRng } from "./rng/rng.js";
 export { mulberry32Prng } from "./rng/mulberry32prng.js";
+export { Datetime } from "./Datetime.js";
+export { Time, UnitOfTime } from "./measurements/Time.js";
 //# sourceMappingURL=entry.tools-ts.js.map

package/dist/entry.tools-ts.js.map

@@ -1 +1 @@
-{"version":3,"file":"entry.tools-ts.js","sourceRoot":"","sources":["../src/entry.tools-ts.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAC7C,OAAO,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAA;AAC3D,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAA;AACnD,OAAO,EAAE,mBAAmB,EAAE,MAAM,iCAAiC,CAAA;AACrE,OAAO,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAA;AACzD,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AAI5C,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AACtC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AAChC,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AACpC,OAAO,EAAE,MAAM,EAA8B,MAAM,aAAa,CAAA;AAChE,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AACtC,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AAClC,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAC1C,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AACtD,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,WAAW,CAAA;AAE3C,OAAO,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAA;AAC5C,OAAO,EAAE,yBAAyB,EAAE,MAAM,wBAAwB,CAAA;AAClE,OAAO,EAAE,iBAAiB,EAAE,MAAM,0CAA0C,CAAA;AAC5E,OAAO,EAAE,sBAAsB,EAAE,MAAM,+CAA+C,CAAA;AAEtF,OAAO,EAAE,oBAAoB,EAAE,MAAM,kCAAkC,CAAA;AAKvE,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AACxC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AAChC,OAAO,EAAE,SAAS,EAA4B,MAAM,cAAc,CAAA;AAClE,OAAO,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAA"}
+{"version":3,"file":"entry.tools-ts.js","sourceRoot":"","sources":["../src/entry.tools-ts.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAC7C,OAAO,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAA;AAC3D,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAA;AACnD,OAAO,EAAE,mBAAmB,EAAE,MAAM,iCAAiC,CAAA;AACrE,OAAO,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAA;AACzD,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AAI5C,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AACtC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AAChC,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AACpC,OAAO,EAAE,MAAM,EAA8B,MAAM,aAAa,CAAA;AAChE,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AACtC,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AAClC,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAC1C,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AACtD,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,WAAW,CAAA;AAE3C,OAAO,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAA;AAC5C,OAAO,EAAE,yBAAyB,EAAE,MAAM,wBAAwB,CAAA;AAClE,OAAO,EAAE,iBAAiB,EAAE,MAAM,0CAA0C,CAAA;AAC5E,OAAO,EAAE,sBAAsB,EAAE,MAAM,+CAA+C,CAAA;AAEtF,OAAO,EAAE,oBAAoB,EAAE,MAAM,kCAAkC,CAAA;AAKvE,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AACxC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AAChC,OAAO,EAAE,SAAS,EAA4B,MAAM,cAAc,CAAA;AAClE,OAAO,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAA;AACxD,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AACxC,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAA"}

package/dist/measurements/Measurement.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Represents a measure with its unit
+ */
+export interface Measurement<TMeasurementUnit> {
+    value: number;
+    unit: TMeasurementUnit;
+}

package/dist/measurements/Measurement.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=Measurement.js.map

package/dist/measurements/Measurement.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Measurement.js","sourceRoot":"","sources":["../../src/measurements/Measurement.ts"],"names":[],"mappings":""}

package/dist/measurements/Time.d.ts

@@ -0,0 +1,37 @@
+import { Measurement } from "./Measurement.js";
+/**
+ * Represents the possible units to define time.
+ */
+export declare enum UnitOfTime {
+    MILLISECONDS = "milliseconds",
+    SECONDS = "seconds",
+    MINUTES = "minutes",
+    HOURS = "hours"
+}
+/**
+ * Represents a time with its unit
+ */
+export type Time = Measurement<UnitOfTime>;
+/**
+ * A set of functions to work with Times.
+ */
+export declare const Time: {
+    create: (value: number, unit: UnitOfTime) => {
+        value: number;
+        unit: UnitOfTime;
+    };
+    /**
+     * Converts a time to another unit of time.
+     * The provided time is left untouched.
+     * @param time The time to convert.
+     * @param newUnit The new unit to convert to.
+     * @returns A new Time with the requested unit of time.
+     */
+    convert(time: Time, newUnit: UnitOfTime): Time;
+    /**
+     * Returns the value of the time in the given unit of time.
+     * @param time The time to get the value of.
+     * @param newUnit The unit of time to get the value of the time in.
+     */
+    in(time: Time, newUnit: UnitOfTime): number;
+};

package/dist/measurements/Time.js

@@ -0,0 +1,53 @@
+/**
+ * Represents the possible units to define time.
+ */
+export var UnitOfTime;
+(function (UnitOfTime) {
+    UnitOfTime["MILLISECONDS"] = "milliseconds";
+    UnitOfTime["SECONDS"] = "seconds";
+    UnitOfTime["MINUTES"] = "minutes";
+    UnitOfTime["HOURS"] = "hours";
+})(UnitOfTime || (UnitOfTime = {}));
+/**
+ * The definition of factors of time, where the base unit is the second.
+ * 1 minute is 1/60th of a second.
+ */
+const TIME_PER_SECONDS = {
+    [UnitOfTime.MILLISECONDS]: 1000,
+    [UnitOfTime.SECONDS]: 1,
+    [UnitOfTime.MINUTES]: 1 / 60,
+    [UnitOfTime.HOURS]: 1 / 60 / 60,
+};
+/**
+ * A set of functions to work with Times.
+ */
+export const Time = {
+    create: (value, unit) => {
+        return {
+            value,
+            unit,
+        };
+    },
+    /**
+     * Converts a time to another unit of time.
+     * The provided time is left untouched.
+     * @param time The time to convert.
+     * @param newUnit The new unit to convert to.
+     * @returns A new Time with the requested unit of time.
+     */
+    convert(time, newUnit) {
+        return {
+            value: Time.in(time, newUnit),
+            unit: newUnit,
+        };
+    },
+    /**
+     * Returns the value of the time in the given unit of time.
+     * @param time The time to get the value of.
+     * @param newUnit The unit of time to get the value of the time in.
+     */
+    in(time, newUnit) {
+        return (time.value * TIME_PER_SECONDS[newUnit]) / TIME_PER_SECONDS[time.unit];
+    },
+};
+//# sourceMappingURL=Time.js.map

package/dist/measurements/Time.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Time.js","sourceRoot":"","sources":["../../src/measurements/Time.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,MAAM,CAAN,IAAY,UAKX;AALD,WAAY,UAAU;IACpB,2CAA6B,CAAA;IAC7B,iCAAmB,CAAA;IACnB,iCAAmB,CAAA;IACnB,6BAAe,CAAA;AACjB,CAAC,EALW,UAAU,KAAV,UAAU,QAKrB;AAED;;;GAGG;AACH,MAAM,gBAAgB,GAA+B;IACnD,CAAC,UAAU,CAAC,YAAY,CAAC,EAAE,IAAI;IAC/B,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;IACvB,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE;IAC5B,CAAC,UAAU,CAAC,KAAK,CAAC,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE;CAChC,CAAA;AAOD;;GAEG;AACH,MAAM,CAAC,MAAM,IAAI,GAAG;IAClB,MAAM,EAAE,CAAC,KAAa,EAAE,IAAgB,EAAE,EAAE;QAC1C,OAAO;YACL,KAAK;YACL,IAAI;SACL,CAAA;IACH,CAAC;IAED;;;;;;OAMG;IACH,OAAO,CAAC,IAAU,EAAE,OAAmB;QACrC,OAAO;YACL,KAAK,EAAE,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,CAAC;YAC7B,IAAI,EAAE,OAAO;SACd,CAAA;IACH,CAAC;IAED;;;;OAIG;IACH,EAAE,CAAC,IAAU,EAAE,OAAmB;QAChC,OAAO,CAAC,IAAI,CAAC,KAAK,GAAG,gBAAgB,CAAC,OAAO,CAAC,CAAC,GAAG,gBAAgB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IAC/E,CAAC;CACF,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guillaume-docquier/tools-ts",
-  "version": "5.1.1",
+  "version": "6.0.0",
   "description": "My personal collection of typescript tools",
   "homepage": "https://github.com/Guillaume-Docquier/tools-ts",
   "license": "MIT",