Pass this an array and it will return an interface with enhanced methods for that array.

const lookup = { c: 'you found me' };
  const result = foray(['a', 'b', 'c']).findMapped((key) => lookup[key]);
  console.log(result); // 'you found me';

Wraps the passed array in a Proxy, returning an object that can be used just like the original array, but with added methods provided by foray.

const array = foray([1, 2, 3, 4]);
    array.push(5); // you can use standard array methods
    const output = array.findMapped((v) => { // ...and foray ones
        if (v * 2 === 8) return { found: true };
    });
    console.log(output); // { found: true }

Wraps the passed array in a foray object and stores it in a WeakMap. If the same array is passed again, the function will return the stored foray instance from the WeakMap, instead of creating a new one. This provides a performance optimization for repeat calls with the same array.

const array = [1, 2, 3, 4];
    // each time you want access to foray methods, just wrap the array
    const output1 = foray(array).findMapped((v) => {
        if (v * 2 === 8) return { found: 8 };
    });
    const output2 = foray(array).findMapped((v) => {
        if (v * 2 === 6) return { found: 6 };
    });
    console.log(output1); // { found: 8 }
    console.log(output2); // { found: 6 }

Allows to create a function that is designed to manipulate an array using atomic functions.

useLog simply logs the current item and then returns it. This can be useful for debugging.

useEscape will stop the fn() process and immediately return if the checkFn returns truthy.

useMapper just applies a simple mapping function.

useReducer applies a simple reduction function. It assumes the initial value for the reduction is in the first argument slot.

useSlice acts like the Array.prototype.slice method for the output array. It sets the start and end positions of the output array as it iterates through the input items. If an item's position falls outside the specified slice range, the function returns undefined and adjusts the output array accordingly. It can take one or two arguments, and handles both positive and negative indices.

Note: if you are looking to just handle slicing at the end of your atom you should probably use a hook instead.

This is an example of an atom initialiser that will initialise the atom during the runtime of the fn().

withLog is a decorator that logs the output of a passed-in atom function.

fn(
      cohesive(
        withLog(makeWithArg(useMapper, 0)),
        useEscape(v => v),
      )
    );

This is an example of an atom decorator that will modify the behaviour of an already initialised atom. withOutput specifically takes an output that has been generated by the fn() and pipes that as an input to the passed in atomFn.

The class just tracks the internal cursor used inside fn(). Atoms can use this to alter the inputs and outputs, and to decide when we should return.

Adds the afterAllHook to trigger once method has finished processing the target array.

// Reduce our outputs to the final one and return a single value.
addAfterAllHook(reduceMapped, (cursor) => {
  cursor.outputs = cursor.outputs.slice(-1);
  ([cursor.returnValue] = cursor.outputs);
});

Adds the afterHook to trigger once method has processed through one loop of the target array.

Adds the beforeAllHook to trigger once before any array processing by method

Adds the beforeHook to trigger before each loop of the array as method processes.

Grab out the list of hooks attached to method based on hookCategoryName. If no hookCategoryName provided, then the entire hooks object is returned.

Extend a method created by fn() to have hooks.

Trigger hooks based on hook category name.

Pass the input to multiple functions, in order, the output will be from the last function to return a truthy value.

Combine more than one atom together, similar to pipe(), but making sure to manage outputs as we go.

Pass the input to multiple functions, in order, the output will be from the first function to return a truthy value.

Typical implementation of pipe. This is more basic than cohesive.

Passes the input to multiple functions, in left-to-right order, the output of the first function is passed to the next. The final output will be the returned value from the last processed function.

Pass the input to multiple functions, in left-to-right order, the output of the first function is passed to the next. If a falsey value is encountered the processing stops and returns. The final output will be the returned value from the last processed function.

A good use-case for this atom would be passing your input through a list of functions that replace tokens. It will continue on replacing, returning the modified input. If you encounter something that doesn't validate you can return a falsey value to halt processing.

It might also be that falsey isn't good enough for your use-case. If so, you can create a configured version using pipeWhile.configure({ isTruthyFn }). This allows you to control what is seen as truthy, anything outside of this will halt the processing.

findMapped - allows you to find() that also map()s, but will be more efficient than running [].map(x).find(x) for finds that occur before the end of the array, because it maps as it goes.

get - simple offset getter.

getReversed - simple reversed offset getter.

Map and reduce at the same time!! "Where we're going, roads aren't even a concept..."

const data = foray([1, 2, 3, 4]);
    const sumOfSquares = data.reduceMapped(
        x => x * x, // square each number
        (acc, x) => acc + x // sum the squares
    );
    console.log(sumOfSquares); // Outputs 30

set - simple offset setter.