@dxos/util 0.8.3 → 0.8.4-main.1068cf700f

package/src/string.ts

@@ -12,3 +12,39 @@ export const capitalize = (str: string): string => {
 
   return str.charAt(0).toUpperCase() + str.slice(1);
 };
+
+/**
+ * Remove leading space from multi-line strings.
+ */
+export function trim(strings: TemplateStringsArray, ...values: any[]) {
+  // First, build the raw result with relative indentation.
+  const raw = strings.reduce((out, str, i) => {
+    out += str;
+    if (i < values.length) {
+      const match = str.match(/(^|\n)([ \t]*)$/);
+      const baseIndent = match ? match[2] : '';
+      const val = String(values[i]).replace(/\r?\n/g, '\n' + baseIndent);
+      out += val;
+    }
+    return out;
+  }, '');
+
+  // Split into lines and trim leading/trailing blank lines.
+  const lines = raw.split('\n');
+
+  while (lines.length && !lines[0].trim()) lines.shift();
+  while (lines.length && !lines[lines.length - 1].trim()) lines.pop();
+
+  // Find smallest indent across all non-blank lines.
+  const minIndent = Math.min(...lines.filter((l) => l.trim()).map((l) => l.match(/^[ \t]*/)?.[0].length ?? 0));
+
+  // Remove that indent from all lines.
+  return lines.map((l) => l.slice(minIndent)).join('\n');
+}
+
+// From https://stackoverflow.com/a/67243723/2804332
+/**
+ * Converts a string to kebab case.
+ */
+export const kebabize = (str: string) =>
+  str.replace(/[A-Z]+(?![a-z])|[A-Z]/g, ($, ofs) => (ofs ? '-' : '') + $.toLowerCase());

package/src/to-fallback.ts

@@ -194,17 +194,18 @@ export const keyToFallback = (key: PublicKey) => hexToFallback(key.toHex());
 // TODO(wittjosiah): Support non-hex strings (e.g. DIDs, UUIDs, etc.)
 export const hexToFallback = (hex: string) => toFallback(parseInt(hex, 16));
 
+// TODO(burdon): Rename?
 export const toFallback = (hash: number): FallbackValue => {
-  // Calculate total possible combinations of emoji and hue pairs
+  // Calculate total possible combinations of emoji and hue pairs.
   const totalCombinations = idEmoji.length * idHue.length;
 
-  // Get a deterministic index within the range of all possible combinations
+  // Get a deterministic index within the range of all possible combinations.
   const combinationIndex = hash % totalCombinations;
 
-  // Calculate which emoji to use based on the combination index
+  // Calculate which emoji to use based on the combination index.
   const emojiIndex = Math.floor(combinationIndex / idHue.length);
 
-  // Calculate which hue to use based on the combination index
+  // Calculate which hue to use based on the combination index.
   const hueIndex = combinationIndex % idHue.length;
 
   return {

package/src/tree.test.ts

@@ -6,7 +6,7 @@ import { describe, test } from 'vitest';
 
 import { PublicKey } from '@dxos/keys';
 
-import { stringifyTree, type TreeNode } from './tree';
+import { type TreeNode, stringifyTree } from './tree';
 
 describe('Tree logging', () => {
   test('simple', () => {

package/src/types.test.ts

@@ -4,7 +4,7 @@
 
 import { describe, expect, test } from 'vitest';
 
-import { isNonNullable } from './types';
+import { arrayMove, arraySwap, isNonNullable } from './types';
 
 describe('types', () => {
   test('filter', async () => {
@@ -12,4 +12,14 @@ describe('types', () => {
     const filtered: number[] = values.filter(isNonNullable);
     expect(filtered).to.deep.equal([1, 2, 3, 4]);
   });
+
+  test('arrayMove', () => {
+    expect(arrayMove([1, 2, 3, 4], 0, 2)).to.deep.equal([2, 3, 1, 4]);
+    expect(arrayMove([1, 2, 3, 4], 2, 0)).to.deep.equal([3, 1, 2, 4]);
+  });
+
+  test('arraySwap', () => {
+    expect(arraySwap([1, 2, 3, 4], 0, 2)).to.deep.equal([3, 2, 1, 4]);
+    expect(arraySwap([1, 2, 3, 4], 2, 0)).to.deep.equal([3, 2, 1, 4]);
+  });
 });

package/src/types.ts

@@ -12,13 +12,31 @@ export type MaybePromise<T> = T | Promise<T>;
 
 export type GuardedType<T> = T extends (value: any) => value is infer R ? R : never;
 
-export type DeepReadonly<T> = {
-  readonly [P in keyof T]: T[P] extends Record<string, any>
-    ? DeepReadonly<T[P]>
-    : T[P] extends Array<infer U>
-      ? ReadonlyArray<DeepReadonly<U>>
-      : T[P];
-};
+/**
+ * Removes readonly modifiers from top-level properties of T.
+ * Also converts readonly arrays at the top level to mutable arrays.
+ * For nested properties, mutability depends on the schema definition.
+ */
+export type ToMutable<T> = T extends object
+  ? { -readonly [K in keyof T]: T[K] extends readonly (infer U)[] ? U[] : T[K] }
+  : T;
+
+export type Intersection<Types extends readonly unknown[]> = Types extends [infer First, ...infer Rest]
+  ? First & Intersection<Rest>
+  : unknown;
+
+/**
+ * Recursively makes all properties of T readonly.
+ * Primitives (including branded types like `string & { __brand: true }`) are returned as-is.
+ * Arrays become ReadonlyArrays with deeply readonly elements.
+ */
+export type DeepReadonly<T> = T extends string | number | boolean | bigint | symbol | null | undefined
+  ? T // Primitives (including branded primitives) stay as-is.
+  : T extends Array<infer U>
+    ? ReadonlyArray<DeepReadonly<U>>
+    : T extends object
+      ? { readonly [P in keyof T]: DeepReadonly<T[P]> }
+      : T;
 
 export type DeepWriteable<T> = { -readonly [K in keyof T]: T[K] extends object ? DeepWriteable<T[K]> : T[K] };
 
@@ -48,7 +66,7 @@ export type Falsy = false | 0 | '' | null | undefined;
  * NOTE: To filter by type:
  * items.filter((item: any): item is RangeSet<Decoration> => item instanceof RangeSet)
  */
-export const isNotFalsy = <T>(value: T): value is Exclude<T, Falsy> => !!value;
+export const isTruthy = <T>(value: T): value is Exclude<T, Falsy> => !!value;
 export const isNonNullable = <T>(value: T | null | undefined): value is T => value != null;
 
 // TODO(burdon): Replace use of setTimeout everywhere?
@@ -104,9 +122,19 @@ export const sortKeys = <T extends object>(obj: T): T =>
     }, {} as T);
 
 /**
- * Swap position of element within array.
+ * Move element within array.
  */
-export const arrayMove = <T>(array: T[], from: number, to: number): Array<T> => {
+export const arrayMove = <T>(array: T[], from: number, to: number): T[] => {
   array.splice(to < 0 ? array.length + to : to, 0, array.splice(from, 1)[0]);
   return array;
 };
+
+/**
+ * Swap position of element within array.
+ */
+export function arraySwap<T>(array: T[], from: number, to: number): T[] {
+  const current = array[from];
+  array[from] = array[to];
+  array[to] = current;
+  return array;
+}

package/src/uint8array.test.ts

@@ -2,7 +2,7 @@
 // Copyright 2023 DXOS.org
 //
 
-import { test, expect, describe } from 'vitest';
+import { describe, expect, test } from 'vitest';
 
 import { arrayToBuffer, arrayToString, bufferToArray, stringToArray } from './uint8array';
 

package/src/unit.test.ts

@@ -0,0 +1,25 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { describe, it } from 'vitest';
+
+import { Unit } from './unit';
+
+describe('url', () => {
+  it('duration', ({ expect }) => {
+    const tests: [number, string][] = [
+      [0, '0ms'],
+      [1, '1ms'],
+      [1_000, '1.0s'],
+      [2_887, '2.9s'],
+      [1_000 * 60, '1m'],
+      [1_000 * 60 + 1_000 * 5, '1m 5s'],
+      [1_000 * 60 * 60 + 1_000 * 60 * 5, '1h 5m'],
+    ];
+
+    tests.forEach(([input, output]) => {
+      expect(Unit.Duration(input).toString(), input.toString()).toBe(output);
+    });
+  });
+});

package/src/unit.ts

@@ -0,0 +1,83 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export type Unit = {
+  symbol: string;
+  quotient: number;
+  precision?: number;
+};
+
+export type UnitValue<T> = {
+  unit: Unit;
+  value: number;
+  formattedValue: T;
+  toString: () => string;
+};
+
+export type UnitFormat<T = any> = (n: number, precision?: number) => UnitValue<T>;
+
+const createFormat = (unit: Unit): UnitFormat<string> => {
+  return (n: number, precision = unit.precision ?? 0) => {
+    const value = n / unit.quotient;
+    return {
+      unit,
+      value,
+      formattedValue: value.toFixed(precision),
+      toString: () => `${value.toFixed(precision)}${unit.symbol}`,
+    };
+  };
+};
+
+const MS_SECONDS = 1_000;
+const MS_MINUTES = 60 * MS_SECONDS;
+const MS_HOURS = 60 * MS_MINUTES;
+
+export const Unit: Record<string, UnitFormat> = {
+  // General.
+  Percent: createFormat({ symbol: '%', quotient: 1 / 100, precision: 2 }),
+  Thousand: createFormat({ symbol: 'k', quotient: 1_000, precision: 2 }),
+
+  // Bytes (note KB vs KiB).
+  Gigabyte: createFormat({ symbol: 'GB', quotient: 1_000 * 1_000 * 1_000, precision: 2 }),
+  Megabyte: createFormat({ symbol: 'MB', quotient: 1_000 * 1_000, precision: 2 }),
+  Kilobyte: createFormat({ symbol: 'KB', quotient: 1_000, precision: 2 }),
+  Byte: createFormat({ symbol: 'B', quotient: 1 }),
+
+  // Time.
+  Hour: createFormat({ symbol: 'h', quotient: MS_HOURS }),
+  Minute: createFormat({ symbol: 'm', quotient: MS_MINUTES }),
+  Second: createFormat({ symbol: 's', quotient: MS_SECONDS, precision: 1 }),
+  Millisecond: createFormat({ symbol: 'ms', quotient: 1 }),
+  Duration: (n: number) => {
+    const hours = Math.floor(n / MS_HOURS);
+    const minutes = Math.floor((n % MS_HOURS) / MS_MINUTES);
+    if (hours) {
+      const formattedValue = minutes ? `${hours}h ${minutes}m` : `${hours}h`;
+      return {
+        unit: { symbol: 'h', quotient: MS_HOURS },
+        value: hours,
+        formattedValue,
+        toString: () => formattedValue,
+      };
+    }
+
+    if (minutes) {
+      const seconds = (n - MS_MINUTES * minutes) / MS_SECONDS;
+      const formattedValue = seconds ? `${minutes}m ${seconds}s` : `${minutes}m`;
+      return {
+        unit: { symbol: 'm', quotient: MS_MINUTES },
+        value: minutes,
+        formattedValue,
+        toString: () => formattedValue,
+      };
+    }
+
+    const seconds = n >= MS_SECONDS;
+    if (seconds) {
+      return Unit.Second(n);
+    }
+
+    return Unit.Millisecond(n);
+  },
+} as const;

package/src/url.test.ts

@@ -0,0 +1,22 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { describe, it } from 'vitest';
+
+import { createUrl } from './url';
+
+describe('url', () => {
+  it('should create a url', ({ expect }) => {
+    const url = createUrl('https://example.com', {
+      i1: undefined,
+      i2: null,
+      p1: true,
+      p2: false,
+      p3: 'dxos',
+      p4: 100,
+    });
+
+    expect(url.toString()).toBe('https://example.com/?p1=true&p2=false&p3=dxos&p4=100');
+  });
+});

package/src/url.ts

@@ -0,0 +1,15 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+/**
+ * Normalize construction of URLs.
+ */
+export const createUrl = (url: URL | string, search?: Record<string, any | undefined>): URL => {
+  const base = typeof url === 'string' ? new URL(url) : url;
+  if (search) {
+    base.search = new URLSearchParams(Object.entries(search).filter(([_, value]) => value != null)).toString();
+  }
+
+  return base;
+};

package/src/weak.test.ts

@@ -2,7 +2,7 @@
 // Copyright 2023 DXOS.org
 //
 
-import { test, expect, describe } from 'vitest';
+import { describe, expect, test } from 'vitest';
 
 import { WeakDictionary } from './weak';