Array Operations

/**
 * Find the common unique items in two arrays
 * @param array1 - The first array to compare
 * @param array2 - The second array to compare  
 * @param options - Optional settings for intersection behavior
 * @returns An array of the common items, or first common item if justFirst is true
 */
function intersect<T1, T2>(array1: intersect.Array<T1>, array2: intersect.Array<T2>, options?: intersect.Options): Array<T1 | T2>;
function intersect<T1, T2>(array1: intersect.Array<T1>, array2: intersect.Array<T2>, options?: intersect.Options): T1 | T2;

namespace intersect {
  /** Array-like structure including arrays, Sets, or null */
  type Array<T> = ArrayLike<T> | Set<T> | null;
  
  interface Options {
    /** When true, return the first overlapping value. Defaults to false */
    readonly first?: boolean;
  }
}

import { intersect } from "@hapi/hoek";

// Basic array intersection
const array1 = [1, 2, 3];
const array2 = [1, 4, 5];
const common = intersect(array1, array2); // [1]

// First match only
const first = intersect(array1, array2, { first: true }); // 1

// Working with Sets
const set1 = new Set([1, 2, 3]);
const set2 = new Set([2, 3, 4]);
const setIntersection = intersect(set1, set2); // [2, 3]

// String arrays
const names1 = ['alice', 'bob', 'charlie'];
const names2 = ['bob', 'david', 'eve'];
const commonNames = intersect(names1, names2); // ['bob']

/**
 * Checks if the reference value contains the provided values
 * @param ref - The reference string, array, or object
 * @param values - A single or array of values to find within ref
 * @param options - Optional settings for containment testing
 * @returns true if the value contains the provided values, otherwise false
 */
function contain(ref: string, values: string | string[], options?: contain.Options): boolean;
function contain(ref: any[], values: any, options?: contain.Options): boolean;
function contain(ref: object, values: string | string[] | object, options?: Omit<contain.Options, 'once'>): boolean;

namespace contain {
  interface Options {
    /** Perform a deep comparison. Defaults to false */
    readonly deep?: boolean;
    /** Allow only one occurrence of each value. Defaults to false */
    readonly once?: boolean;
    /** Allow only values explicitly listed. Defaults to false */
    readonly only?: boolean;
    /** Allow partial match. Defaults to false */
    readonly part?: boolean;
    /** Include symbol properties. Defaults to true */
    readonly symbols?: boolean;
  }
}

import { contain } from "@hapi/hoek";

// String containment
contain('aaa', 'a'); // true
contain('aaa', 'a', { only: true }); // true
contain('abc', ['a', 'b']); // true

// Array containment
contain([1, 2, 3], 2); // true
contain([1, 2, 2], [1, 2], { once: true }); // false (2 appears twice)

// Object containment with deep comparison
contain([{ a: 1 }], [{ a: 1 }], { deep: true }); // true

// Object property containment
const obj = { a: 1, b: 2, c: 3 };
contain(obj, { a: 1, d: 4 }, { part: true }); // true (partial match)
contain(obj, ['a', 'b']); // true (has keys a and b)

// Only specified values allowed
contain('abc', ['a', 'b', 'c'], { only: true }); // true
contain('abc', ['a', 'b'], { only: true }); // false (c is not in allowed list)

/**
 * Flatten an array with sub arrays
 * @param array - An array of items or other arrays to flatten
 * @param target - If provided, an array to shallow copy the flattened array items to
 * @returns A flat array of the provided values (appended to target if provided)
 */
function flatten<T>(array: ArrayLike<T | ReadonlyArray<T>>, target?: ArrayLike<T | ReadonlyArray<T>>): T[];

import { flatten } from "@hapi/hoek";

// Basic flattening
const nested = [1, [2, 3]];
const flat = flatten(nested); // [1, 2, 3]

// Multiple levels
const deepNested = [1, [2, [3, 4]], 5];
const flattened = flatten(deepNested); // [1, 2, [3, 4], 5] (only one level)

// Flattening with target array
const array = [1, [2, 3]];
const target = [4, [5]];
const result = flatten(array, target); // [4, [5], 1, 2, 3]

// Mixed data types
const mixed = ['a', ['b', 'c'], 'd'];
const flatMixed = flatten(mixed); // ['a', 'b', 'c', 'd']

// Empty arrays
const withEmpty = [1, [], [2, 3]];
const flatEmpty = flatten(withEmpty); // [1, 2, 3]