@dxos/util 0.7.4 → 0.7.5-labs.071a3e2

package/src/position.test.ts

@@ -0,0 +1,98 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { describe, it, expect } from 'vitest';
+
+import { byPosition, type Position } from './position';
+
+type TestItem = {
+  id: number;
+  position?: Position;
+};
+
+describe('byPosition', () => {
+  it('should keep items with same position in their original order', () => {
+    const items: TestItem[] = [
+      { id: 1, position: 'static' },
+      { id: 2, position: 'static' },
+      { id: 3, position: 'hoist' },
+      { id: 4, position: 'hoist' },
+      { id: 5, position: 'fallback' },
+      { id: 6, position: 'fallback' },
+    ];
+
+    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));
+  });
+
+  it('should place "hoist" items before "static" items', () => {
+    const items: TestItem[] = [
+      { id: 1, position: 'static' },
+      { id: 2, position: 'hoist' },
+    ];
+
+    const sorted = [...items].sort(byPosition);
+    expect(sorted[0].position).toBe('hoist');
+    expect(sorted[1].position).toBe('static');
+  });
+
+  it('should place "fallback" items after "static" items', () => {
+    const items: TestItem[] = [
+      { id: 1, position: 'fallback' },
+      { id: 2, position: 'static' },
+    ];
+
+    const sorted = [...items].sort(byPosition);
+    expect(sorted[0].position).toBe('static');
+    expect(sorted[1].position).toBe('fallback');
+  });
+
+  it('should treat items without position as "static"', () => {
+    const items: TestItem[] = [{ id: 1 }, { id: 2, position: 'hoist' }, { id: 3, position: 'fallback' }];
+
+    const sorted = [...items].sort(byPosition);
+    expect(sorted[0].position).toBe('hoist');
+    expect(sorted[1].position).toBeUndefined();
+    expect(sorted[2].position).toBe('fallback');
+  });
+
+  it('should correctly sort mixed positions', () => {
+    const items: TestItem[] = [
+      { id: 1, position: 'fallback' },
+      { id: 2, position: 'static' },
+      { id: 3, position: 'hoist' },
+      { id: 4 }, // implicit static
+      { id: 5, position: 'hoist' },
+      { id: 6, position: 'fallback' },
+    ];
+
+    const sorted = [...items].sort(byPosition);
+
+    // All hoisted items should come first
+    expect(sorted[0].position).toBe('hoist');
+    expect(sorted[1].position).toBe('hoist');
+
+    // Static items (including undefined) should be in the middle
+    expect(sorted[2].position).toBe('static');
+    expect(sorted[3].position).toBeUndefined();
+
+    // Fallback items should be last
+    expect(sorted[4].position).toBe('fallback');
+    expect(sorted[5].position).toBe('fallback');
+  });
+
+  it('should handle empty arrays', () => {
+    const items: TestItem[] = [];
+    expect(() => [...items].sort(byPosition)).not.toThrow();
+  });
+
+  it('should handle single item arrays', () => {
+    const items: TestItem[] = [{ id: 1, position: 'static' }];
+    expect(() => [...items].sort(byPosition)).not.toThrow();
+  });
+});

package/src/position.ts

@@ -0,0 +1,30 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+/**
+ * Determines priority order.
+ *
+ * - `static` - Remain in natural order.
+ * - `hoist` - Placed before `static`.
+ * - `fallback` - Placed after `static`.
+ */
+export type Position = 'static' | 'hoist' | 'fallback';
+
+/**
+ * Sorting function for sorting by position.
+ */
+export const byPosition = <T extends { position?: Position }>(a: T, b: T) => {
+  const aPosition = a.position ?? 'static';
+  const bPosition = b.position ?? 'static';
+
+  if (aPosition === bPosition) {
+    return 0;
+  } else if (aPosition === 'hoist' || bPosition === 'fallback') {
+    return -1;
+  } else if (bPosition === 'hoist' || aPosition === 'fallback') {
+    return 1;
+  }
+
+  return 0;
+};

package/src/safe-parse.ts

@@ -0,0 +1,32 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+export const safeParseInt = (value: string | undefined, defaultValue?: number) => {
+  try {
+    const n = parseInt(value ?? '');
+    return isNaN(n) ? defaultValue : n;
+  } catch (err) {
+    return defaultValue;
+  }
+};
+
+export const safeParseFloat = (str: string, defaultValue?: number): number | undefined => {
+  try {
+    return parseFloat(str);
+  } catch {
+    return defaultValue ?? 0;
+  }
+};
+
+export const safeParseJson: {
+  <T extends object>(data: string | undefined | null, defaultValue: T): T;
+  <T extends object>(data: string | undefined | null): T | undefined;
+} = <T extends object>(data: string | undefined | null, defaultValue?: T) => {
+  if (data && data.length > 0) {
+    try {
+      return JSON.parse(data);
+    } catch (err) {}
+  }
+  return defaultValue;
+};

package/src/string.ts

@@ -0,0 +1,14 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+/**
+ * Capitalizes the first letter of a string.
+ */
+export const capitalize = (str: string): string => {
+  if (str.length === 0) {
+    return '';
+  }
+
+  return str.charAt(0).toUpperCase() + str.slice(1);
+};

package/src/types.ts

@@ -10,7 +10,34 @@ export type MaybeProvider<T, V = void> = T | ((arg: V) => T);
 
 export type MaybePromise<T> = T | Promise<T>;
 
-export type MakeOptional<Type, Key extends keyof Type> = Omit<Type, Key> & Partial<Pick<Type, Key>>;
+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];
+};
+
+export type DeepWriteable<T> = { -readonly [K in keyof T]: T[K] extends object ? DeepWriteable<T[K]> : T[K] };
+
+/**
+ * Simplifies type (copied from effect).
+ */
+export type Simplify<A> = { [K in keyof A]: A[K] } extends infer B ? B : never;
+
+/**
+ * Replace types of specified keys.
+ */
+export type Specialize<T, U> = Simplify<Omit<T, keyof U> & U>;
+
+/**
+ * Make specified keys optional.
+ */
+// TODO(burdon): Wrapping with Simplify fails.
+// export type MakeOptional<T, K extends keyof T> = Simplify<Omit<T, K> & Partial<Pick<T, K>>>;
+export type MakeOptional<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>;
 
 /**
  * All types that evaluate to false when cast to a boolean.
@@ -27,7 +54,7 @@ export const isNotFalsy = <T>(value: T): value is Exclude<T, Falsy> => !!value;
 export const nonNullable = <T>(value: T): value is NonNullable<T> => value !== null && value !== undefined;
 export const isNotNullOrUndefined = <T>(value: T): value is Exclude<T, null | undefined> => value != null;
 // export const isNotNullish = <T>(value: T | null | undefined): value is T => value !== undefined && value !== null;
-export const boolGuard = <T>(value: T | null | undefined): value is T => Boolean(value);
+// export const boolGuard = <T>(value: T | null | undefined): value is T => Boolean(value);
 
 // TODO(burdon): Replace use of setTimeout everywhere?
 //  Would remove the need to cancel (and associated errors), but would change the operation of the code
@@ -55,14 +82,14 @@ export const getAsyncProviderValue = <T, V = void>(
 /**
  * Remove keys with undefined values.
  */
-export const stripUndefinedValues = <T extends { [index: string]: any }>(obj: T): T => {
+export const stripUndefined = <T extends { [index: string]: any }>(obj: T): T => {
   if (typeof obj === 'object') {
     Object.keys(obj).forEach((key) => {
       const value = obj[key];
       if (value === undefined) {
         delete obj[key];
       } else if (value !== null && typeof value === 'object') {
-        stripUndefinedValues(value); // TODO(burdon): Test recursion.
+        stripUndefined(value); // TODO(burdon): Test recursion.
       }
     });
   }
@@ -88,12 +115,3 @@ export const arrayMove = <T>(array: T[], from: number, to: number): Array<T> =>
   array.splice(to < 0 ? array.length + to : to, 0, array.splice(from, 1)[0]);
   return array;
 };
-
-export const safeParseInt = (value: string | undefined, defaultValue?: number) => {
-  try {
-    const n = parseInt(value ?? '');
-    return isNaN(n) ? defaultValue : n;
-  } catch (err) {
-    return defaultValue;
-  }
-};

package/dist/types/src/safe-parse-json.d.ts

@@ -1,5 +0,0 @@
-export declare const safeParseJson: {
-    <T extends object>(data: string | undefined | null, defaultValue: T): T;
-    <T extends object>(data: string | undefined | null): T | undefined;
-};
-//# sourceMappingURL=safe-parse-json.d.ts.map

package/dist/types/src/safe-parse-json.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"safe-parse-json.d.ts","sourceRoot":"","sources":["../../../src/safe-parse-json.ts"],"names":[],"mappings":"AAIA,eAAO,MAAM,aAAa,EAAE;IAC1B,CAAC,CAAC,SAAS,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,EAAE,YAAY,EAAE,CAAC,GAAG,CAAC,CAAC;IACxE,CAAC,CAAC,SAAS,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GAAG,CAAC,GAAG,SAAS,CAAC;CAQpE,CAAC"}

package/src/safe-parse-json.ts

@@ -1,15 +0,0 @@
-//
-// Copyright 2024 DXOS.org
-//
-
-export const safeParseJson: {
-  <T extends object>(data: string | undefined | null, defaultValue: T): T;
-  <T extends object>(data: string | undefined | null): T | undefined;
-} = <T extends object>(data: string | undefined | null, defaultValue?: T) => {
-  if (data) {
-    try {
-      return JSON.parse(data);
-    } catch (err) {}
-  }
-  return defaultValue;
-};