A log of the development process for Rixfeed

This document contains a description of the development process for Rixfeed, including the use of immutability-helper and YAML to define change sets.

Rixfeed Dev Log

### Rixfeed Dev Log

#### Immutability Helpers

I wrote some code that allows you to send a message
like this to the chat bot:

```yml
#!/rixfeed/yml/put
---
id: fXHCezxC5O7utKIZ0Y0X
models:
  core--ghost-app-data:
    props:
      ghostAppId:
        $set: invisible-ghost
  core--acl:
    props:
      roles:
        viewers:
          $identity-dedupe:
          - groups--special-group
          - groups--public
...
```

And it will apply those updates
to the targeted node.

In this case, we're adding the `special-group`
and `public` group to the viewers of the node
if they are not already added.

In order to make this work, I wanted to 
extend a javascript library called [immutability-helper](https://www.npmjs.com/package/immutability-helper)

If you're familiar with React, then you know
why an immutability helper would be useful.

If you aren't, you can read about why
`immutability-helper` is useful using the
link I provided above.

Now, in order to use this libary, you
do something like this:

```typescript
import update from 'immutability-helper';
 
const newData = update(myData, {
  x: {y: {z: {$set: 7}}},
  a: {b: {$push: [9]}}
});
```

However, I'm not a big fan of all those
curly braces.

I thought it would be neat to
be able to define these change sets
using YAML.

Additionally, I wanted to be able to
pass complex functions that take arguments
and then apply those changes to the field.

Immutability helper supports custom
functions, but it does not support 
custom functions which take arguments.
Custom functions only support 
functions which take the current value
of the field you are updating.

In order to enable the behavior I wanted, I had to 
to write some helper functions that
take the arguments defined in your 
YAML change set and curry them.

What folows is my solution.

For the benefit of the reader,
I included verbose comments.

```typescript
import yaml from 'js-yaml';
import { Spec } from 'immutability-helper';
import { identityDedupe } from './dedupe';
import { deepTraverse } from './deep-traverse';
import { keys } from './keys';

/**
 * Overview
 * 
 * use `parseChangeSet` to convert a yml string
 * to a immutability-helper change set.
 * 
 * This function supports providing custom functions
 * which allow you to define your own
 * immutability-helper functions.
 * 
 * See `parseChangeSet` for details.
 */

/**
 * define your custom immutability helper functions
 * here
 */
export const ImmutabilityHelperFunctions = {
  '$identity-dedupe': (o: number[], arg: number[]) => 
    identityDedupe([...o, ...arg]),
}

export type ImmutabilityHelperFunctions = typeof ImmutabilityHelperFunctions;

export interface ParseChangeSetFactoryProps {
  /** The function used to bind custom functions. */
  binder: BinderFn,
}

/**
 * Factory function to parse a change set in YAML format.
 * This function takes a `binder` function and returns a
 * function that loads the YAML string into a schema object.
 * 
 * The inner function then traverses the schema and 
 * replaces values that match custom function keys with 
 * their corresponding function definitions. The factory 
 * pattern is for ease of testing.
 */
export const parseChangeSetFactory = <T extends (...args: any) => any>(
  props: ParseChangeSetFactoryProps,
) => (yamlStr: string) => {
  const { binder } = props;

  // Load YAML string into schema object
  const schema: Record<string, any> = yaml.load(yamlStr) as object;

  // Traverse through the schema and bind custom functions
  deepTraverse<typeof schema>({
    obj: schema,
    visit: ({ obj, key, value }) => {
      if (typeof value !== 'object' && !Array.isArray(value)) {
        // nothing to see here
        return;
      } else if (value === null || value === undefined) {
        // move along.
        return;
      }
      const matchKeys: Array<keyof typeof value> = keys(value);
      const customFunctionKeys = keys(ImmutabilityHelperFunctions);
      const customFunctionId = customFunctionKeys.find((k) =>
        matchKeys.find((k2) => k === k2)
      ) || null;
      if (customFunctionId) {
        const customFnDef: Spec<T> = bindCustomFunction({
          binder,
          customFunctionId,
          args: value[customFunctionId],
        });
        obj[key] = customFnDef;
      }
    },
  });

  return schema;
}


export interface BindCustomFunctionProps {
  /** the function used to bind the curried
   * custom function accessor to a specific
   * customFunctionId and specific arguments
   * to that function. 
   */
  binder: BinderFn,
  customFunctionId: keyof ImmutabilityHelperFunctions,
  /** arguments defined in the yaml schema */
  args: any[]
}

/**
 * Binds the accessor function curried by the binder 
 * to specified arguments and the id for a custom function.
 * 
 * @returns an immutability-helper spec which 
 * includes an $apply field that invokes the 
 * custom function with the provided arguments.
 * The returned spec is used for modifying objects 
 * while maintaining immutability.
 * 
 * #### Motivation
 * immutability-helper custom functions only accept
 * one parameter--the object which they are modifiying.
 * In order to circumvent this, we curry the arguments
 * such that our custom function fits this criteria.
 */
export const bindCustomFunction = <T>(
  props: BindCustomFunctionProps,
): Spec<T> => {
  const { binder, customFunctionId, args } = props;
  // Create a spec object with an apply 
  // field that uses the final
  // curried custom function.
  const customFn = binder({ 
    customFunctionId,
    args,
  });
  const result: Spec<T>  = {
    $apply: customFn,
  };
  return result;
};

export interface BinderFnProps {
  customFunctionId: keyof ImmutabilityHelperFunctions,
  /** arguments defined in the yaml schema */
  args: any[],
}

export interface BindAccessorProps {
  /** an accessor which returns an
   * uncurried custom immutability-helper
   * function.
   * this pattern is to enable modular testing.
   */
  accessor: (key: keyof ImmutabilityHelperFunctions) => (...args: any[]) => any,
}

/**
 * Binds a custom accessor function to an immutability-helper
 * custom function. `bindAccessor` takes an `accessor` 
 * function and returns another function "binder" 
 * that accepts `innerProps` with properties 
 * `customFunctionId` and `args`.
 * 
 * The inner function applies the custom function using
 * the accessor function, which curries the ImmutabilityHelperFunctions.
 * 
 * The inner function uses the custom function key
 * and the accessor to fetch the uncurried custom function.
 * It then produces a final curried custom function 
 * in the format that immutability-helper accepts.
 * 
 * @returns a function can be used to bind custom functions.
 */
export const bindAccessor:
  (accessorProps: BindAccessorProps) => BinderFn = 
    /** fetches an uncurried custom fn by some customFunctionId */
    ({ accessor }: BindAccessorProps) => 
      /** the BinderFn */
      (innerProps: BinderFnProps) => 
        /** the final curried custom function */
        (obj: any) =>
          accessor(innerProps.customFunctionId)(obj, innerProps.args);

/**
 * This inner function binds the custom function key
 * and its arguments to the final curried 
 * immutability custom function.
 */
export type BinderFn = (props: BinderFnProps) => (obj: any) => any;

// Create a binder function using the bindAccessor function
const binder: BinderFn = bindAccessor({
  accessor: (key) => ImmutabilityHelperFunctions[key],
});

/**
 * use `parseChangeSet` to convert a yml string
 * to a immutability-helper change set.
 * 
 * `parseChangeSet` will use the `binder`
 * provided to generate immutability-helper
 * custom methods that match your passed schema.
 * 
 * #### Implementation Notes
 * Define object A with property P.
 * The binder applies the logic of your custom 
 * function to the current value of P and any
 * additional arguments specified within the
 * yaml schema.
 * 
 * immutability-helper custom-functions do not accept 
 * additonal arguments--only the current value
 * of P. This necessitates the use of the BinderFn.
 * 
 * These additional arguments are then curried to 
 * produce an immutibilty-helper custom function
 * that only accepts an argument for the
 * value modified by applying the custom function.
 */
export const parseChangeSet = parseChangeSetFactory({
  binder,
});


```

If you don't understand how this code works,
that's ok. Neither do I. And I wrote it 3 days ago.

No coding article would be complete without tests,
which you can see here, if you're interested: [tests](/pHzJlZh6B7WbFEZ37n5r).
The tests are worth checking out to at least
see how I used the factory functions to
create the appropiate mocked functions to
enable testing.