@oliversalzburg/js-utils 0.0.2 → 0.0.3

package/README.md

@@ -1,48 +1 @@
-# Project Template
-
-## Does
-
--   [Yarn 3](https://yarnpkg.com/)
--   Uses [TypeScript](https://www.typescriptlang.org/)
--   Target application runs in [Node.js](https://nodejs.org/)
--   [esbuild](https://esbuild.github.io/)
--   [EditorConfig](https://editorconfig.org/) + [ESLint](https://eslint.org/) + [Prettier](https://prettier.io/) + [lint-staged](https://github.com/okonet/lint-staged)
--   QA with [GitHub Actions](https://github.com/features/actions)
--   [MkDocs](https://www.mkdocs.org/)-oriented Markdown in mind
-
-## Doesn't
-
--   [Yarn PnP](https://yarnpkg.com/features/pnp)
--   [Yarn telemetry](https://yarnpkg.com/advanced/telemetry)
--   [Yarn Zero-Installs](https://yarnpkg.com/features/zero-installs)
--   [Husky](https://github.com/typicode/husky)
-
-## Why
-
-1.  Why modern Yarn?
-
-    Among other things, Yarn is robust, performant and extremely versatile when it comes to repository management. The given configuration provides a very solid first-time experience. Some of the things that make modern Yarn great can be seen in this project template.
-
-1.  Why esbuild?
-
-    We want fast builds. The code is still checked for correctness in the editor and in CI.
-
-1.  Why the MkDocs Markdown?
-
-    If you're going to want to build any documentation site, you will appreciate having auto-formatted to this style from the start. Using mkdocs-material for documentation sites is highly recommended. The Python Markdown ecosystem is much more versatile and performant than the JS/TS space.
-
-1.  Why is PnP disabled?
-
-    While PnP is generally preferred for its strictness, using it still incurs a lot of friction. Because PnP is enabled by default in modern Yarn, this deters many users from adopting modern Yarn. Thus, this project uses Yarn's `node-modules` linker, the behavior of which should be very familiar to most adopters.
-
-1.  Why is telemetry disabled?
-
-    Whenever possible, the disclosure of _any_ data should be opt-in. Please refer to the document linked above, and enable telemetry after carefully reading it.
-
-1.  Why not Zero-Installs?
-
-    Zero-Installs are purely a `.gitignore`-controlled feature. Most new adopters do not expect the behavior of the default configuration and some adopters have raised concerns over long-term effects. Enable it after carefully reading the article linked above.
-
-1.  Why not use Husky for the hook?
-
-    Husky is more complex than what is required to install the hook in a modern Yarn repository. We also do not want to hand over control over repository behavior to a dependency.
+# JS Utils

package/output/array.d.ts

@@ -1,5 +1,32 @@
-import { ConstructorOf } from "./nil.js";
+import { ConstructorOf } from "./core.js";
+/**
+ * Places the items in the array in random order.
+ * @param array The array to shuffle.
+ * @returns The passed array in random order.
+ */
 export declare const shuffleArray: <T>(array: T[]) => T[];
+/**
+ * Returns an array that holds all items that appear in both
+ * passed arrays.
+ * @param a The first array.
+ * @param b The second array.
+ * @returns A new array which holds the items that appear in
+ * both passed arrays.
+ */
 export declare const intersect: <T>(a: T[], b: T[]) => T[];
+/**
+ * Returns an array that holds all items that only appear in `a`.
+ * @param a The first array.
+ * @param b The second array.
+ * @returns A new array which holds the items that ony appear
+ * in `a`.
+ */
 export declare const difference: <T>(a: T[], b: T[]) => T[];
+/**
+ * From an array with unknown contents, retrieve all the elements
+ * that are of a certain type and return them as a new array.
+ * @param array The array to filter.
+ * @param InstanceType The type to search for.
+ * @returns A new array with the filtered items.
+ */
 export declare const filterType: <T>(array: Array<unknown>, InstanceType: ConstructorOf<T>) => T[];

package/output/array.js

@@ -1,4 +1,9 @@
 import { is } from "./nil.js";
+/**
+ * Places the items in the array in random order.
+ * @param array The array to shuffle.
+ * @returns The passed array in random order.
+ */
 export const shuffleArray = (array) => {
     for (let index = array.length - 1; index > 0; index--) {
         const targetIndex = Math.floor(Math.random() * (index + 1));
@@ -8,11 +13,33 @@ export const shuffleArray = (array) => {
     }
     return array;
 };
+/**
+ * Returns an array that holds all items that appear in both
+ * passed arrays.
+ * @param a The first array.
+ * @param b The second array.
+ * @returns A new array which holds the items that appear in
+ * both passed arrays.
+ */
 export const intersect = (a, b) => {
     return a.filter(x => b.includes(x));
 };
+/**
+ * Returns an array that holds all items that only appear in `a`.
+ * @param a The first array.
+ * @param b The second array.
+ * @returns A new array which holds the items that ony appear
+ * in `a`.
+ */
 export const difference = (a, b) => {
     return a.filter(x => !b.includes(x));
 };
+/**
+ * From an array with unknown contents, retrieve all the elements
+ * that are of a certain type and return them as a new array.
+ * @param array The array to filter.
+ * @param InstanceType The type to search for.
+ * @returns A new array with the filtered items.
+ */
 export const filterType = (array, InstanceType) => array.filter(element => is(element, InstanceType));
 //# sourceMappingURL=array.js.map

package/output/array.js.map

@@ -1 +1 @@
-{"version":3,"file":"array.js","sourceRoot":"","sources":["../source/array.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiB,EAAE,EAAE,MAAM,UAAU,CAAC;AAE7C,MAAM,CAAC,MAAM,YAAY,GAAG,CAAI,KAAe,EAAE,EAAE;IACjD,KAAK,IAAI,KAAK,GAAG,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,KAAK,GAAG,CAAC,EAAE,KAAK,EAAE,EAAE;QACrD,MAAM,WAAW,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC;QAC5D,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC;QAC1B,KAAK,CAAC,KAAK,CAAC,GAAG,KAAK,CAAC,WAAW,CAAC,CAAC;QAClC,KAAK,CAAC,WAAW,CAAC,GAAG,IAAI,CAAC;KAC3B;IACD,OAAO,KAAK,CAAC;AACf,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,SAAS,GAAG,CAAI,CAAW,EAAE,CAAW,EAAE,EAAE;IACvD,OAAO,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;AACtC,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,UAAU,GAAG,CAAI,CAAW,EAAE,CAAW,EAAE,EAAE;IACxD,OAAO,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;AACvC,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,UAAU,GAAG,CAAI,KAAqB,EAAE,YAA8B,EAAE,EAAE,CACrF,KAAK,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC,EAAE,CAAC,OAAO,EAAE,YAAY,CAAC,CAAa,CAAC"}
+{"version":3,"file":"array.js","sourceRoot":"","sources":["../source/array.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAE9B;;;;GAIG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,CAAI,KAAe,EAAE,EAAE;IACjD,KAAK,IAAI,KAAK,GAAG,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,KAAK,GAAG,CAAC,EAAE,KAAK,EAAE,EAAE;QACrD,MAAM,WAAW,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC;QAC5D,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC;QAC1B,KAAK,CAAC,KAAK,CAAC,GAAG,KAAK,CAAC,WAAW,CAAC,CAAC;QAClC,KAAK,CAAC,WAAW,CAAC,GAAG,IAAI,CAAC;KAC3B;IACD,OAAO,KAAK,CAAC;AACf,CAAC,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,CAAI,CAAW,EAAE,CAAW,EAAE,EAAE;IACvD,OAAO,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;AACtC,CAAC,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,CAAI,CAAW,EAAE,CAAW,EAAE,EAAE;IACxD,OAAO,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;AACvC,CAAC,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,CAAI,KAAqB,EAAE,YAA8B,EAAE,EAAE,CACrF,KAAK,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC,EAAE,CAAC,OAAO,EAAE,YAAY,CAAC,CAAa,CAAC"}

package/output/core.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Describes a function that is a constructor for T.
+ */
+export type ConstructorOf<T = Record<string, unknown>> = new (...args: any[]) => T;

package/output/core.js

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

package/output/core.js.map

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

package/output/nil.d.ts

@@ -1,30 +1,39 @@
+import { ConstructorOf } from "./core.js";
+/**
+ * When you want to normalize away `null` | `undefined`, or deal
+ * with either type through a consistent interface.
+ */
 export type Nil = null | undefined;
-export type Maybe<T> = T | Nil;
 /**
- * Describes a function that is a constructor for T.
+ * A type that could be either what you want, or `Nil`.
  */
-export type ConstructorOf<T = Record<string, unknown>> = new (...args: any[]) => T;
+export type Maybe<T> = T | Nil;
 /**
  * Check if something is a concrete value of the given type.
  * Can be used as a typeguard.
- *
  * @param nilable The subject that could be nil.
  * @param InstanceType The type to check against.
+ * @returns `true` if the input element matches the given type,
+ * `false` otherwise.
  */
 export declare function is<T>(nilable: Maybe<T>, InstanceType: ConstructorOf<T>): nilable is T;
 /**
- * Check if something is Nil.
+ * Check if something is nil.
  * Can be used as a typeguard.
- *
  * @param subject The subject that could be nil.
+ * @returns `true` if the subject is nil, `false` otherwise.
  */
 export declare function isNil<T>(subject: Maybe<T>): subject is Nil;
+/**
+ * Thrown when an unexpected nil value was encountered.
+ */
 export declare class UnexpectedNilError extends Error {
     constructor(message?: string);
 }
 /**
  * Ensure that the passed subject is not nil; throw otherwise.
- *
  * @param subject A subject that is possible nil.
+ * @returns The subject, if it isn't nil.
+ * @throws {UnexpectedNilError} When the subject is nil.
  */
 export declare function mustExist<T>(subject: Maybe<T>): T;

package/output/nil.js

@@ -1,22 +1,26 @@
 /**
  * Check if something is a concrete value of the given type.
  * Can be used as a typeguard.
- *
  * @param nilable The subject that could be nil.
  * @param InstanceType The type to check against.
+ * @returns `true` if the input element matches the given type,
+ * `false` otherwise.
  */
 export function is(nilable, InstanceType) {
     return !isNil(nilable) && nilable instanceof InstanceType;
 }
 /**
- * Check if something is Nil.
+ * Check if something is nil.
  * Can be used as a typeguard.
- *
  * @param subject The subject that could be nil.
+ * @returns `true` if the subject is nil, `false` otherwise.
  */
 export function isNil(subject) {
     return subject === null || subject === undefined;
 }
+/**
+ * Thrown when an unexpected nil value was encountered.
+ */
 export class UnexpectedNilError extends Error {
     constructor(message = "unexpected nil value") {
         super(message);
@@ -24,8 +28,9 @@ export class UnexpectedNilError extends Error {
 }
 /**
  * Ensure that the passed subject is not nil; throw otherwise.
- *
  * @param subject A subject that is possible nil.
+ * @returns The subject, if it isn't nil.
+ * @throws {UnexpectedNilError} When the subject is nil.
  */
 export function mustExist(subject) {
     if (isNil(subject)) {

package/output/nil.js.map

@@ -1 +1 @@
-{"version":3,"file":"nil.js","sourceRoot":"","sources":["../source/nil.ts"],"names":[],"mappings":"AAQA;;;;;;GAMG;AACH,MAAM,UAAU,EAAE,CAAI,OAAiB,EAAE,YAA8B;IACrE,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,OAAO,YAAY,YAAY,CAAC;AAC5D,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,KAAK,CAAI,OAAiB;IACxC,OAAO,OAAO,KAAK,IAAI,IAAI,OAAO,KAAK,SAAS,CAAC;AACnD,CAAC;AAED,MAAM,OAAO,kBAAmB,SAAQ,KAAK;IAC3C,YAAY,OAAO,GAAG,sBAAsB;QAC1C,KAAK,CAAC,OAAO,CAAC,CAAC;IACjB,CAAC;CACF;AAED;;;;GAIG;AACH,MAAM,UAAU,SAAS,CAAI,OAAiB;IAC5C,IAAI,KAAK,CAAC,OAAO,CAAC,EAAE;QAClB,MAAM,IAAI,kBAAkB,EAAE,CAAC;KAChC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC"}
+{"version":3,"file":"nil.js","sourceRoot":"","sources":["../source/nil.ts"],"names":[],"mappings":"AAaA;;;;;;;GAOG;AACH,MAAM,UAAU,EAAE,CAAI,OAAiB,EAAE,YAA8B;IACrE,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,OAAO,YAAY,YAAY,CAAC;AAC5D,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,KAAK,CAAI,OAAiB;IACxC,OAAO,OAAO,KAAK,IAAI,IAAI,OAAO,KAAK,SAAS,CAAC;AACnD,CAAC;AAED;;GAEG;AACH,MAAM,OAAO,kBAAmB,SAAQ,KAAK;IAC3C,YAAY,OAAO,GAAG,sBAAsB;QAC1C,KAAK,CAAC,OAAO,CAAC,CAAC;IACjB,CAAC;CACF;AAED;;;;;GAKG;AACH,MAAM,UAAU,SAAS,CAAI,OAAiB;IAC5C,IAAI,KAAK,CAAC,OAAO,CAAC,EAAE;QAClB,MAAM,IAAI,kBAAkB,EAAE,CAAC;KAChC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/output/sleep.d.ts

@@ -1,6 +1,6 @@
 /**
  * Wait a given period before continuing execution.
- *
  * @param duration How many milliseconds to wait.
+ * @returns Nothing
  */
-export declare function sleep(duration: number): Promise<void>;
+export declare const sleep: (duration: number) => Promise<void>;

package/output/sleep.js

@@ -1,9 +1,9 @@
 /**
  * Wait a given period before continuing execution.
- *
  * @param duration How many milliseconds to wait.
+ * @returns Nothing
  */
-export function sleep(duration) {
+export const sleep = (duration) => {
     return new Promise(resolve => setTimeout(resolve, duration));
-}
+};
 //# sourceMappingURL=sleep.js.map

package/output/sleep.js.map

@@ -1 +1 @@
-{"version":3,"file":"sleep.js","sourceRoot":"","sources":["../source/sleep.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,UAAU,KAAK,CAAC,QAAgB;IACpC,OAAO,IAAI,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC,CAAC;AAC/D,CAAC"}
+{"version":3,"file":"sleep.js","sourceRoot":"","sources":["../source/sleep.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,CAAC,MAAM,KAAK,GAAG,CAAC,QAAgB,EAAiB,EAAE;IACvD,OAAO,IAAI,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC,CAAC;AAC/D,CAAC,CAAC"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@oliversalzburg/js-utils",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "license": "MIT",
   "author": "Oliver Salzburg <oliver.salzburg@gmail.com>",
   "type": "module",
@@ -17,7 +17,7 @@
     "build": "yarn run build:tsc",
     "build:esbuild": "node build.js",
     "build:tsc": "tsc",
-    "lint:eslint": "eslint source",
+    "lint:eslint": "eslint source ./*js",
     "lint:tsc": "tsc --noEmit",
     "npm:publish": "npm publish",
     "npm:publish:major": "npm version major && npm publish",
@@ -33,6 +33,7 @@
     "@typescript-eslint/parser": "6.9.0",
     "esbuild": "0.19.5",
     "eslint": "8.52.0",
+    "eslint-plugin-jsdoc": "46.8.2",
     "lint-staged": "15.0.2",
     "prettier": "3.0.3",
     "prettier-package-json": "2.8.0",