@thi.ng/arrays 2.10.22 → 2.11.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2025-04-01T21:42:04Z
+- **Last updated**: 2025-04-30T12:52:32Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -11,6 +11,16 @@ See [Conventional Commits](https://conventionalcommits.org/) for commit guidelin
 **Note:** Unlisted _patch_ versions only involve non-code or otherwise excluded changes
 and/or version bumps of transitive dependencies.
 
+## [2.11.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/arrays@2.11.0) (2025-04-30)
+
+#### 🚀 Features
+
+- add `permutation()` ([7dcc389](https://github.com/thi-ng/umbrella/commit/7dcc389))
+
+#### ♻️ Refactoring
+
+- minor update arg types ([52900ef](https://github.com/thi-ng/umbrella/commit/52900ef))
+
 ### [2.10.11](https://github.com/thi-ng/umbrella/tree/@thi.ng/arrays@2.10.11) (2025-01-17)
 
 #### 🩹 Bug fixes

package/README.md

@@ -7,7 +7,7 @@
 [![Mastodon Follow](https://img.shields.io/mastodon/follow/109331703950160316?domain=https%3A%2F%2Fmastodon.thi.ng&style=social)](https://mastodon.thi.ng/@toxi)
 
 > [!NOTE]
-> This is one of 205 standalone projects, maintained as part
+> This is one of 206 standalone projects, maintained as part
 > of the [@thi.ng/umbrella](https://github.com/thi-ng/umbrella/) monorepo
 > and anti-framework.
 >
@@ -60,7 +60,7 @@ For Node.js REPL:
 const arr = await import("@thi.ng/arrays");
 ```
 
-Package sizes (brotli'd, pre-treeshake): ESM: 3.00 KB
+Package sizes (brotli'd, pre-treeshake): ESM: 3.05 KB
 
 ## Dependencies
 
@@ -112,6 +112,7 @@ directory are using this package:
 - [`levenshtein()`](https://github.com/thi-ng/umbrella/tree/develop/packages/arrays/src/levenshtein.ts)
 - [`multiSwap()`](https://github.com/thi-ng/umbrella/tree/develop/packages/arrays/src/swap.ts)
 - [`peek()`](https://github.com/thi-ng/umbrella/tree/develop/packages/arrays/src/peek.ts)
+- [`permutation()`](https://github.com/thi-ng/umbrella/tree/develop/packages/arrays/src/permutation.ts)
 - [`quickSort()`](https://github.com/thi-ng/umbrella/tree/develop/packages/arrays/src/quicksort.ts)
 - [`rotate()` / `rotateTyped()`](https://github.com/thi-ng/umbrella/tree/develop/packages/arrays/src/rotate.ts)
 - [`selectThresholdMin()` / `selectThresholdMax()`](https://github.com/thi-ng/umbrella/tree/develop/packages/arrays/src/threshold.ts)

package/index.d.ts

@@ -18,6 +18,7 @@ export * from "./into.js";
 export * from "./iterator.js";
 export * from "./levenshtein.js";
 export * from "./peek.js";
+export * from "./permutation.js";
 export * from "./quicksort.js";
 export * from "./rotate.js";
 export * from "./shuffle.js";

package/index.js

@@ -18,6 +18,7 @@ export * from "./into.js";
 export * from "./iterator.js";
 export * from "./levenshtein.js";
 export * from "./peek.js";
+export * from "./permutation.js";
 export * from "./quicksort.js";
 export * from "./rotate.js";
 export * from "./shuffle.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/arrays",
-  "version": "2.10.22",
+  "version": "2.11.0",
   "description": "Array / Arraylike utilities",
   "type": "module",
   "module": "./index.js",
@@ -39,17 +39,17 @@
     "tool:tangle": "../../node_modules/.bin/tangle src/**/*.ts"
   },
   "dependencies": {
-    "@thi.ng/api": "^8.11.25",
-    "@thi.ng/checks": "^3.7.5",
-    "@thi.ng/compare": "^2.4.17",
-    "@thi.ng/equiv": "^2.1.81",
-    "@thi.ng/errors": "^2.5.31",
-    "@thi.ng/random": "^4.1.16"
+    "@thi.ng/api": "^8.11.27",
+    "@thi.ng/checks": "^3.7.7",
+    "@thi.ng/compare": "^2.4.19",
+    "@thi.ng/equiv": "^2.1.83",
+    "@thi.ng/errors": "^2.5.33",
+    "@thi.ng/random": "^4.1.18"
   },
   "devDependencies": {
-    "esbuild": "^0.25.2",
-    "typedoc": "^0.28.1",
-    "typescript": "^5.8.2"
+    "esbuild": "^0.25.3",
+    "typedoc": "^0.28.3",
+    "typescript": "^5.8.3"
   },
   "keywords": [
     "aos",
@@ -139,6 +139,9 @@
     "./peek": {
       "default": "./peek.js"
     },
+    "./permutation": {
+      "default": "./permutation.js"
+    },
     "./quicksort": {
       "default": "./quicksort.js"
     },
@@ -171,5 +174,5 @@
     "tag": "array",
     "year": 2018
   },
-  "gitHead": "87aa2d0e64a357476c10fd57aabdfded13c79f7d\n"
+  "gitHead": "4354686a6fb1f82c09ea48f92f87786191b231a0\n"
 }

package/permutation.d.ts

@@ -0,0 +1,66 @@
+import type { NumericArray } from "@thi.ng/api";
+import type { IRandom } from "@thi.ng/random";
+/**
+ * Creates a new array of `n` numbers with a random permutation of integers, in
+ * the semi-open [0,n) range (optionally using provided `rnd` instance).
+ *
+ * @remarks
+ * This function is syntax sugar, combining {@link fillRange} and
+ * {@link shuffle}.
+ *
+ * @example
+ * ```ts tangle:../export/permutation.ts
+ * import { permutation } from "@thi.ng/arrays";
+ *
+ * console.log(permuation(8));
+ * // [ 6, 2, 7, 5, 4, 0, 3, 1 ]
+ * ```
+ *
+ * @param n
+ * @param rnd
+ */
+export declare function permutation(n: number, rnd?: IRandom): number[];
+/**
+ * Fill the given array with a random permutation of integers, in the semi-open
+ * [0,n) range, where `n` is the length of the array. Optionally uses provided
+ * `rnd` instance.
+ *
+ * @remarks
+ * This function is syntax sugar, combining {@link fillRange} and
+ * {@link shuffle}.
+ *
+ * For typed integer arrays, the length of the array must be compatible with its
+ * value range, otherwise duplicates will appear (due to value overflow or
+ * clamping). E.g. a `Uint8Array` can only have a max length of 256 items if
+ * unique values are required. A `Int8Array` can only have a max length of 128
+ * values, otherwise negative numbers will appear in the result.
+ *
+ * @example
+ * ```ts tangle:../export/permutation-uint8.ts
+ * import { permutation } from "@thi.ng/arrays";
+ *
+ * const buf = new Uint8Array(16);
+ *
+ * // permute entire buffer
+ * console.log(permutation(buf));
+ * // Uint8Array(16) [ 6, 3, 2, 8, 10, 1, 15, 11, 9, 5, 0, 13, 7, 4, 14, 12 ]
+ *
+ * // apply to only a sub-ranges of the buffer
+ * for (let i = 0; i < buf.length; i += 4) {
+ * 	console.log(permutation(buf.subarray(i, i + 4)));
+ * }
+ * // Uint8Array(4) [ 1, 3, 2, 0 ]
+ * // Uint8Array(4) [ 2, 0, 3, 1 ]
+ * // Uint8Array(4) [ 1, 3, 2, 0 ]
+ * // Uint8Array(4) [ 3, 2, 1, 0 ]
+ *
+ * // show full buffer
+ * console.log(buf);
+ * // Uint8Array(16) [ 1, 3, 2, 0, 2, 0, 3, 1, 1, 3, 2, 0, 3, 2, 1, 0 ]
+ * ```
+ *
+ * @param n
+ * @param rnd
+ */
+export declare function permutation<T extends NumericArray>(buf: T, rnd?: IRandom): T;
+//# sourceMappingURL=permutation.d.ts.map

package/permutation.js

@@ -0,0 +1,13 @@
+import { isNumber } from "@thi.ng/checks/is-number";
+import { fillRange } from "./fill-range.js";
+import { shuffle } from "./shuffle.js";
+function permutation(buf, rnd) {
+  return shuffle(
+    fillRange(isNumber(buf) ? new Array(buf) : buf),
+    void 0,
+    rnd
+  );
+}
+export {
+  permutation
+};

package/rotate.d.ts

@@ -11,7 +11,7 @@ import type { TypedArray } from "@thi.ng/api";
  * @param buf
  * @param num
  */
-export declare const rotate: <T>(buf: Array<T>, num: number) => T[];
+export declare const rotate: <T>(buf: T[], num: number) => T[];
 /**
  * Same as {@link rotate}, but for optimized for typed arrays!
  *

package/swizzle.d.ts

@@ -1,4 +1,4 @@
-import type { Fn } from "@thi.ng/api";
+import type { Fn, NumericArray } from "@thi.ng/api";
 /**
  * Returns optimized function to immutably select, repeat, reshape and /
  * or reorder array / object values in the specified index order.
@@ -42,5 +42,5 @@ import type { Fn } from "@thi.ng/api";
  *
  * @param order - indices
  */
-export declare const swizzle: <T>(order: string | PropertyKey[]) => Fn<T, any[]>;
+export declare const swizzle: <T>(order: string | PropertyKey[] | NumericArray) => Fn<T, any[]>;
 //# sourceMappingURL=swizzle.d.ts.map