@xylabs/array 4.13.19 → 4.13.21

package/README.md

@@ -12,13 +12,326 @@
 [![snyk-badge][]][snyk-link]
 [![socket-badge][]][socket-link]
 
-Version: 4.13.15
 
 Base functionality used throughout XY Labs TypeScript/JavaScript libraries
 
-## Documentation
+## API Documentation
+
+**@xylabs/array**
+
+***
+
+## Functions
+
+- [containsAll](#functions/containsAll)
+- [distinct](#functions/distinct)
+- [filterAs](#functions/filterAs)
+- [filterAsync](#functions/filterAsync)
+- [findAs](#functions/findAs)
+- [findLastAs](#functions/findLastAs)
+- [flatten](#functions/flatten)
+- [uniq](#functions/uniq)
+- [uniqBy](#functions/uniqBy)
+
+### functions
+
+  ### <a id="containsAll"></a>containsAll
+
+[**@xylabs/array**](#../README)
+
+***
+
+```ts
+function containsAll<T>(source, target): boolean;
+```
+
+## Type Parameters
+
+### T
+
+`T`
+
+## Parameters
+
+### source
+
+`T`[]
+
+### target
+
+`T`[]
+
+## Returns
+
+`boolean`
+
+  ### <a id="distinct"></a>distinct
+
+[**@xylabs/array**](#../README)
+
+***
+
+```ts
+function distinct<T>(
+   value, 
+   index, 
+   array): boolean;
+```
+
+## Type Parameters
+
+### T
+
+`T`
+
+## Parameters
+
+### value
+
+`T`
+
+### index
+
+`number`
+
+### array
+
+`T`[]
+
+## Returns
+
+`boolean`
+
+  ### <a id="filterAs"></a>filterAs
+
+[**@xylabs/array**](#../README)
+
+***
+
+```ts
+function filterAs<In, Out>(x, predicate): NonNullable<Out>[];
+```
+
+## Type Parameters
+
+### In
+
+`In`
+
+### Out
+
+`Out`
+
+## Parameters
+
+### x
+
+`In`[]
+
+### predicate
+
+(`a`) => `Out`
+
+## Returns
+
+`NonNullable`\<`Out`\>[]
+
+  ### <a id="filterAsync"></a>filterAsync
+
+[**@xylabs/array**](#../README)
+
+***
+
+```ts
+function filterAsync<T>(array, predicate): Promise<T[]>;
+```
+
+Returns the elements of an array that meet the condition specified in a callback function.
+
+## Type Parameters
+
+### T
+
+`T`
+
+## Parameters
+
+### array
+
+`T`[]
+
+The array to filter.
+
+### predicate
+
+(`value`, `index`, `array`) => `Promise`\<`boolean`\>
+
+A function that accepts up to three arguments. The filter method calls the predicate function one time for each element in the array.
+
+## Returns
+
+`Promise`\<`T`[]\>
+
+The elements of an array that meet the condition specified in a callback function.
+
+  ### <a id="findAs"></a>findAs
+
+[**@xylabs/array**](#../README)
+
+***
+
+```ts
+function findAs<In, Out>(x, predicate): undefined | NonNullable<Out>;
+```
+
+## Type Parameters
+
+### In
+
+`In`
+
+### Out
+
+`Out`
+
+## Parameters
+
+### x
+
+`In`[]
+
+### predicate
+
+(`a`) => `Out`
+
+## Returns
+
+`undefined` \| `NonNullable`\<`Out`\>
+
+  ### <a id="findLastAs"></a>findLastAs
+
+[**@xylabs/array**](#../README)
+
+***
+
+```ts
+function findLastAs<In, Out>(x, predicate): undefined | NonNullable<Out>;
+```
+
+## Type Parameters
+
+### In
+
+`In`
+
+### Out
+
+`Out`
+
+## Parameters
+
+### x
+
+`In`[]
+
+### predicate
+
+(`a`) => `Out`
+
+## Returns
+
+`undefined` \| `NonNullable`\<`Out`\>
+
+  ### <a id="flatten"></a>flatten
+
+[**@xylabs/array**](#../README)
+
+***
+
+```ts
+function flatten<T>(a?, b?): T[];
+```
+
+## Type Parameters
+
+### T
+
+`T`
+
+## Parameters
+
+### a?
+
+`T` | `ConcatArray`\<`T`\>
+
+### b?
+
+`T` | `ConcatArray`\<`T`\>
+
+## Returns
+
+`T`[]
+
+  ### <a id="uniq"></a>uniq
+
+[**@xylabs/array**](#../README)
+
+***
+
+```ts
+function uniq<T>(arr): T[];
+```
+
+## Type Parameters
+
+### T
+
+`T`
+
+## Parameters
+
+### arr
+
+`T`[]
+
+## Returns
+
+`T`[]
+
+  ### <a id="uniqBy"></a>uniqBy
+
+[**@xylabs/array**](#../README)
+
+***
+
+```ts
+function uniqBy<T, I>(arr, iteratee): T[];
+```
+
+## Type Parameters
+
+### T
+
+`T`
+
+### I
+
+`I`
+
+## Parameters
+
+### arr
+
+`T`[]
+
+### iteratee
+
+(`item`) => `I`
+
+## Returns
+
+`T`[]
 
-Coming Soon!
 
 Part of [sdk-js](https://www.npmjs.com/package/@xyo-network/sdk-js)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xylabs/array",
-  "version": "4.13.19",
+  "version": "4.13.21",
   "description": "Base functionality used throughout XY Labs TypeScript/JavaScript libraries",
   "keywords": [
     "xylabs",
@@ -28,19 +28,25 @@
   "exports": {
     ".": {
       "types": "./dist/neutral/index.d.ts",
+      "source": "./src/index.ts",
       "default": "./dist/neutral/index.mjs"
     },
     "./package.json": "./package.json"
   },
   "module": "./dist/neutral/index.mjs",
+  "source": "./src/index.ts",
   "types": "./dist/neutral/index.d.ts",
+  "files": [
+    "dist",
+    "src"
+  ],
   "dependencies": {
-    "@xylabs/exists": "^4.13.19"
+    "@xylabs/exists": "^4.13.21"
   },
   "devDependencies": {
-    "@xylabs/ts-scripts-yarn3": "^7.0.0-rc.27",
-    "@xylabs/tsconfig": "^7.0.0-rc.27",
-    "@xylabs/vitest-extended": "^4.13.19",
+    "@xylabs/ts-scripts-yarn3": "^7.0.0",
+    "@xylabs/tsconfig": "^7.0.0",
+    "@xylabs/vitest-extended": "^4.13.21",
     "typescript": "^5.8.3",
     "vitest": "^3.2.4"
   },

package/src/spec/containsAll.spec.ts

@@ -0,0 +1,92 @@
+import '@xylabs/vitest-extended'
+
+import {
+  describe, expect, it,
+} from 'vitest'
+
+import { containsAll } from '../containsAll.ts'
+
+describe('containsAll', () => {
+  describe('when the source array contains all the target elements', () => {
+    const testCases: [unknown[], unknown[]][] = [
+      [
+        [1, 2, 3, 4, 5, 6],
+        [1, 2, 3],
+      ],
+      [
+        ['f', 'e', 'd', 'c', 'b', 'a'],
+        ['a', 'b', 'c'],
+      ],
+    ]
+    it.each(testCases)('returns true', (source, target) => {
+      expect(containsAll(source, target)).toBeTrue()
+    })
+  })
+  describe('when the source array does not contain all the target elements', () => {
+    const testCases: [unknown[], unknown[]][] = [
+      [
+        [1, 2, 3, 4, 5, 6],
+        [5, 6, 7],
+      ],
+      [
+        ['f', 'e', 'd', 'c', 'b', 'a'],
+        ['d', 'e', 'f', 'g'],
+      ],
+    ]
+    it.each(testCases)('returns false', (source, target) => {
+      expect(containsAll(source, target)).toBeFalse()
+    })
+  })
+
+  // Edge cases with empty arrays
+  describe('when working with empty arrays', () => {
+    const testCases: [unknown[], unknown[], boolean][] = [
+      [[], [], true], // Empty source, empty target should be true
+      [[1, 2, 3], [], true], // Non-empty source, empty target should be true
+      [[], [1, 2, 3], false], // Empty source, non-empty target should be false
+    ]
+    it.each(testCases)('handles the case correctly', (source, target, expected) => {
+      expect(containsAll(source, target)).toBe(expected)
+    })
+  })
+
+  // Cases with duplicate elements
+  describe('when arrays contain duplicate elements', () => {
+    const testCases: [unknown[], unknown[]][] = [
+      [[1, 2, 2, 3, 3, 3], [2, 3]], // Duplicates in source
+      [[1, 2, 3], [2, 2, 3, 3]], // Duplicates in target (should still work if source has at least one of each)
+    ]
+    it.each(testCases)('returns true when all unique elements are pxresent', (source, target) => {
+      expect(containsAll(source, target)).toBeTrue()
+    })
+  })
+
+  // Objects and reference types
+  describe('when arrays contain objects', () => {
+    const obj1 = { id: 1 }
+    const obj2 = { id: 2 }
+    const obj3 = { id: 3 }
+
+    it('checks object references correctly', () => {
+      // Same objects (by reference)
+      expect(containsAll([obj1, obj2, obj3], [obj1, obj2])).toBeTrue()
+
+      // Different objects with same content
+      expect(containsAll([obj1, obj2, obj3], [{ id: 1 }, { id: 2 }])).toBeFalse()
+    })
+  })
+
+  // Special values
+  describe('when arrays contain special values', () => {
+    it('handles null and undefined correctly', () => {
+      expect(containsAll([null, undefined, 1, 2], [null, undefined])).toBeTrue()
+      expect(containsAll([1, 2, 3], [undefined])).toBeFalse()
+    })
+
+    it('handles NaN correctly', () => {
+      // Note: This depends on how containsAll is implemented
+      // NaN !== NaN in JavaScript, so this might fail depending on implementation
+      expect(containsAll([Number.NaN, 1, 2], [Number.NaN])).toBeTrue()
+    })
+  })
+})

package/src/spec/distinct.spec.ts

@@ -0,0 +1,73 @@
+import '@xylabs/vitest-extended'
+
+import {
+  describe, expect, it,
+} from 'vitest'
+
+import { distinct } from '../distinct.ts'
+
+describe('distinct', () => {
+  describe('basic scenarios', () => {
+    const testCases: [unknown[], unknown[]][] = [
+      [
+        [1, 2, 3, 3, 2, 1],
+        [1, 2, 3],
+      ],
+      [
+        ['a', 'b', 'c', 'c', 'b', 'a'],
+        ['a', 'b', 'c'],
+      ],
+    ]
+    it.each(testCases)('removes duplicates', (input, expected) => {
+      expect(input.filter(distinct)).toEqual(expected)
+    })
+  })
+
+  describe('edge cases', () => {
+    it('handles empty arrays', () => {
+      expect([].filter(distinct)).toEqual([])
+    })
+
+    it('handles arrays with a single element', () => {
+      expect([5].filter(distinct)).toEqual([5])
+    })
+
+    it('preserves order of first occurrence', () => {
+      expect([3, 1, 2, 3, 2, 1].filter(distinct)).toEqual([3, 1, 2])
+    })
+  })
+
+  describe('special values', () => {
+    it('handles null and undefined', () => {
+      expect([null, undefined, null, undefined].filter(distinct)).toEqual([null, undefined])
+    })
+
+    it('handles mixed types', () => {
+      expect([1, '1', true, 1, '1', true].filter(distinct)).toEqual([1, '1', true])
+    })
+
+    it('handles NaN values', () => {
+      const result = [Number.NaN, Number.NaN, 1, 2].filter(distinct)
+      expect(result.length).toBe(3)
+      expect(Number.isNaN(result[0])).toBeTrue()
+      expect(result.slice(1)).toEqual([1, 2])
+    })
+  })
+
+  describe('objects and references', () => {
+    it('distinguishes objects by reference', () => {
+      const obj1 = { id: 1 }
+      const obj2 = { id: 2 }
+      const obj3 = { id: 1 } // Same content as obj1, different reference
+
+      expect([obj1, obj2, obj1, obj3].filter(distinct)).toEqual([obj1, obj2, obj3])
+    })
+
+    it('works with complex nested objects', () => {
+      const obj1 = { user: { name: 'Alice', id: 1 } }
+      const obj2 = { user: { name: 'Bob', id: 2 } }
+
+      expect([obj1, obj2, obj1].filter(distinct)).toEqual([obj1, obj2])
+    })
+  })
+})

package/src/spec/filterAsync.spec.ts

@@ -0,0 +1,105 @@
+import {
+  describe, expect, it,
+} from 'vitest'
+
+import { filterAsync } from '../filterAsync.ts'
+
+describe('filterAsync', () => {
+  const evenNumbers = async (value: number) => await Promise.resolve(value % 2 === 0) // Keep even numbers
+  it('filters an array based on an asynchronous predicate', async () => {
+    const array = [1, 2, 3, 4, 5]
+    const result = await filterAsync(array, evenNumbers)
+    expect(result).toEqual([2, 4])
+  })
+
+  it('returns an empty array if no elements match the predicate', async () => {
+    const array = [1, 3, 5]
+    const result = await filterAsync(array, evenNumbers)
+    expect(result).toEqual([])
+  })
+
+  it('returns the original array if all elements match the predicate', async () => {
+    const array = [2, 4, 6]
+    const result = await filterAsync(array, evenNumbers)
+    expect(result).toEqual([2, 4, 6])
+  })
+
+  it('handles an empty array', async () => {
+    const array: number[] = []
+    const result = await filterAsync(array, evenNumbers)
+    expect(result).toEqual([])
+  })
+
+  it('handles predicates that depend on the index', async () => {
+    const array = [10, 20, 30, 40, 50]
+    const evenIndices = async (_value: number, index: number) =>
+      await Promise.resolve(index % 2 === 0) // Keep elements at even indices
+    const result = await filterAsync(array, evenIndices)
+    expect(result).toEqual([10, 30, 50])
+  })
+
+  it('handles predicates that depend on the entire array', async () => {
+    const array = [1, 2, 3, 4, 5]
+    const greaterThanMin = async (value: number, _index: number, arr: number[]) =>
+      await Promise.resolve(value > Math.min(...arr)) // Keep elements greater than the smallest element
+    const result = await filterAsync(array, greaterThanMin)
+    expect(result).toEqual([2, 3, 4, 5])
+  })
+
+  it('processes all items concurrently', async () => {
+    // This test verifies that all predicate functions are called before any are awaited
+    const executionOrder: number[] = []
+    const delayedEvenNumbers = async (value: number) => {
+      executionOrder.push(value) // Record when this function was called
+      // Delay longer for even numbers to ensure non-sequential execution is visible
+      const delay = value % 2 === 0 ? 50 : 10
+      await new Promise(resolve => setTimeout(resolve, delay))
+      return value % 2 === 0
+    }
+
+    const array = [1, 2, 3, 4, 5]
+    const result = await filterAsync(array, delayedEvenNumbers)
+
+    // All items should be processed before any promises resolve
+    expect(executionOrder).toEqual([1, 2, 3, 4, 5])
+    expect(result).toEqual([2, 4])
+  })
+
+  it('handles rejection in the predicate function', async () => {
+    const rejectingPredicate = async (value: number) => {
+      if (value === 3) {
+        throw new Error('Test error')
+      }
+      return await Promise.resolve(value % 2 === 0)
+    }
+
+    const array = [1, 2, 3, 4, 5]
+    await expect(filterAsync(array, rejectingPredicate)).rejects.toThrow('Test error')
+  })
+
+  it('works with a predicate that sometimes returns synchronously', async () => {
+    const mixedPredicate = (value: number) => {
+      if (value % 2 === 0) {
+        // Return synchronously for even numbers
+        return Promise.resolve(true)
+      }
+      // Return asynchronously for odd numbers
+      return Promise.resolve(false)
+    }
+
+    const array = [1, 2, 3, 4, 5]
+    const result = await filterAsync(array, mixedPredicate)
+    expect(result).toEqual([2, 4])
+  })
+
+  it('handles a large array efficiently', async () => {
+    const largeArray = Array.from({ length: 1000 }, (_, i) => i)
+    const start = performance.now()
+
+    const result = await filterAsync(largeArray, evenNumbers)
+
+    const end = performance.now()
+    expect(result.length).toBe(500) // Should have 500 even numbers
+    expect(end - start).toBeLessThan(1000) // Should complete in a reasonable time
+  })
+})

package/src/spec/flatten.spec.ts

@@ -0,0 +1,18 @@
+import {
+  describe, expect, it,
+} from 'vitest'
+
+import { flatten } from '../flatten.ts'
+
+describe('flatten', () => {
+  const testCases: [unknown | unknown[], unknown | unknown[], unknown | unknown[]][] = [
+    [['a'], ['b', 'c'], ['a', 'b', 'c']],
+    ['a', ['b', 'c'], ['a', 'b', 'c']],
+    [['a', 'b'], undefined, ['a', 'b']],
+    [undefined, undefined, []],
+    [['a'], [1, 2], ['a', 1, 2]],
+  ]
+  it.each(testCases)('flattens inputs', (a, b, expected) => {
+    expect(flatten(a, b)).toEqual(expected)
+  })
+})

package/xy.config.ts

@@ -1,10 +0,0 @@
-import type { XyTsupConfig } from '@xylabs/ts-scripts-yarn3'
-const config: XyTsupConfig = {
-  compile: {
-    browser: {},
-    neutral: { src: true },
-    node: {},
-  },
-}
-
-export default config