@fluentui-react-native/framework-base 0.1.1

package/src/immutable-merge/Merge.test.ts

@@ -0,0 +1,342 @@
+import type { MergeOptions } from './Merge';
+import { immutableMerge, immutableMergeCore, processImmutable } from './Merge';
+
+interface IFakeStyle {
+  s1?: string;
+  s2?: number;
+  nm?: INoMerge;
+}
+
+interface INoMerge {
+  nm1?: number;
+  nm2?: number;
+}
+
+interface IFakeSettings {
+  root?: {
+    p1?: string;
+    p2?: number;
+    nm?: INoMerge;
+    style?: IFakeStyle;
+  };
+  fakeSlot?: {
+    ps1?: string;
+    ps2?: number;
+    style?: IFakeStyle;
+  };
+}
+
+const sett1: IFakeSettings = {
+  root: {
+    p2: 1,
+    nm: { nm1: 1 },
+    style: { s1: 'foo', s2: 2, nm: { nm1: 1 } },
+  },
+  fakeSlot: {
+    ps2: 2,
+  },
+};
+
+const sett2: IFakeSettings = {
+  root: {
+    p1: 'sett2',
+    p2: 2,
+    nm: { nm2: 2 },
+  },
+  fakeSlot: {
+    style: { s1: 'sett2' },
+  },
+};
+
+const sett1plus2: IFakeSettings = {
+  root: {
+    p1: 'sett2',
+    p2: 2,
+    nm: { nm2: 2 },
+    style: { s1: 'foo', s2: 2, nm: { nm1: 1 } },
+  },
+  fakeSlot: {
+    ps2: 2,
+    style: { s1: 'sett2' },
+  },
+};
+
+const sett3: IFakeSettings = {
+  root: {
+    p1: 'sett3',
+    style: { s2: 3, nm: { nm2: 2 } },
+  },
+};
+
+const sett1plus3: IFakeSettings = {
+  root: {
+    p1: 'sett3',
+    p2: 1,
+    nm: { nm1: 1 },
+    style: { s1: 'foo', s2: 3, nm: { nm2: 2 } },
+  },
+  fakeSlot: {
+    ps2: 2,
+  },
+};
+
+const sett1plus2plus3: IFakeSettings = {
+  root: {
+    p1: 'sett3',
+    p2: 2,
+    nm: { nm2: 2 },
+    style: { s1: 'foo', s2: 3, nm: { nm2: 2 } },
+  },
+  fakeSlot: {
+    ps2: 2,
+    style: { s1: 'sett2' },
+  },
+};
+
+const mergeOptions: MergeOptions = {
+  object: {
+    style: 0,
+  },
+};
+
+interface IDeepObj {
+  a: { b: { c: number } };
+  b: { c: { d: { d: string } } };
+}
+
+const deep1 = {
+  a: { b: { c: 1 } },
+  b: { c: { d: { d: 'foo' } } },
+  c: { e: 4 },
+};
+
+const deep2 = {
+  a: { b1: 3, b: { c: 2 } },
+  b: { c: { d2: 'bar' } },
+  c: { e2: { f: 'baz' } },
+};
+
+const deepMerged = {
+  a: { b1: 3, b: { c: 2 } },
+  b: { c: { d: { d: 'foo' }, d2: 'bar' } },
+  c: { e: 4, e2: { f: 'baz' } },
+};
+
+const singleToChange = {
+  a: { b: { c: { changeMe: { color: 'blue' } } } },
+  b: { d: { changeMe: { font: 'fixed' } } },
+};
+
+const singleWithChanges = {
+  a: { b: { c: { changeMe: { color: 'changed' } } } },
+  b: { d: { changeMe: { font: 'fixed' } } },
+};
+
+const _colorKey = 'color';
+
+const changeMeHandler = (...objs: (Record<string, unknown> | undefined)[]) => {
+  // written always assuming only one entry
+  if (objs.length === 1) {
+    const firstObj = objs[0]!;
+
+    if (firstObj[_colorKey]) {
+      return { ...firstObj, color: 'changed' };
+    }
+
+    return firstObj;
+  }
+  return undefined;
+};
+
+const changeMeOption1: MergeOptions = {
+  a: {
+    b: {
+      c: {
+        changeMe: changeMeHandler,
+      },
+    },
+  },
+};
+
+const changeMeOption2: MergeOptions = {
+  object: {
+    object: {
+      object: {
+        changeMe: changeMeHandler,
+      },
+      changeMe: changeMeHandler,
+    },
+  },
+};
+
+describe('Immutable merge unit tests', () => {
+  test('merge one returns same object', () => {
+    const obj = {
+      a: 'a',
+      b: 2,
+    };
+    expect(immutableMerge(obj, undefined)).toBe(obj);
+    expect(immutableMerge(undefined, obj)).toBe(obj);
+  });
+
+  test('merge flat is like assign', () => {
+    const obj1 = { a: 'a', b: 1 };
+    const obj2 = { b: 2, c: true };
+    const merged = { a: 'a', b: 2, c: true };
+    expect(immutableMerge<any>(obj1, obj2)).toEqual(merged);
+    expect(immutableMergeCore<any>(0, obj1, obj2)).toEqual(merged);
+    expect(immutableMergeCore<any>(true, obj1, obj2)).toEqual(merged);
+  });
+
+  const dm1 = {
+    a: { b: { c: { foo: 'foo', bar: 'bar' } } },
+    d: { e: 1, f: { g: 'hello', h: 2 } },
+  };
+
+  const dm2 = {
+    a: { b: { c: { bar: 'bar2', baz: 'baz' } }, i: 'world' },
+    d: { j: 4 },
+  };
+
+  test('deep merge', () => {
+    expect(immutableMerge<any>(dm1, dm2)).toEqual({
+      a: { b: { c: { foo: 'foo', bar: 'bar2', baz: 'baz' } }, i: 'world' },
+      d: { e: 1, f: { g: 'hello', h: 2 }, j: 4 },
+    });
+  });
+
+  test('merge zero levels', () => {
+    expect(immutableMergeCore<any>(0, dm1, dm2)).toEqual(dm2);
+  });
+
+  test('merge one level deep', () => {
+    const result = {
+      a: dm2.a,
+      d: { ...dm1.d, ...dm2.d },
+    };
+    expect(immutableMergeCore<any>(1, dm1, dm2)).toEqual(result);
+    expect(immutableMergeCore<any>({ object: 0 }, dm1, dm2)).toEqual(result);
+  });
+
+  test('merge with empty object', () => {
+    const merged = immutableMergeCore(mergeOptions, sett1, {});
+    expect(merged).toBe(sett1);
+    const merged2 = immutableMergeCore(mergeOptions, {}, sett2);
+    expect(merged2).toBe(sett2);
+  });
+
+  test('merge sett1 and sett2', () => {
+    const merged = immutableMergeCore(mergeOptions, sett1, sett2) as IFakeSettings;
+    expect(merged).toEqual(sett1plus2);
+    expect(merged!.root.style).toBe(sett1.root.style);
+    expect(merged!.fakeSlot!.style).toBe(sett2.fakeSlot!.style);
+  });
+
+  test('merge sett1 and sett3', () => {
+    const merged = immutableMergeCore(mergeOptions, sett1, sett3) as IFakeSettings;
+    expect(merged).toEqual(sett1plus3);
+    expect(merged!.fakeSlot).toBe(sett1.fakeSlot);
+  });
+
+  test('merge three', () => {
+    const merged = immutableMergeCore(mergeOptions, sett1, sett2, sett3);
+    expect(merged).toEqual(sett1plus2plus3);
+  });
+
+  test('deepMerge', () => {
+    const merged = immutableMergeCore<any>(-1, deep1, deep2) as IDeepObj;
+    expect(merged).toEqual(deepMerged);
+    expect(merged.b.c.d).toBe(deep1.b.c.d);
+    expect(merged.a.b).not.toBe(deep2.a.b);
+  });
+
+  test('singleProcessNoChange', () => {
+    const merged = processImmutable({ object: true }, singleToChange);
+    expect(merged).toBe(singleToChange);
+  });
+
+  test('single process with change', () => {
+    const merged = processImmutable(changeMeOption1, singleToChange);
+    expect(merged).toEqual(singleWithChanges);
+    expect(merged).not.toBe(singleToChange);
+    expect((merged as any).b).toBe(singleToChange.b);
+  });
+
+  test('single process with change - alternative', () => {
+    const merged = processImmutable(changeMeOption2, singleToChange);
+    expect(merged).toEqual(singleWithChanges);
+    expect(merged).not.toBe(singleToChange);
+    expect((merged as any).b).toBe(singleToChange.b);
+  });
+
+  const withArray1 = {
+    baseArray: [1, 2, 3],
+    sub: { subArray: ['a', 'b', 'c'] },
+  };
+
+  const withArray2 = {
+    baseArray: [4, 5, 6],
+    sub: { subArray: ['d', 'e', 'f'] },
+  };
+
+  test('arrays overwrite each other', () => {
+    const merged = immutableMergeCore({ depth: -1 }, withArray1, withArray2);
+    expect(merged).toEqual(withArray2);
+    expect(merged).not.toBe(withArray2);
+  });
+
+  const withObj = {
+    a: { foo: 'bar' },
+    b: 2,
+  };
+
+  const withNonObj = {
+    a: 'hello',
+    b: 3,
+  };
+
+  test('last writer wins for objects and non-objects', () => {
+    const merged = immutableMerge<any>(withObj, withNonObj);
+    expect(merged).toEqual(withNonObj);
+    const merged2 = immutableMerge<any>(withNonObj, withObj);
+    expect(merged2).toEqual(withObj);
+  });
+
+  const arrayMerger = (...targets: any[]) => {
+    const arrays = targets.filter((t) => Array.isArray(t));
+    let result = [];
+    arrays.forEach((v) => (result = result.concat(...v)));
+    return result;
+  };
+
+  test('arrays can merge with handler', () => {
+    const merged = immutableMergeCore(
+      {
+        object: {
+          subArray: arrayMerger,
+        },
+      },
+      withArray1,
+      withArray2,
+    );
+    expect(merged).toEqual({
+      baseArray: [4, 5, 6],
+      sub: { subArray: ['a', 'b', 'c', 'd', 'e', 'f'] },
+    });
+  });
+
+  test('arrays can merge deeply', () => {
+    const merged = immutableMergeCore(
+      {
+        object: true,
+        array: 'appendArray',
+      },
+      withArray1,
+      withArray2,
+    );
+    expect(merged).toEqual({
+      baseArray: [1, 2, 3, 4, 5, 6],
+      sub: { subArray: ['a', 'b', 'c', 'd', 'e', 'f'] },
+    });
+  });
+});

package/src/immutable-merge/Merge.ts

@@ -0,0 +1,255 @@
+/**
+ * The basic options for recursion at a given level.  Two types for two behaviors:
+ *
+ * boolean:
+ *  - if true, recurse indefinitely
+ *  - if false, don't recurse
+ *
+ * number:
+ *  - if 0, don't recurse from this level
+ *  - if > 0, recurse that many times then stop
+ *  - if < 0, recurse indefinitely
+ */
+export type RecursionOption = boolean | number;
+
+/**
+ * a function that can be set to merge arguments
+ */
+export type CustomRecursionHandler = (...vals: any[]) => any;
+
+/**
+ * built in handler functions that can be applied for a given key
+ */
+export type BuiltinRecursionHandlers = 'appendArray';
+
+/**
+ * Handlers for recursion of a given key or type.  These can either be functions or a reference to a supported
+ * built-in merge routine
+ */
+export type RecursionHandler = BuiltinRecursionHandlers | CustomRecursionHandler;
+
+/**
+ * Base object type for merges, avoids using object since that is too broad. In particular things like null and arrays
+ * are not valid object types for the purposes of this library.
+ */
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+export type ObjectBase = {};
+
+/**
+ *
+ */
+export type TypeofResult = 'undefined' | 'object' | 'boolean' | 'number' | 'string' | 'symbol' | 'bigint' | 'function';
+export type ExpandedTypeof = TypeofResult | 'array' | 'null';
+
+/**
+ * configuration object for the merge, key names are matched with a few exceptions:
+ * - object: matches non-array object types
+ * - array: matches array types
+ * - [key: string]: matches anything by name
+ */
+export interface MergeOptions {
+  [objectTypeOrKeyName: string]: RecursionOption | RecursionHandler | MergeOptions;
+}
+
+/**
+ * built in handlers for the module
+ */
+const _builtinHandlers: { [K in BuiltinRecursionHandlers]: CustomRecursionHandler } = {
+  appendArray: (...objs: any[]) => {
+    return [].concat(...objs);
+  },
+};
+
+/**
+ * This processes the various type options for merge core and turns them into a MergeConfig
+ * @param options - options passed into immutableMergeCore
+ */
+function normalizeOptions(options: RecursionOption | MergeOptions): [MergeOptions, boolean] {
+  return typeof options === 'boolean'
+    ? [{ object: options }, options]
+    : typeof options === 'number'
+    ? [{ object: options >= 0 ? options : true }, options !== 0]
+    : [options, true];
+}
+
+/**
+ * Provide a more sensible type result that expands upon the built in typeof operator
+ * In particular this will differentiate arrays and nulls from standard objects
+ * @param val - value to check type
+ */
+function getEntityType(val: unknown): ExpandedTypeof {
+  switch (typeof val) {
+    case 'object':
+      if (val === null) {
+        return 'null';
+      } else if (Array.isArray(val)) {
+        return 'array';
+      }
+      return 'object';
+    default:
+      return typeof val as TypeofResult;
+  }
+}
+
+/** resolve custom handlers if they are applicable */
+function resolveIfHandler(option: RecursionHandler | RecursionOption | MergeOptions): CustomRecursionHandler | MergeOptions | undefined {
+  return typeof option === 'function' ? option : typeof option === 'string' ? _builtinHandlers[option] : undefined;
+}
+
+/** pass array configurations down, this allows for saying all arrays should be appended rather than replaced */
+function getTypesMixin(config: MergeOptions): MergeOptions {
+  return config.array ? { array: config.array } : {};
+}
+
+/** resolve the object behaviors for configuration */
+function resolveForObject(option: RecursionHandler | RecursionOption | MergeOptions, mixin: MergeOptions): MergeOptions | undefined {
+  if (typeof option === 'boolean') {
+    // booleans won't recurse if false, otherwise recurse infinitely
+    return option ? { object: option, ...mixin } : mixin;
+  } else if (typeof option === 'number') {
+    // numbers get decremented or set to false if we've reached zero.  Negative values will have been converted to boolean true
+    return option === 0 ? mixin : { object: option - 1, ...mixin };
+  } else {
+    // otherwise it is an object type so just pass the child object through
+    return option as MergeOptions;
+  }
+}
+
+/**
+ * Figure out the handler for this property.
+ * It will either be a function, a config object to pass to a recursive call, or undefined
+ * in the undefined case, this key will be left as-is
+ */
+function getHandlerForPropertyOfType(
+  config: MergeOptions,
+  propKey: string,
+  propType: string,
+): CustomRecursionHandler | MergeOptions | undefined {
+  let result: CustomRecursionHandler | MergeOptions | undefined = undefined;
+  const option = config[propKey] !== undefined ? config[propKey] : config[propType] !== undefined ? config[propType] : undefined;
+
+  if (option !== undefined) {
+    // try to resolve the option as a handler, either function or built-in first.  This is the only option that is valid for non-object types.
+    result = resolveIfHandler(option);
+
+    // if it is an object then resolve boolean, number or config types
+    if (result === undefined && propType === 'object') {
+      result = resolveForObject(option, getTypesMixin(config));
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Assign properties of source objects to a new target object. This is just a type wrapper around Object.assign
+ * @param objs - array of objects to merge
+ * @returns the result of object assign on the objects, typed to T
+ */
+function assignToNewObject<T extends ObjectBase>(...objs: T[]): T {
+  return Object.assign({}, ...objs);
+}
+
+/**
+ * Filter a set of unknown values to only include those that extend ObjectBase
+ * @param values - array of values to filter
+ * @returns the filtered set of values
+ */
+export function filterToObjects<T extends ObjectBase = ObjectBase>(values: unknown[]): T[] {
+  return values.filter((v) => v && getEntityType(v) === 'object' && Object.getOwnPropertyNames(v).length > 0) as T[];
+}
+
+/**
+ * This will merge two or more objects together using an immutable style merge pattern.  If there is only one object or
+ * if there is only one object with values, that object itself will be returned, with two or more objects the keys within will
+ * be first merged with Object.assign and then optionally will recurse to merge sub objects as specified by the options.
+ *
+ * Note that this tries hard to not create extra objects, because of this merging an object with an empty object will not
+ * create a new object.
+ *
+ * @param mergeOptions - options driving behavior of the merge.  See MergeOptions for a description
+ * @param singleMode - normally if there is only one branch to follow in the merge the routine will not recurse.  If single mode
+ * is true the routine will progress through all branches of the hierarchy.  Useful if using a processor function that needs to be run.
+ * @param objs - an array of objects to merge together
+ */
+function immutableMergeWorker<T extends ObjectBase>(mergeOptions: RecursionOption | MergeOptions, singleMode: boolean, ...objs: T[]): T {
+  const setToMerge = filterToObjects<T>(objs);
+  const [options, mightRecurse] = normalizeOptions(mergeOptions);
+  const processSingle = singleMode && setToMerge.length === 1;
+
+  // there is work to do if there is more than one object to merge or if we are processing single objects
+  if (setToMerge.length > 1 || (processSingle && setToMerge.length === 1)) {
+    // now assign everything to get the normal property precedence (and merge all the keys)
+    let result = processSingle ? undefined : assignToNewObject(...setToMerge);
+    const processSet = result || setToMerge[0];
+
+    for (const key in processSet) {
+      if (processSet.hasOwnProperty(key)) {
+        // only process if there is potential work to do
+        if (mightRecurse) {
+          const originalVal = processSet[key];
+          const entityType = getEntityType(originalVal);
+          const handler = getHandlerForPropertyOfType(options, key, entityType);
+          if (handler !== undefined) {
+            const values = setToMerge.map((set) => set[key]).filter((v) => v !== undefined);
+            const updatedVal =
+              typeof handler === 'function'
+                ? handler(...values)
+                : immutableMergeWorker<ObjectBase>(handler, singleMode, ...filterToObjects(values));
+            if (updatedVal !== originalVal) {
+              result = result || assignToNewObject(...setToMerge);
+              result[key] = updatedVal;
+            }
+          }
+        }
+
+        // delete undefined keys from the object, otherwise there is no easy way to delete keys
+        if (!processSingle && result[key] === undefined) {
+          delete result[key];
+        }
+      }
+    }
+
+    // in the single processing case return the original if nothing changed, otherwise return result
+    return result || processSet;
+  }
+  return setToMerge.length > 0 ? setToMerge[0] : undefined;
+}
+
+/**
+ * Recursively immutable merge sets of objects infinitely deep.  This behaves like a standard deep merge with arrays replacing
+ * one another rather than appending.  If appending arrays is desireable this can be configured via immutableMergeCore
+ *
+ * @param objs - variable input array of typed objects to merge
+ */
+export function immutableMerge<T extends ObjectBase>(...objs: (T | undefined)[]): T | undefined {
+  return immutableMergeWorker(true, false, ...objs);
+}
+
+/**
+ * Version of immutable merge that can be configured to behave in a variety of manners.  See the documentation for details.
+ *
+ * @param options - configuration options for the merge, this dictates what keys will be handled in what way
+ * @param objs - set of objects to merge together
+ */
+export function immutableMergeCore<T extends ObjectBase>(
+  options: RecursionOption | MergeOptions,
+  ...objs: (T | undefined)[]
+): T | undefined {
+  return immutableMergeWorker(options, false, ...objs);
+}
+
+/**
+ * Process one or more immutable objects ensuring that handlers are called on every entry that applies.  If a single object
+ * is passed in and no changes are made, that object will be returned.  If updates happen from the handlers it will return the
+ * minimally mutated object.
+ *
+ * The use case for this might be a style transformation on a deeply nested object.  If no changes are made the object won't be
+ * updated but in the case where something needs to be transformed this will perform the minimal mutations.
+ *
+ * @param processors - set of processor functions for handling keys
+ * @param objs - one or more objects to process.  If multiple objects are passed they will be merged
+ */
+export function processImmutable<T extends ObjectBase>(options: MergeOptions, ...objs: (T | undefined)[]): T | undefined {
+  return immutableMergeWorker(options, true, ...objs);
+}

package/src/index.ts

@@ -0,0 +1,20 @@
+// immutable-merge exports
+export { immutableMerge, immutableMergeCore, processImmutable, filterToObjects } from './immutable-merge/Merge';
+export type {
+  BuiltinRecursionHandlers,
+  CustomRecursionHandler,
+  MergeOptions,
+  ObjectBase,
+  RecursionHandler,
+  RecursionOption,
+} from './immutable-merge/Merge';
+
+// memo-cache exports
+export type { GetMemoValue } from './memo-cache/getMemoCache';
+export { getMemoCache } from './memo-cache/getMemoCache';
+export { memoize } from './memo-cache/memoize';
+
+// merge-props exports
+export type { StyleProp } from './merge-props/mergeStyles.types';
+export { mergeStyles } from './merge-props/mergeStyles';
+export { mergeProps } from './merge-props/mergeProps';