@fluixi/utils 1.0.0-alpha.100

package/dist/lib/object/sort.js

@@ -0,0 +1,298 @@
+import { isPlainObject } from './utils.js';
+// ─── Internal helpers ─────────────────────────────────────────────────────────
+/** Read a value via dot-notation path, e.g. `'address.city'`. */
+function getAtPath(obj, path) {
+    if (obj == null)
+        return undefined;
+    let cur = obj;
+    for (const segment of path.split('.')) {
+        if (cur == null)
+            return undefined;
+        cur = cur[segment];
+    }
+    return cur;
+}
+/**
+ * Natural, type-aware comparison.
+ * Returns negative / zero / positive like `Array.prototype.sort` expects.
+ * Handles: null/undefined (always pushed last), NaN, Date, boolean, number, string.
+ * Falls back to locale-aware string coercion for mixed / unknown types.
+ */
+function compareValues(a, b, locale, localeOptions) {
+    // null / undefined: treated as "greater than anything" so they sink to the end
+    const aN = a == null;
+    const bN = b == null;
+    if (aN && bN)
+        return 0;
+    if (aN)
+        return 1;
+    if (bN)
+        return -1;
+    // NaN: sink below null
+    const aNaN = typeof a === 'number' && Number.isNaN(a);
+    const bNaN = typeof b === 'number' && Number.isNaN(b);
+    if (aNaN && bNaN)
+        return 0;
+    if (aNaN)
+        return 1;
+    if (bNaN)
+        return -1;
+    // Date
+    if (a instanceof Date && b instanceof Date) {
+        return a.getTime() - b.getTime();
+    }
+    // Boolean (false < true)
+    if (typeof a === 'boolean' && typeof b === 'boolean') {
+        return (a === b ? 0 : a ? 1 : -1);
+    }
+    // Number (covers BigInt with coercion below)
+    if (typeof a === 'number' && typeof b === 'number') {
+        return a - b;
+    }
+    // String: locale-aware
+    if (typeof a === 'string' && typeof b === 'string') {
+        return a.localeCompare(b, locale, localeOptions);
+    }
+    // Fallback: coerce both to string
+    return String(a).localeCompare(String(b), locale, localeOptions);
+}
+/** Build a single numeric direction multiplier for the i-th sort key. */
+function dirFor(order, i) {
+    const o = Array.isArray(order) ? (order[i] ?? 'asc') : (order ?? 'asc');
+    return o === 'desc' ? -1 : 1;
+}
+// ─── Core sort functions ──────────────────────────────────────────────────────
+/**
+ * Sort a flat array of primitives, Dates, or mixed values using natural
+ * comparison.  Respects `order`, `locale`, `localeOptions`, and `nullsLast`.
+ */
+function sortPrimitiveArray(arr, options) {
+    const { order, locale, localeOptions, nullsLast = true } = options;
+    const dir = dirFor(order, 0);
+    return arr.slice().sort((a, b) => {
+        const aN = a == null;
+        const bN = b == null;
+        if (aN && bN)
+            return 0;
+        if (aN)
+            return nullsLast ? 1 : -1;
+        if (bN)
+            return nullsLast ? -1 : 1;
+        return compareValues(a, b, locale, localeOptions) * dir;
+    });
+}
+/**
+ * Sort an array of objects by one or more key paths.
+ * Keys are compared left-to-right; the next key is only consulted when all
+ * previous keys produced a tie.
+ */
+function sortObjectArray(arr, keys, options) {
+    const { order, locale, localeOptions, nullsLast = true, comparator } = options;
+    if (comparator) {
+        return arr.slice().sort(comparator);
+    }
+    return arr.slice().sort((a, b) => {
+        for (let i = 0; i < keys.length; i++) {
+            const aVal = getAtPath(a, keys[i]);
+            const bVal = getAtPath(b, keys[i]);
+            const aN = aVal == null;
+            const bN = bVal == null;
+            if (aN && bN)
+                continue;
+            if (aN)
+                return nullsLast ? 1 : -1;
+            if (bN)
+                return nullsLast ? -1 : 1;
+            const cmp = compareValues(aVal, bVal, locale, localeOptions);
+            if (cmp !== 0)
+                return cmp * dirFor(order, i);
+        }
+        return 0;
+    });
+}
+/**
+ * Return a new plain object whose own keys are sorted alphabetically, with
+ * `priorityKeys` pinned to the front.  Values are left untouched unless
+ * `deep` is set.
+ */
+function sortRecord(record, options) {
+    const { order, priorityKeys = [], locale, localeOptions, deep } = options;
+    const dir = dirFor(order, 0);
+    const prioritySet = new Set(priorityKeys);
+    const rest = Object.keys(record).filter((k) => !prioritySet.has(k));
+    rest.sort((a, b) => a.localeCompare(b, locale, localeOptions) * dir);
+    const ordered = [...priorityKeys.filter((k) => k in record), ...rest];
+    const result = {};
+    for (const key of ordered) {
+        result[key] = deep ? sortDeep(record[key], options) : record[key];
+    }
+    return result;
+}
+/**
+ * Recursively sort a value: sorts arrays in place (returning new array) and
+ * sorts record-object keys.  Primitives and non-plain objects are returned
+ * unchanged.
+ */
+function sortDeep(value, options) {
+    if (Array.isArray(value)) {
+        // Deep-sort elements first, then sort the array itself
+        const deepSorted = value.map((item) => sortDeep(item, options));
+        return sortArrayValue(deepSorted, options);
+    }
+    if (isPlainObject(value)) {
+        return sortRecord(value, options);
+    }
+    return value;
+}
+/**
+ * Apply an explicit index permutation to an array.
+ *
+ * `indices[i]` names the source index that appears at position `i` in the
+ * output.  Input elements not named by any index are appended at the end in
+ * their original relative order.  Out-of-range indices are ignored.
+ */
+function applyIndices(arr, indices) {
+    const len = arr.length;
+    const used = new Set();
+    const result = [];
+    for (const idx of indices) {
+        if (idx >= 0 && idx < len && !used.has(idx)) {
+            result.push(arr[idx]);
+            used.add(idx);
+        }
+    }
+    // Append any elements not covered by the permutation
+    for (let i = 0; i < len; i++) {
+        if (!used.has(i))
+            result.push(arr[i]);
+    }
+    return result;
+}
+/**
+ * Dispatch array sorting to the appropriate strategy based on the options
+ * present: explicit index permutation → value-based sort → direction-only.
+ */
+function sortArrayValue(arr, options) {
+    const { by, comparator, indices, order } = options;
+    // ── Explicit index permutation ───────────────────────────────────────────
+    if (indices) {
+        const permuted = applyIndices(arr, indices);
+        // order: 'desc' reverses the permuted result
+        return dirFor(order, 0) === -1 ? permuted.reverse() : permuted;
+    }
+    // ── Custom comparator ────────────────────────────────────────────────────
+    if (comparator) {
+        return arr.slice().sort(comparator);
+    }
+    // ── Key-based sort ───────────────────────────────────────────────────────
+    if (by) {
+        const keys = Array.isArray(by) ? by : [by];
+        return sortObjectArray(arr, keys, options);
+    }
+    // ── No key: object arrays are ordered by index position ──────────────────
+    // asc  = natural order (unchanged)
+    // desc = reverse the array
+    const firstReal = arr.find((x) => x != null);
+    if (firstReal != null && isPlainObject(firstReal)) {
+        return dirFor(order, 0) === -1 ? arr.slice().reverse() : arr.slice();
+    }
+    // ── Primitive array ──────────────────────────────────────────────────────
+    return sortPrimitiveArray(arr, options);
+}
+export function sort(input, options = {}) {
+    const { deep } = options;
+    if (Array.isArray(input)) {
+        const items = deep
+            ? input.map((item) => sortDeep(item, options))
+            : input;
+        return sortArrayValue(items, options);
+    }
+    if (isPlainObject(input)) {
+        return sortRecord(input, options);
+    }
+    return input;
+}
+// ─── Convenience helpers ──────────────────────────────────────────────────────
+/**
+ * Sort an array of objects by one or more key paths, returning a new array.
+ * Shorthand for `sort(arr, { by: key, order })`.
+ *
+ * @example
+ * sortBy(users, 'name')
+ * sortBy(users, ['lastName', 'firstName'], 'asc')
+ * sortBy(products, 'price', 'desc')
+ */
+export function sortBy(arr, by, order = 'asc', options = {}) {
+    return sort(arr, { ...options, by, order });
+}
+/**
+ * Sort the keys of a record object, returning a new object.
+ * Shorthand for `sort(record, { order, priorityKeys, deep })`.
+ *
+ * @example
+ * sortKeys({ z: 1, a: 2 })                        // { a: 2, z: 1 }
+ * sortKeys(obj, { priorityKeys: ['id', 'type'] })
+ * sortKeys(tree, { deep: true })
+ */
+export function sortKeys(record, options = {}) {
+    return sort(record, options);
+}
+/**
+ * Move an element from one index to another, shifting the elements in between.
+ * Returns a new array; the original is not mutated.
+ *
+ * - Clamps `from` and `to` to valid array bounds.
+ * - When `from === to` the original array is returned as-is (same reference).
+ *
+ * @example
+ * move(['a','b','c','d'], 0, 2)  // ['b','c','a','d']  (first → third)
+ * move(['a','b','c','d'], 3, 1)  // ['a','d','b','c']  (last  → second)
+ * move(users, fromIndex, toIndex)
+ */
+export function move(arr, from, to) {
+    const len = arr.length;
+    if (len === 0)
+        return arr.slice();
+    const f = Math.max(0, Math.min(len - 1, from));
+    const t = Math.max(0, Math.min(len - 1, to));
+    if (f === t)
+        return arr.slice();
+    const result = arr.slice();
+    const [item] = result.splice(f, 1);
+    result.splice(t, 0, item);
+    return result;
+}
+/**
+ * Swap two elements by index, returning a new array.
+ * The original array is not mutated.
+ * Out-of-range indices throw a `RangeError`.
+ *
+ * @example
+ * swap(['a','b','c'], 0, 2)  // ['c','b','a']
+ * swap(users, 1, 3)
+ */
+export function swap(arr, i, j) {
+    const len = arr.length;
+    if (i < 0 || i >= len)
+        throw new RangeError(`swap: index ${i} out of range`);
+    if (j < 0 || j >= len)
+        throw new RangeError(`swap: index ${j} out of range`);
+    if (i === j)
+        return arr.slice();
+    const result = arr.slice();
+    result[i] = arr[j];
+    result[j] = arr[i];
+    return result;
+}
+/**
+ * Reorder an array by providing the full desired sequence of source indices.
+ * Shorthand for `sort(arr, { indices })`.
+ *
+ * @example
+ * reorder(['a','b','c'], [2, 0, 1])          // ['c','a','b']
+ * reorder(tabs, newIndexOrder)               // apply UI drag-and-drop result
+ * reorder(rows, [3,1,0,2], 'desc')           // permute then reverse
+ */
+export function reorder(arr, indices, order = 'asc') {
+    return sort(arr, { indices, order });
+}

package/dist/lib/object/sort.mjs

@@ -0,0 +1,186 @@
+// src/lib/object/utils.ts
+function isPlainObject(v) {
+  if (typeof v !== "object" || v === null) return false;
+  const proto = Object.getPrototypeOf(v);
+  return proto === Object.prototype || proto === null;
+}
+
+// src/lib/object/sort.ts
+function getAtPath(obj, path) {
+  if (obj == null) return void 0;
+  let cur = obj;
+  for (const segment of path.split(".")) {
+    if (cur == null) return void 0;
+    cur = cur[segment];
+  }
+  return cur;
+}
+function compareValues(a, b, locale, localeOptions) {
+  const aN = a == null;
+  const bN = b == null;
+  if (aN && bN) return 0;
+  if (aN) return 1;
+  if (bN) return -1;
+  const aNaN = typeof a === "number" && Number.isNaN(a);
+  const bNaN = typeof b === "number" && Number.isNaN(b);
+  if (aNaN && bNaN) return 0;
+  if (aNaN) return 1;
+  if (bNaN) return -1;
+  if (a instanceof Date && b instanceof Date) {
+    return a.getTime() - b.getTime();
+  }
+  if (typeof a === "boolean" && typeof b === "boolean") {
+    return a === b ? 0 : a ? 1 : -1;
+  }
+  if (typeof a === "number" && typeof b === "number") {
+    return a - b;
+  }
+  if (typeof a === "string" && typeof b === "string") {
+    return a.localeCompare(b, locale, localeOptions);
+  }
+  return String(a).localeCompare(String(b), locale, localeOptions);
+}
+function dirFor(order, i) {
+  const o = Array.isArray(order) ? order[i] ?? "asc" : order ?? "asc";
+  return o === "desc" ? -1 : 1;
+}
+function sortPrimitiveArray(arr, options) {
+  const { order, locale, localeOptions, nullsLast = true } = options;
+  const dir = dirFor(order, 0);
+  return arr.slice().sort((a, b) => {
+    const aN = a == null;
+    const bN = b == null;
+    if (aN && bN) return 0;
+    if (aN) return nullsLast ? 1 : -1;
+    if (bN) return nullsLast ? -1 : 1;
+    return compareValues(a, b, locale, localeOptions) * dir;
+  });
+}
+function sortObjectArray(arr, keys, options) {
+  const { order, locale, localeOptions, nullsLast = true, comparator } = options;
+  if (comparator) {
+    return arr.slice().sort(comparator);
+  }
+  return arr.slice().sort((a, b) => {
+    for (let i = 0; i < keys.length; i++) {
+      const aVal = getAtPath(a, keys[i]);
+      const bVal = getAtPath(b, keys[i]);
+      const aN = aVal == null;
+      const bN = bVal == null;
+      if (aN && bN) continue;
+      if (aN) return nullsLast ? 1 : -1;
+      if (bN) return nullsLast ? -1 : 1;
+      const cmp = compareValues(aVal, bVal, locale, localeOptions);
+      if (cmp !== 0) return cmp * dirFor(order, i);
+    }
+    return 0;
+  });
+}
+function sortRecord(record, options) {
+  const { order, priorityKeys = [], locale, localeOptions, deep } = options;
+  const dir = dirFor(order, 0);
+  const prioritySet = new Set(priorityKeys);
+  const rest = Object.keys(record).filter((k) => !prioritySet.has(k));
+  rest.sort(
+    (a, b) => a.localeCompare(b, locale, localeOptions) * dir
+  );
+  const ordered = [...priorityKeys.filter((k) => k in record), ...rest];
+  const result = {};
+  for (const key of ordered) {
+    result[key] = deep ? sortDeep(record[key], options) : record[key];
+  }
+  return result;
+}
+function sortDeep(value, options) {
+  if (Array.isArray(value)) {
+    const deepSorted = value.map((item) => sortDeep(item, options));
+    return sortArrayValue(deepSorted, options);
+  }
+  if (isPlainObject(value)) {
+    return sortRecord(value, options);
+  }
+  return value;
+}
+function applyIndices(arr, indices) {
+  const len = arr.length;
+  const used = /* @__PURE__ */ new Set();
+  const result = [];
+  for (const idx of indices) {
+    if (idx >= 0 && idx < len && !used.has(idx)) {
+      result.push(arr[idx]);
+      used.add(idx);
+    }
+  }
+  for (let i = 0; i < len; i++) {
+    if (!used.has(i)) result.push(arr[i]);
+  }
+  return result;
+}
+function sortArrayValue(arr, options) {
+  const { by, comparator, indices, order } = options;
+  if (indices) {
+    const permuted = applyIndices(arr, indices);
+    return dirFor(order, 0) === -1 ? permuted.reverse() : permuted;
+  }
+  if (comparator) {
+    return arr.slice().sort(comparator);
+  }
+  if (by) {
+    const keys = Array.isArray(by) ? by : [by];
+    return sortObjectArray(arr, keys, options);
+  }
+  const firstReal = arr.find((x) => x != null);
+  if (firstReal != null && isPlainObject(firstReal)) {
+    return dirFor(order, 0) === -1 ? arr.slice().reverse() : arr.slice();
+  }
+  return sortPrimitiveArray(arr, options);
+}
+function sort(input, options = {}) {
+  const { deep } = options;
+  if (Array.isArray(input)) {
+    const items = deep ? input.map((item) => sortDeep(item, options)) : input;
+    return sortArrayValue(items, options);
+  }
+  if (isPlainObject(input)) {
+    return sortRecord(input, options);
+  }
+  return input;
+}
+function sortBy(arr, by, order = "asc", options = {}) {
+  return sort(arr, { ...options, by, order });
+}
+function sortKeys(record, options = {}) {
+  return sort(record, options);
+}
+function move(arr, from, to) {
+  const len = arr.length;
+  if (len === 0) return arr.slice();
+  const f = Math.max(0, Math.min(len - 1, from));
+  const t = Math.max(0, Math.min(len - 1, to));
+  if (f === t) return arr.slice();
+  const result = arr.slice();
+  const [item] = result.splice(f, 1);
+  result.splice(t, 0, item);
+  return result;
+}
+function swap(arr, i, j) {
+  const len = arr.length;
+  if (i < 0 || i >= len) throw new RangeError(`swap: index ${i} out of range`);
+  if (j < 0 || j >= len) throw new RangeError(`swap: index ${j} out of range`);
+  if (i === j) return arr.slice();
+  const result = arr.slice();
+  result[i] = arr[j];
+  result[j] = arr[i];
+  return result;
+}
+function reorder(arr, indices, order = "asc") {
+  return sort(arr, { indices, order });
+}
+export {
+  move,
+  reorder,
+  sort,
+  sortBy,
+  sortKeys,
+  swap
+};