radashi 12.5.1 → 12.6.1

package/README.md

@@ -9,7 +9,7 @@
   <a href="https://app.codecov.io/gh/radashi-org/radashi/tree/main/src"><img src="https://img.shields.io/codecov/c/github/radashi-org/radashi?logo=codecov" alt="Codecov" /></a>
   <a href="https://biomejs.dev/"><img src="https://img.shields.io/badge/code_style-biome.js-blue?logo=biome" alt="Code Style: Biome.js" /></a>
   <a href="https://github.com/radashi-org/radashi/discussions"><img src="https://img.shields.io/github/discussions/radashi-org/radashi?logo=github" alt="GitHub Discussions" /></a>
-  <a href="https://app.gitter.im/#/room/#radashi:gitter.im"><img src="https://badges.gitter.im/join_chat.svg" alt="Gitter.im" /></a>
+  <a href="https://jsr.io/@radashi-org/radashi"><img src="https://jsr.io/badges/@radashi-org/radashi" alt="JSR.io" /></a>
   <p align="center">
     <span>English</span> | <a href="./README-pt_br.md">Português</a>
   </p>
@@ -100,13 +100,13 @@ deno add jsr:@radashi-org/radashi
 
 ## FAQ
 
-- **“I need XYZ, but Radashi doesn't have it.”**  
+- **“I need XYZ, but Radashi doesn't have it.”**
   If you have a need not met by our current set of functions, we want to hear about it. [Start a discussion](https://github.com/orgs/radashi-org/discussions/new?category=ideas) so we can explore the idea together!
 
-- **What does “community first” mean exactly?**  
+- **What does “community first” mean exactly?**
   It means putting the community's needs first, leaning towards adding support for popular use cases, as opposed to being strictly minimalist. As such, your feedback is very welcome and we value your perspective. Specifically, we want you to [contribute your viewpoint](https://github.com/orgs/radashi-org/discussions/categories/rfcs?discussions_q=is%3Aopen+category%3ARFCs) to discussions in our RFCs category.
 
-- **Are my contributions welcome?**  
+- **Are my contributions welcome?**
   Yes! Pull requests are encouraged, but please keep them small and focused. Sweeping changes are discouraged and won't be merged (unless the rationale's been thoroughly discussed).
 
   Please review _“The ethos of Radashi”_ before submitting a pull request:
@@ -115,35 +115,35 @@ deno add jsr:@radashi-org/radashi
     <img src="https://github.com/radashi-org/radashi/raw/main/.github/img/ethos-button.png" alt="The ethos of Radashi" width="250px" />
   </a>
 
-- **Can I help you maintain this?**  
+- **Can I help you maintain this?**
   Yes! I'll add you as a contributor to the repository. You can review pull requests and help with triage. With time, you may earn the ability to merge approved PRs.
 
   <a href="https://github.com/orgs/radashi-org/discussions/4">
     <img src="https://github.com/radashi-org/radashi/raw/main/.github/img/apply-button.png" alt="Apply to join the Radashi team" width="250px" />
   </a>
 
-- **Is backwards compatibility a goal?**  
+- **Is backwards compatibility a goal?**
   Yes! We want the transition from `radash` to this library to be smooth. If you're coming from Radash, we recommend installing `radashi@^12`. This version will continue to receive backported fixes even after Radashi v13 is released. You can upgrade to the latest major version when you're ready.
 
-- **Automatic releases**  
+- **Automatic releases**
   To ensure contributions are quickly rolled out, we have the following automatic processes:
 
-  - **Patch releases**  
+  - **Patch releases**
     Whenever the `main` branch receives a `^fix:` commit, a patch release is immediately published to NPM.
 
-  - **Beta releases**  
+  - **Beta releases**
     Pull requests that add a new feature can be labeled with `prerelease` by a maintainer. This triggers a GitHub workflow that attempts to copy the PR into the `beta` branch. If that succeeds, a beta release is immediately published to NPM.
 
     Installing `radashi@beta` will always fetch the latest beta release. Although the name "beta" may suggest unstable code, PRs need tests to be eligible for a prerelease.
 
     Beta releases provide quick access to new features without waiting for a regular release cycle. They're also an opportunity for the community to provide feedback before the feature is released to the `main` branch.
 
-  - **"Next" releases**  
+  - **"Next" releases**
     Pull requests with breaking changes can also be labeled with `prerelease` by a maintainer. In this case, the PR is copied into the `next` branch. If that succeeds, a "next" release is published to NPM.
 
     Installing `radashi@next` will always fetch the latest "next" release.
 
-- **Release cycle**  
+- **Release cycle**
   Radashi is expected to release a new minor or major version on a monthly basis, but releases are not on a strict schedule. Pre-releases are available for testing and feedback before the final release.
 
 <img src="https://github.com/radashi-org/radashi/raw/main/.github/img/rule.png" width="100%" />

package/dist/radashi.cjs

@@ -132,17 +132,15 @@ function fork(array, condition) {
 
 // src/array/group.ts
 function group(array, getGroupId) {
-  return array.reduce(
-    (acc, item) => {
-      const groupId = getGroupId(item);
-      if (!acc[groupId]) {
-        acc[groupId] = [];
-      }
-      acc[groupId].push(item);
-      return acc;
-    },
-    {}
-  );
+  const groups = /* @__PURE__ */ Object.create(null);
+  array.forEach((item, index) => {
+    const groupId = getGroupId(item, index);
+    if (!groups[groupId]) {
+      groups[groupId] = [];
+    }
+    groups[groupId].push(item);
+  });
+  return groups;
 }
 
 // src/array/intersects.ts
@@ -404,19 +402,6 @@ function zipToObject(keys2, values) {
   );
 }
 
-// src/async/AggregateError.ts
-var AggregateErrorOrPolyfill = /* @__PURE__ */ (() => globalThis.AggregateError ?? class AggregateError extends Error {
-  constructor(errors = []) {
-    var _a, _b;
-    super();
-    const name = ((_a = errors.find((e) => e.name)) == null ? void 0 : _a.name) ?? "";
-    this.name = `AggregateError(${name}...)`;
-    this.message = `AggregateError with ${errors.length} errors`;
-    this.stack = ((_b = errors.find((e) => e.stack)) == null ? void 0 : _b.stack) ?? this.stack;
-    this.errors = errors;
-  }
-})();
-
 // src/async/all.ts
 async function all(input) {
   const errors = [];
@@ -549,6 +534,20 @@ async function parallel(options, array, func) {
   return results.map((r) => r.result);
 }
 
+// src/async/queueByKey.ts
+function queueByKey(asyncFn, keyFn) {
+  const queues = /* @__PURE__ */ new Map();
+  return async (...args) => {
+    const key = keyFn(...args);
+    const next = () => asyncFn(...args);
+    const queue = (queues.get(key) || Promise.resolve()).then(next, next);
+    queues.set(key, queue);
+    const cleanup = () => queues.get(key) === queue && queues.delete(key);
+    queue.then(cleanup, cleanup);
+    return queue;
+  };
+}
+
 // src/async/reduce.ts
 async function reduce(array, reducer, initialValue) {
   if (!array) {
@@ -603,14 +602,6 @@ function sleep(milliseconds) {
   return new Promise((res) => setTimeout(res, milliseconds));
 }
 
-// src/async/TimeoutError.ts
-var TimeoutError = class extends Error {
-  constructor(message) {
-    super(message ?? "Operation timed out");
-    this.name = "TimeoutError";
-  }
-};
-
 // src/async/timeout.ts
 function timeout(ms, error) {
   return new Promise(
@@ -787,6 +778,17 @@ function partob(fn, argObj) {
   return (restObj) => fn({ ...argObj, ...restObj });
 }
 
+// src/curry/promiseChain.ts
+function promiseChain(...funcs) {
+  return async (...args) => {
+    let result = await funcs[0](...args);
+    for (let i = 1; i < funcs.length; i++) {
+      result = await funcs[i](result);
+    }
+    return result;
+  };
+}
+
 // src/curry/proxied.ts
 function proxied(handler) {
   return new Proxy(
@@ -898,6 +900,16 @@ function min(array, getter) {
   return array.reduce((a, b) => get2(a) < get2(b) ? a : b);
 }
 
+// src/number/parseDuration.ts
+function parseDuration(duration, options) {
+  return new DurationParser(options).parse(duration);
+}
+
+// src/number/parseQuantity.ts
+function parseQuantity(quantity, options) {
+  return new QuantityParser(options).parse(quantity);
+}
+
 // src/number/range.ts
 function* range(startOrLength, end, valueOrMapper = (i) => i, step = 1) {
   const mapper = isFunction(valueOrMapper) ? valueOrMapper : () => valueOrMapper;
@@ -1369,6 +1381,192 @@ function upperize(obj) {
   return mapKeys(obj, (k) => k.toUpperCase());
 }
 
+// src/oop/AggregateError.ts
+var AggregateErrorOrPolyfill = /* @__PURE__ */ (() => globalThis.AggregateError ?? class AggregateError extends Error {
+  constructor(errors = []) {
+    var _a, _b;
+    super();
+    const name = ((_a = errors.find((e) => e.name)) == null ? void 0 : _a.name) ?? "";
+    this.name = `AggregateError(${name}...)`;
+    this.message = `AggregateError with ${errors.length} errors`;
+    this.stack = ((_b = errors.find((e) => e.stack)) == null ? void 0 : _b.stack) ?? this.stack;
+    this.errors = errors;
+  }
+})();
+
+// src/oop/QuantityParser.ts
+var QuantityParser = class {
+  constructor({ units, short }) {
+    this.units = units;
+    this.short = short;
+  }
+  /**
+   * Parse a quantity string into its numeric value
+   *
+   * @throws {Error} If the quantity string is invalid or contains an unknown unit
+   */
+  parse(quantity) {
+    var _a;
+    const match = quantity.match(/^(-?\d+(?:\.\d+)?) ?(\w+)?s?$/);
+    if (!match) {
+      throw new Error(`Invalid quantity, cannot parse: ${quantity}`);
+    }
+    let unit = match[2];
+    unit = ((_a = this.short) == null ? void 0 : _a[unit]) || unit;
+    const count = Number.parseFloat(match[1]);
+    if (Math.abs(count) > 1 && unit.endsWith("s")) {
+      unit = unit.substring(0, unit.length - 1);
+    }
+    if (!this.units[unit]) {
+      throw new Error(
+        `Invalid unit: ${unit}, makes sure it is one of: ${Object.keys(this.units).join(", ")}`
+      );
+    }
+    return count * this.units[unit];
+  }
+};
+
+// src/oop/DurationParser.ts
+var _DurationParser = class _DurationParser extends QuantityParser {
+  constructor(options) {
+    super({
+      units: {
+        ..._DurationParser.units,
+        ...options == null ? void 0 : options.units
+      },
+      short: {
+        ..._DurationParser.shortUnits,
+        ...options == null ? void 0 : options.short
+      }
+    });
+  }
+};
+_DurationParser.units = {
+  week: 6048e5,
+  day: 864e5,
+  hour: 36e5,
+  minute: 6e4,
+  second: 1e3,
+  millisecond: 1
+};
+_DurationParser.shortUnits = {
+  w: "week",
+  d: "day",
+  h: "hour",
+  m: "minute",
+  s: "second",
+  ms: "millisecond"
+};
+var DurationParser = _DurationParser;
+
+// src/oop/Semaphore.ts
+var SemaphorePermit = class {
+  constructor(semaphore, request, weight) {
+    this.semaphore = semaphore;
+    this.request = request;
+    this.weight = weight;
+  }
+  /**
+   * Releases this permit back to the semaphore, allowing another
+   * operation to acquire it.
+   */
+  release() {
+    this.semaphore.release(this);
+    this.release = noop;
+  }
+};
+var Semaphore = class {
+  /**
+   * Creates a new semaphore with the specified capacity.
+   * @param maxCapacity Maximum number of permits that can be issued simultaneously
+   */
+  constructor(maxCapacity) {
+    this.maxCapacity = maxCapacity;
+    this.queue = [];
+    if (maxCapacity <= 0) {
+      throw new Error("maxCapacity must be > 0");
+    }
+    this.capacity = maxCapacity;
+  }
+  /**
+   * Number of pending acquisition requests.
+   */
+  get queueLength() {
+    return this.queue.length;
+  }
+  /**
+   * Acquires a permit from this semaphore, waiting if necessary until
+   * one becomes available.
+   * @param options.signal - The signal to abort the acquisition
+   * @param options.weight - The weight of the permit to acquire
+   * @returns A promise that resolves to a permit when one is
+   * available
+   */
+  async acquire({
+    signal,
+    weight = 1
+  } = {}) {
+    if (weight <= 0) {
+      throw new Error("weight must be > 0");
+    }
+    if (weight > this.maxCapacity) {
+      throw new Error("weight must be \u2264 maxCapacity");
+    }
+    const request = withResolvers();
+    const permit = new SemaphorePermit(this, request, weight);
+    if (signal) {
+      const abort = () => {
+        const index = this.queue.indexOf(permit);
+        if (index >= 0) {
+          this.queue.splice(index, 1);
+          request.reject(signal.reason);
+        }
+      };
+      signal.addEventListener("abort", abort);
+      const cleanup = () => {
+        signal.removeEventListener("abort", abort);
+      };
+      request.promise.then(cleanup, cleanup);
+    }
+    if (this.capacity < weight) {
+      this.queue.push(permit);
+      await request.promise;
+    } else {
+      this.capacity -= weight;
+    }
+    return permit;
+  }
+  /**
+   * Rejects all pending acquisition requests.
+   */
+  reject(error) {
+    this.acquire = () => Promise.reject(error);
+    this.queue.forEach((permit) => permit.request.reject(error));
+    this.queue = [];
+  }
+  /**
+   * Releases a permit back to the semaphore, increasing capacity and
+   * potentially fulfilling a pending acquisition request.
+   */
+  release(permit) {
+    this.capacity += permit.weight;
+    const nextPermit = this.queue[0];
+    if (nextPermit && this.capacity >= nextPermit.weight) {
+      this.capacity -= nextPermit.weight;
+      this.queue.shift();
+      nextPermit.request.resolve();
+    }
+  }
+};
+
+// src/oop/TimeoutError.ts
+var TimeoutError = class extends Error {
+  constructor(message) {
+    super(message ?? "Operation timed out");
+    this.name = "TimeoutError";
+  }
+};
+
 // src/random/draw.ts
 function draw(array) {
   const max2 = array.length;
@@ -1526,6 +1724,19 @@ function dedent(text, ...values) {
   return output.replace(/^[ \t]*\n|\n[ \t]*$/g, "");
 }
 
+// src/string/escapeHTML.ts
+var htmlCharacters = /[&<>"']/g;
+var replacements = {
+  "&": "&amp;",
+  "<": "&lt;",
+  ">": "&gt;",
+  '"': "&quot;",
+  "'": "&#39;"
+};
+function escapeHTML(input) {
+  return input.replace(htmlCharacters, (char) => replacements[char]);
+}
+
 // src/string/pascal.ts
 function pascal(str) {
   if (!str) {
@@ -1636,6 +1847,13 @@ function trim(str, charsToTrim = " ") {
   return str.replace(regex, "");
 }
 
+// src/typed/assert.ts
+function assert(condition, message) {
+  if (!condition) {
+    throw message instanceof Error ? message : new Error(message ?? "Assertion failed");
+  }
+}
+
 // src/typed/isArray.ts
 var isArray = /* @__PURE__ */ (() => Array.isArray)();
 
@@ -1851,11 +2069,16 @@ function isWeakSet(value) {
 
 exports.AggregateError = AggregateErrorOrPolyfill;
 exports.DefaultCloningStrategy = DefaultCloningStrategy;
+exports.DurationParser = DurationParser;
 exports.FastCloningStrategy = FastCloningStrategy;
+exports.QuantityParser = QuantityParser;
+exports.Semaphore = Semaphore;
+exports.SemaphorePermit = SemaphorePermit;
 exports.TimeoutError = TimeoutError;
 exports.all = all;
 exports.alphabetical = alphabetical;
 exports.always = always;
+exports.assert = assert;
 exports.assign = assign;
 exports.boil = boil;
 exports.callable = callable;
@@ -1882,6 +2105,7 @@ exports.dedent = dedent;
 exports.defer = defer;
 exports.diff = diff;
 exports.draw = draw;
+exports.escapeHTML = escapeHTML;
 exports.filterKey = filterKey;
 exports.first = first;
 exports.flat = flat;
@@ -1948,12 +2172,16 @@ exports.objectify = objectify;
 exports.omit = omit;
 exports.once = once;
 exports.parallel = parallel;
+exports.parseDuration = parseDuration;
+exports.parseQuantity = parseQuantity;
 exports.partial = partial;
 exports.partob = partob;
 exports.pascal = pascal;
 exports.pick = pick;
 exports.pluck = pluck;
+exports.promiseChain = promiseChain;
 exports.proxied = proxied;
+exports.queueByKey = queueByKey;
 exports.random = random;
 exports.range = range;
 exports.reduce = reduce;