@dxos/util 0.9.1-main.c7dcc2e112 → 0.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dxos/util",
-  "version": "0.9.1-main.c7dcc2e112",
+  "version": "0.10.0",
   "description": "Temporary bucket for misc functions, which should graduate into separate packages.",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
@@ -30,13 +30,13 @@
   ],
   "dependencies": {
     "@hazae41/symbol-dispose-polyfill": "^1.0.2",
-    "@dxos/debug": "0.9.1-main.c7dcc2e112",
-    "@dxos/invariant": "0.9.1-main.c7dcc2e112",
-    "@dxos/keys": "0.9.1-main.c7dcc2e112",
-    "@dxos/node-std": "0.9.1-main.c7dcc2e112"
+    "@dxos/debug": "0.10.0",
+    "@dxos/keys": "0.10.0",
+    "@dxos/invariant": "0.10.0",
+    "@dxos/node-std": "0.10.0"
   },
   "devDependencies": {
-    "@dxos/crypto": "0.9.1-main.c7dcc2e112"
+    "@dxos/crypto": "0.10.0"
   },
   "publishConfig": {
     "access": "public"

package/src/Position.test.ts

@@ -0,0 +1,106 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { describe, test } from 'vitest';
+
+import * as Position from './Position';
+
+type TestItem = {
+  id: number;
+  position?: Position.Position;
+};
+
+describe('Position.compare', () => {
+  test('should keep items with same position in their original order', ({ expect }) => {
+    const items: TestItem[] = [
+      { id: 1 },
+      { id: 2 },
+      { id: 3, position: Position.first },
+      { id: 4, position: Position.first },
+      { id: 5, position: Position.last },
+      { id: 6, position: Position.last },
+    ];
+
+    const sorted = [...items].sort(Position.compare);
+
+    expect(sorted.findIndex((item) => item.id === 3)).toBeLessThan(sorted.findIndex((item) => item.id === 4));
+    expect(sorted.findIndex((item) => item.id === 1)).toBeLessThan(sorted.findIndex((item) => item.id === 2));
+    expect(sorted.findIndex((item) => item.id === 5)).toBeLessThan(sorted.findIndex((item) => item.id === 6));
+  });
+
+  test('should place Position.first items before items in natural order', ({ expect }) => {
+    const items: TestItem[] = [{ id: 1 }, { id: 2, position: Position.first }];
+
+    const sorted = [...items].sort(Position.compare);
+    expect(sorted[0].position).toBe(Position.first);
+    expect(sorted[1].position).toBeUndefined();
+  });
+
+  test('should place Position.last items after items in natural order', ({ expect }) => {
+    const items: TestItem[] = [{ id: 1, position: Position.last }, { id: 2 }];
+
+    const sorted = [...items].sort(Position.compare);
+    expect(sorted[0].position).toBeUndefined();
+    expect(sorted[1].position).toBe(Position.last);
+  });
+
+  test('should treat items without position as natural order', ({ expect }) => {
+    const items: TestItem[] = [{ id: 1 }, { id: 2, position: Position.first }, { id: 3, position: Position.last }];
+
+    const sorted = [...items].sort(Position.compare);
+    expect(sorted[0].position).toBe(Position.first);
+    expect(sorted[1].position).toBeUndefined();
+    expect(sorted[2].position).toBe(Position.last);
+  });
+
+  test('should correctly sort mixed positions', ({ expect }) => {
+    const items: TestItem[] = [
+      { id: 1, position: Position.last },
+      { id: 2 },
+      { id: 3, position: Position.first },
+      { id: 4 },
+      { id: 5, position: Position.first },
+      { id: 6, position: Position.last },
+    ];
+
+    const sorted = [...items].sort(Position.compare);
+
+    expect(sorted[0].position).toBe(Position.first);
+    expect(sorted[1].position).toBe(Position.first);
+
+    expect(sorted[2].position).toBeUndefined();
+    expect(sorted[3].position).toBeUndefined();
+
+    expect(sorted[4].position).toBe(Position.last);
+    expect(sorted[5].position).toBe(Position.last);
+  });
+
+  test('should sort numeric tiers between first and last', ({ expect }) => {
+    const items: TestItem[] = [
+      { id: 1, position: Position.last },
+      { id: 2, position: 1 },
+      { id: 3, position: Position.first },
+      { id: 4 },
+      { id: 5, position: -1 },
+    ];
+
+    const sorted = [...items].sort(Position.compare);
+
+    expect(sorted[0].id).toBe(3); // Position.first = -Infinity
+    expect(sorted[1].id).toBe(5); // -1
+    expect(sorted[2].id).toBe(4); // undefined = 0
+    expect(sorted[3].id).toBe(2); // 1
+    expect(sorted[4].id).toBe(1); // Position.last = Infinity
+  });
+
+  test('should handle empty arrays', ({ expect }) => {
+    const items: TestItem[] = [];
+    expect(() => [...items].sort(Position.compare)).not.toThrow();
+  });
+
+  test('should handle single item arrays', ({ expect }) => {
+    const items: TestItem[] = [{ id: 1 }];
+    expect(() => [...items].sort(Position.compare)).not.toThrow();
+  });
+});

package/src/Position.ts

@@ -0,0 +1,29 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+// @import-as-namespace
+
+/**
+ * Numeric priority order — lower values sort earlier.
+ * - `undefined` - Treated as `0`; sorts between `first` and `last`.
+ * - `first` (-Infinity) - Sorts before all other items.
+ * - `last` (Infinity) - Sorts after all other items.
+ * - Any integer between `first` and `last` allows custom tiers.
+ */
+export type Position = number;
+
+export const first: Position = -Infinity;
+export const last: Position = Infinity;
+
+/**
+ * Comparator for sorting by position.
+ */
+export const compare = <T extends { position?: Position }>({ position: a }: T, { position: b }: T): -1 | 0 | 1 => {
+  const aVal = a ?? 0;
+  const bVal = b ?? 0;
+  if (aVal === bVal) {
+    return 0;
+  }
+  return aVal < bVal ? -1 : 1;
+};

package/src/index.ts

@@ -37,7 +37,7 @@ export * from './order-keys';
 export * from './order';
 export * from './pick';
 export * from './platform';
-export * from './position';
+export * as Position from './Position';
 export * from './random';
 export * from './range';
 export * from './reducers';

package/src/types.ts

@@ -12,6 +12,14 @@ export type MaybePromise<T> = T | Promise<T>;
 
 export type GuardedType<T> = T extends ((value: any) => value is infer R) ? R : never;
 
+/**
+ * Flat intersection of up to five types. Behaves like `A & B & C & ...` but
+ * formats as a comma-separated tuple, which fits multi-line layouts more
+ * cleanly than chained `&` operators. Unused slots default to `unknown`,
+ * which is inert under intersection (`T & unknown = T`).
+ */
+export type Merge<A, B = unknown, C = unknown, D = unknown, E = unknown> = A & B & C & D & E;
+
 /**
  * Removes readonly modifiers from top-level properties of T.
  * Also converts readonly arrays at the top level to mutable arrays.

package/dist/types/src/position.d.ts

@@ -1,14 +0,0 @@
-/**
- * Determines priority order:
- * - `undefined` - Remain in natural order.
- * - `first` - Placed before items in natural order.
- * - `last` - Placed after items in natural order.
- */
-export type Position = 'first' | 'last';
-/**
- * Sorting function for sorting by position.
- */
-export declare const byPosition: <T extends {
-    position?: Position;
-}>({ position: a }: T, { position: b }: T) => -1 | 0 | 1;
-//# sourceMappingURL=position.d.ts.map

package/dist/types/src/position.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"position.d.ts","sourceRoot":"","sources":["../../../src/position.ts"],"names":[],"mappings":"AAMA;;;;;GAKG;AACH,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,MAAM,CAAC;AAExC;;GAEG;AACH,eAAO,MAAM,UAAU,GAAI,CAAC,SAAS;IAAE,QAAQ,CAAC,EAAE,QAAQ,CAAA;CAAE,mBAAmB,CAAC,mBAAmB,CAAC,eAUnG,CAAC"}

package/dist/types/src/position.test.d.ts

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=position.test.d.ts.map

package/dist/types/src/position.test.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"position.test.d.ts","sourceRoot":"","sources":["../../../src/position.test.ts"],"names":[],"mappings":""}

package/src/position.test.ts

@@ -1,92 +0,0 @@
-//
-// Copyright 2025 DXOS.org
-//
-
-import { describe, test } from 'vitest';
-
-import { type Position, byPosition } from './position';
-
-type TestItem = {
-  id: number;
-  position?: Position;
-};
-
-describe('byPosition', () => {
-  test('should keep items with same position in their original order', ({ expect }) => {
-    const items: TestItem[] = [
-      { id: 1 },
-      { id: 2 },
-      { id: 3, position: 'first' },
-      { id: 4, position: 'first' },
-      { id: 5, position: 'last' },
-      { id: 6, position: 'last' },
-    ];
-
-    const sorted = [...items].sort(byPosition);
-
-    // Check that items with the same position maintain relative order
-    expect(sorted.findIndex((item) => item.id === 3)).toBeLessThan(sorted.findIndex((item) => item.id === 4));
-    expect(sorted.findIndex((item) => item.id === 1)).toBeLessThan(sorted.findIndex((item) => item.id === 2));
-    expect(sorted.findIndex((item) => item.id === 5)).toBeLessThan(sorted.findIndex((item) => item.id === 6));
-  });
-
-  test('should place "first" items before items in natural order', ({ expect }) => {
-    const items: TestItem[] = [{ id: 1 }, { id: 2, position: 'first' }];
-
-    const sorted = [...items].sort(byPosition);
-    expect(sorted[0].position).toBe('first');
-    expect(sorted[1].position).toBeUndefined();
-  });
-
-  test('should place "last" items after items in natural order', ({ expect }) => {
-    const items: TestItem[] = [{ id: 1, position: 'last' }, { id: 2 }];
-
-    const sorted = [...items].sort(byPosition);
-    expect(sorted[0].position).toBeUndefined();
-    expect(sorted[1].position).toBe('last');
-  });
-
-  test('should treat items without position as natural order', ({ expect }) => {
-    const items: TestItem[] = [{ id: 1 }, { id: 2, position: 'first' }, { id: 3, position: 'last' }];
-
-    const sorted = [...items].sort(byPosition);
-    expect(sorted[0].position).toBe('first');
-    expect(sorted[1].position).toBeUndefined();
-    expect(sorted[2].position).toBe('last');
-  });
-
-  test('should correctly sort mixed positions', ({ expect }) => {
-    const items: TestItem[] = [
-      { id: 1, position: 'last' },
-      { id: 2 },
-      { id: 3, position: 'first' },
-      { id: 4 },
-      { id: 5, position: 'first' },
-      { id: 6, position: 'last' },
-    ];
-
-    const sorted = [...items].sort(byPosition);
-
-    // All "first" items should come first
-    expect(sorted[0].position).toBe('first');
-    expect(sorted[1].position).toBe('first');
-
-    // Natural-order items (undefined) should be in the middle
-    expect(sorted[2].position).toBeUndefined();
-    expect(sorted[3].position).toBeUndefined();
-
-    // "last" items should be at the end
-    expect(sorted[4].position).toBe('last');
-    expect(sorted[5].position).toBe('last');
-  });
-
-  test('should handle empty arrays', ({ expect }) => {
-    const items: TestItem[] = [];
-    expect(() => [...items].sort(byPosition)).not.toThrow();
-  });
-
-  test('should handle single item arrays', ({ expect }) => {
-    const items: TestItem[] = [{ id: 1 }];
-    expect(() => [...items].sort(byPosition)).not.toThrow();
-  });
-});

package/src/position.ts

@@ -1,28 +0,0 @@
-//
-// Copyright 2025 DXOS.org
-//
-
-// TODO(burdon): This shouldn't be in this low-level util? Move to app-framework?
-
-/**
- * Determines priority order:
- * - `undefined` - Remain in natural order.
- * - `first` - Placed before items in natural order.
- * - `last` - Placed after items in natural order.
- */
-export type Position = 'first' | 'last';
-
-/**
- * Sorting function for sorting by position.
- */
-export const byPosition = <T extends { position?: Position }>({ position: a }: T, { position: b }: T) => {
-  if (a === b) {
-    return 0;
-  } else if (a === 'first' || b === 'last') {
-    return -1;
-  } else if (b === 'first' || a === 'last') {
-    return 1;
-  } else {
-    return 0;
-  }
-};