@ibgib/ts-gib 0.4.9

package/src/V1/transforms/mut8.spec.mts

@@ -0,0 +1,656 @@
+/**
+ * Test basic mut8 transforms.
+ *
+ * NOTE:
+ *   This only tests the node implementation, and manual testing
+ *   is required for browser until I get some kind of browser testing
+ *   going.
+ */
+
+import { IbGib_V1, IbGibRel8ns_V1, Rel8n } from '../types.mjs';
+import { TransformOpts_Mut8, IbGibAddr } from '../../types.mjs';
+import { pretty, clone, delay, getIbGibAddr, getIbAndGib, } from '../../helper.mjs';
+import { sha256v1, } from '../sha256v1.mjs';
+import { ROOT, ROOT_ADDR, GIB_DELIMITER } from '../constants.mjs';
+import { fork } from './fork.mjs';
+import { mut8 } from './mut8.mjs';
+import { Factory_V1 as factory } from '../factory.mjs';
+import { getGib, getGibInfo } from './transform-helper.mjs';
+
+const PRIMITIVE_IBGIBS = [factory.root()].concat(factory.primitives({
+    ibs: [
+        'a', '7', 'tag',
+        'any string/value that isnt hashed with a gib is a primitive',
+        // e.g. 6 -> 6^ -> 6^gib are all equivalent ib^gib addresses,
+    ]
+}));
+
+const STR = 'string here';
+const RENAME_ME_KEY = 'rename me please';
+const RENAMED_KEY = 'renamed successfully';
+const RENAME_VALUE = 'hey heres a value';
+const DATA_SIMPLE_XY = { x: 1, y: 2 };
+const DATA_SIMPLE_XY_STR = { x: 1, y: 2, str: STR };
+const DATA_COMPLEX_XY_NESTED = {
+    xyObj: DATA_SIMPLE_XY,
+    nested1: { [RENAME_ME_KEY]: RENAME_VALUE },
+};
+const NEW_IB = 'new ib here yo';
+
+const DATAS_SIMPLE = [
+    DATA_SIMPLE_XY,
+    DATA_SIMPLE_XY_STR,
+];
+
+describe(`can't mut8 primitives (including the root)`, () => {
+    for (const src of PRIMITIVE_IBGIBS) {
+
+        it(`should fail to mut8 ib (ib: ${src.ib})`, async () => {
+            let errored = false;
+            try {
+                const _ignored = await mut8({ src, mut8Ib: 'changed ' + src.ib });
+            } catch (error) {
+                errored = true;
+            }
+            expect(errored).toBeTrue()
+        });
+
+        it(`should fail to mut8 add or patch data (ib: ${src.ib})`, async () => {
+            let errored = false;
+            try {
+                const _ignored = await mut8({ src, dataToAddOrPatch: { a: "aaaaa" } });
+            } catch (error) {
+                errored = true;
+            }
+            expect(errored).toBeTrue()
+        });
+
+        it(`should fail to mut8 rename data (ib: ${src.ib})`, async () => {
+            let errored = false;
+            try {
+                const _ignored = await mut8({ src, dataToRename: { a: "aaaaa" } });
+            } catch (error) {
+                errored = true;
+            }
+            expect(errored).toBeTrue()
+        });
+
+        it(`should fail to mut8 remove data (ib: ${src.ib})`, async () => {
+            let errored = false;
+            try {
+                const _ignored = await mut8({ src, dataToRemove: { a: "aaaaa" } });
+            } catch (error) {
+                errored = true;
+            }
+            expect(errored).toBeTrue()
+        });
+    }
+});
+
+describe(`when mutating a regular ibgib`, () => {
+
+    describe(`with simple, 1-level, non-nested data and ib`, () => {
+        for (const primitive of PRIMITIVE_IBGIBS) {
+            for (const testData of DATAS_SIMPLE) {
+                // console.log(`doing testdata: ${primitive.ib}.data ~ ${pretty(testData)}`);
+                it(`should add/rename/patch simple data (${primitive.ib}) and ib`, async () => {
+
+                    let { newIbGib: src } = await fork({ src: primitive, noTimestamp: true });
+
+                    // #region add data
+
+                    // we now have a non-primitive source and wish to
+                    // add some internal data to it.
+
+                    let { newIbGib: dataAddedIbGib } = await mut8({
+                        src,
+                        dataToAddOrPatch: testData,
+                        noTimestamp: true,
+                        linkedRel8ns: ['past'],
+                    });
+                    let dataAddedAddr: IbGibAddr = getIbGibAddr({ ibGib: dataAddedIbGib });
+                    expect(dataAddedIbGib).toBeTruthy();
+                    expect(dataAddedIbGib.data).toBeTruthy();
+                    expect(dataAddedIbGib.data).toBeTruthy();
+                    expect(dataAddedIbGib.data).toEqual(testData);
+                    expect(dataAddedIbGib.rel8ns).toBeTruthy();
+                    expect(dataAddedIbGib.rel8ns!.past).toBeTruthy();
+                    expect((dataAddedIbGib.rel8ns!.past || []).length)
+                        .withContext('(dataAddedIbGib.rel8ns!.past || []).length')
+                        .toEqual(1);
+
+                    // #endregion
+
+                    // #region rename
+
+                    const newNameForX = "new name for x here";
+                    const valueForX = dataAddedIbGib.data!.x;
+                    const dataToRename = { x: newNameForX }
+
+                    let { newIbGib: dataRenamedIbGib } =
+                        await mut8({
+                            src: dataAddedIbGib,
+                            dataToRename,
+                            noTimestamp: true,
+                            linkedRel8ns: ['past'],
+                        });
+                    expect(dataRenamedIbGib).toBeTruthy();
+                    expect(dataRenamedIbGib.data).toBeTruthy();
+                    expect(dataRenamedIbGib.data).toBeTruthy();
+                    expect(dataRenamedIbGib.rel8ns).toBeTruthy();
+                    expect(dataRenamedIbGib.rel8ns!.past).toBeTruthy();
+                    expect((dataRenamedIbGib.rel8ns!.past || []).length)
+                        .withContext('dataRenamedIbGib.rel8ns!.past || []).length')
+                        .toEqual(1);
+
+                    // the data should have the new key name that we did
+                    expect(Object.keys(dataRenamedIbGib.data!)).toContain(newNameForX);
+
+                    // the data value for that new key name should be the same as before, since we didn't change it
+                    expect(dataRenamedIbGib.data![newNameForX]).toEqual(valueForX);
+
+                    // the most recent past of the dataRenamed ibGib should be the src's (dataAddedIbGib) address
+                    expect(dataRenamedIbGib.rel8ns!.past![dataRenamedIbGib.rel8ns!.past!.length - 1]).toEqual(dataAddedAddr);
+
+                    //#endregion
+
+                    // #region patch
+
+                    const newValueForX = 42;
+                    const dataToPatch = { x: newValueForX }
+
+                    let { newIbGib: dataPatchedIbGib } =
+                        await mut8({ src: dataAddedIbGib, dataToAddOrPatch: dataToPatch, noTimestamp: true });
+                    expect(dataPatchedIbGib).toBeTruthy();
+                    expect(dataPatchedIbGib.data).toBeTruthy();
+                    expect(dataPatchedIbGib.data).toBeTruthy();
+
+                    // value should be changed to the new value
+                    expect(dataPatchedIbGib.data!.x).toEqual(newValueForX);
+
+                    // the most recent past of the dataRenamed ibGib should be the src's (dataAddedIbGib) address
+                    expect(dataPatchedIbGib.rel8ns!.past![dataPatchedIbGib.rel8ns!.past!.length - 1]).toEqual(dataAddedAddr);
+
+                    //#endregion
+
+                    // #region remove
+
+                    const dataToRemove = { x: '' }; // just want mapping, value is ignored
+
+                    let { newIbGib: dataRemovedIbGib } =
+                        await mut8({ src: dataAddedIbGib, dataToRemove, noTimestamp: true });
+                    expect(dataRemovedIbGib).toBeTruthy();
+                    expect(dataRemovedIbGib.data).toBeTruthy();
+                    expect(dataRemovedIbGib.data).toBeTruthy();
+
+                    // the data value for that new key name should be the same as before, since we didn't change it
+                    expect(dataRemovedIbGib.data!.x).toBeUndefined();
+
+                    // the most recent past of the dataRemovedIbGib should be the src's address
+                    expect(dataRemovedIbGib.rel8ns!.past![dataRemovedIbGib.rel8ns!.past!.length - 1]).toEqual(dataAddedAddr);
+
+                    //#endregion
+
+                    // #region ib
+
+                    let { newIbGib: ibMut8dIbGib } =
+                        await mut8({ src: dataAddedIbGib, mut8Ib: NEW_IB, noTimestamp: true });
+                    expect(ibMut8dIbGib).toBeTruthy();
+                    expect(ibMut8dIbGib.ib).toEqual(NEW_IB);
+
+                    //#endregion
+                });
+
+
+                it(`should be rel8d next mut8`, async () => {
+                    const { newIbGib: tjpIbGib } = await fork({
+                        src: primitive,
+                        destIb: 'some ib yo',
+                        tjp: { timestamp: true, uuid: true },
+                    });
+                    const tjpAddr = getIbGibAddr({ ibGib: tjpIbGib });
+                    const tjpAddrGib = getIbAndGib({ ibGibAddr: tjpAddr }).gib;
+                    expect(tjpIbGib!.data?.uuid).toBeTruthy();
+                    expect(tjpIbGib!.data?.isTjp).withContext("isTjp").toBeTrue()
+                    const { newIbGib: hasRel8dTjp } = await mut8({
+                        src: tjpIbGib,
+                        dataToAddOrPatch: { someData: "not intrinsically pertinent to this test" },
+                    });
+                    const hasRel8dTjpAddr = getIbGibAddr({ ibGib: hasRel8dTjp });
+                    const hasRel8dTjpAddrGib = getIbAndGib({ ibGibAddr: hasRel8dTjpAddr }).gib;
+                    expect(hasRel8dTjp!.data?.uuid).toBeTruthy();
+                    expect(hasRel8dTjp!.data?.isTjp).withContext("isTjp after additional mut8").toBeUndefined();
+                    expect(hasRel8dTjp!.rel8ns).withContext("rel8ns").toBeTruthy();
+                    expect(hasRel8dTjp!.rel8ns!.tjp).withContext("rel8ns.tjp").toBeTruthy();
+                    expect(hasRel8dTjp!.rel8ns!.tjp!.length).withContext("rel8ns.tjp.length").toEqual(1);
+                    expect(hasRel8dTjp!.rel8ns!.tjp).withContext("rel8ns.tjp include").toContain(tjpAddr);
+
+                    // the gib should not just be the hash, since it has a tjp timeline
+                    expect(hasRel8dTjpAddrGib).toContain(tjpAddrGib);
+
+                    // shoe-horning in here some getGibInfo testing...eesh
+                    let hasRel8dTjpGibInfo = getGibInfo({ ibGibAddr: hasRel8dTjpAddr }); // via addr
+                    expect(hasRel8dTjpGibInfo.isPrimitive).toBeUndefined();
+                    expect(hasRel8dTjpGibInfo.piecesCount).toEqual(2, 'pieces count');
+                    const hasRel8dTjpHash = await sha256v1(hasRel8dTjp, '');
+                    expect(hasRel8dTjpGibInfo.punctiliarHash).toEqual(hasRel8dTjpHash, 'punctiliarHash');
+                    expect(hasRel8dTjpGibInfo.tjpGib).toEqual(tjpAddrGib);
+                    // the info should be the same if we get it straight from the gib
+                    const hasRel8dTjpGibInfo_viaGib = getGibInfo({ gib: hasRel8dTjpAddrGib }); // via gib
+                    expect(hasRel8dTjpGibInfo_viaGib).toEqual(hasRel8dTjpGibInfo, 'infos via addr and gib should be equal');
+                });
+            }
+        } // double for..of statement
+    })
+
+    describe(`...and creating dna`, () => {
+        var src: IbGib_V1, forkDnas: IbGib_V1[],
+            // these are used later when reapplying dnas to test pure functionality
+            addDna: IbGib_V1, dataAddedIbGib1: IbGib_V1,
+            patchDna: IbGib_V1, dataPatchedIbGib1: IbGib_V1,
+            renameDna: IbGib_V1, dataRenamedIbGib1: IbGib_V1,
+            removeDna: IbGib_V1, dataRemovedIbGib1: IbGib_V1;
+        beforeAll(async () => {
+            const resInit = await fork({ src: ROOT, dna: true });
+            src = resInit.newIbGib;
+            forkDnas = resInit.dnas!;
+        })
+
+        it(`should have well-formed dna...`, async () => {
+
+            // #region data added
+
+            const srcAddr = getIbGibAddr({ ibGib: src });
+            const dataToAdd = DATA_SIMPLE_XY;
+            const { newIbGib: dataAddedIbGib, dnas: Mut8AddDnas } =
+                await mut8({ src, dna: true, dataToAddOrPatch: dataToAdd });
+            dataAddedIbGib1 = dataAddedIbGib; // for later testing pure functionality
+            const dataAddedAddr = getIbGibAddr({ ibGib: dataAddedIbGib });
+
+            let mut8Dna = Mut8AddDnas![0];
+            addDna = mut8Dna;
+
+            expect(mut8Dna.ib).withContext(`ib should be mut8`).toEqual('mut8');
+
+            {
+                expect(mut8Dna?.rel8ns).withContext(`should descend from mut8^gib primitive`).toBeTruthy();
+                const mut8DnaRel8ns: IbGibRel8ns_V1 = mut8Dna?.rel8ns!;
+                expect(mut8DnaRel8ns.ancestor).withContext(`should descend from mut8^gib primitive`).toBeTruthy();
+                expect(mut8DnaRel8ns.ancestor!.length).withContext(`should descend from mut8^gib primitive`).toEqual(1);
+                expect(mut8DnaRel8ns.ancestor![0]).withContext(`should descend from mut8^gib primitive`).toEqual('mut8^gib');
+
+                const mut8DnaData = (mut8Dna.data as TransformOpts_Mut8<IbGib_V1>)!;
+
+                expect(mut8DnaData).withContext(`should have well-formed common transform opts`).toBeTruthy();
+                expect(mut8DnaData).withContext(`should have well-formed common transform opts`).toBeTruthy();
+                expect(mut8DnaData.dna).withContext(`should have well-formed common transform opts`).toBeTrue()
+                expect(mut8DnaData.srcAddr).withContext(`should have well-formed common transform opts`).toBeUndefined();
+                expect(mut8DnaData.src).withContext(`should have well-formed common transform opts`).toBeUndefined();
+
+                expect(mut8DnaData.type).withContext(`should have well-formed data specific to type of mut8`).toEqual("mut8");
+                expect(mut8DnaData.dataToAddOrPatch).withContext(`should have well-formed data specific to type of mut8`).toEqual(dataToAdd);
+            }
+            // #endregion
+
+            // #region data patched
+
+            {
+                const dataToPatch = { z: '3' };
+                const { newIbGib: dataPatchedIbGib, dnas: patchedDnas } =
+                    await mut8({ src: dataAddedIbGib, dna: true, dataToAddOrPatch: dataToPatch });
+                dataPatchedIbGib1 = dataPatchedIbGib; // for later testing pure functionality
+
+                mut8Dna = patchedDnas![0];
+                patchDna = mut8Dna;
+
+                expect(mut8Dna.ib).withContext(`data patched, ib should be mut8`).toEqual('mut8');
+                expect(mut8Dna?.rel8ns).withContext(`data patched, should descend from mut8^gib primitive`).toBeTruthy();
+                const mut8DnaRel8ns: IbGibRel8ns_V1 = mut8Dna?.rel8ns!;
+                expect(mut8DnaRel8ns.ancestor).withContext(`data patched, should descend from mut8^gib primitive`).toBeTruthy();
+                expect(mut8DnaRel8ns.ancestor!.length).toEqual(1);
+                expect(mut8DnaRel8ns.ancestor![0]).toEqual('mut8^gib');
+
+                const mut8DnaData = (mut8Dna.data as TransformOpts_Mut8<IbGib_V1>)!;
+
+                expect(mut8DnaData).withContext(`data patched, should have well-formed common transform opts`).toBeTruthy();
+                expect(mut8DnaData).withContext(`data patched, should have well-formed common transform opts`).toBeTruthy();
+                expect(mut8DnaData.dna).withContext(`data patched, should have well-formed common transform opts`).toBeTrue()
+                expect(mut8DnaData.srcAddr).withContext(`data patched, should have well-formed common transform opts`).toBeUndefined();
+                expect(mut8DnaData.src).withContext(`data patched, should have well-formed common transform opts`).toBeUndefined();
+                expect(mut8DnaData.type).withContext(`data patched, should have well-formed data specific to type of mut8`).toEqual("mut8");
+                expect(mut8DnaData.dataToAddOrPatch).withContext(`data patched, should have well-formed data specific to type of mut8`).toEqual(dataToPatch);
+            }
+            // #endregion
+
+            // #region data renamed
+            {
+                const dataToRename = { x: RENAMED_KEY };
+                const { newIbGib: dataRenamedIbGib, dnas: renamedDnas } =
+                    await mut8({ src: dataAddedIbGib, dna: true, dataToRename });
+                dataRenamedIbGib1 = dataRenamedIbGib; // for later testing pure functionality
+
+                mut8Dna = renamedDnas![0];
+                renameDna = mut8Dna;
+
+                expect(mut8Dna.ib).withContext(`data renamed, ib should be mut8`).toEqual('mut8');
+                expect(mut8Dna?.rel8ns).withContext(`data renamed, should descend from mut8^gib primitive`).toBeTruthy();
+                const mut8DnaRel8ns: IbGibRel8ns_V1 = mut8Dna?.rel8ns!;
+                expect(mut8DnaRel8ns.ancestor).withContext(`data renamed, should descend from mut8^gib primitive`).toBeTruthy();
+                expect(mut8DnaRel8ns.ancestor!.length).withContext(`data renamed, should descend from mut8^gib primitive`).toEqual(1);
+                expect(mut8DnaRel8ns.ancestor![0]).withContext(`data renamed, should descend from mut8^gib primitive`).toEqual('mut8^gib');
+
+                const mut8DnaData = (mut8Dna.data as TransformOpts_Mut8<IbGib_V1>)!;
+
+                expect(mut8DnaData).withContext(`data renamed, should have well-formed common transform opts`).toBeTruthy();
+                expect(mut8DnaData).withContext(`data renamed, should have well-formed common transform opts`).toBeTruthy();
+                expect(mut8DnaData.dna).withContext(`data renamed, should have well-formed common transform opts`).toBeTrue()
+                expect(mut8DnaData.srcAddr).withContext(`data renamed, should have well-formed common transform opts`).toBeUndefined();
+                expect(mut8DnaData.src).withContext(`data renamed, should have well-formed common transform opts`).toBeUndefined();
+
+                expect(mut8DnaData.type).withContext(`data renamed, should have well-formed data specific to type of mut8`).toEqual("mut8");
+                expect(mut8DnaData.dataToRename).withContext(`data renamed, should have well-formed data specific to type of mut8`).toEqual(dataToRename);
+            }
+            // #endregion
+
+            // #region test remove dna
+
+            {
+                const dataToRemove = { y: '' }; // value is ignored when removing, just want mapping to key
+                const { newIbGib: dataRemovedIbGib, dnas: removedDnas } =
+                    await mut8({ src: dataAddedIbGib, dna: true, dataToRemove });
+                dataRemovedIbGib1 = dataRemovedIbGib; // for later testing pure functionality
+
+                mut8Dna = removedDnas![0];
+                removeDna = mut8Dna;
+
+                expect(mut8Dna.ib).withContext(`data removed, ib should be mut8`).toEqual('mut8');
+                expect(mut8Dna?.rel8ns).withContext(`data removed, should descend from mut8^gib primitive`).toBeTruthy();
+                const mut8DnaRel8ns: IbGibRel8ns_V1 = mut8Dna?.rel8ns!;
+                expect(mut8DnaRel8ns.ancestor).withContext(`data removed, should descend from mut8^gib primitive`).toBeTruthy();
+                expect(mut8DnaRel8ns.ancestor!.length).withContext(`data removed, should descend from mut8^gib primitive`).toEqual(1);
+                expect(mut8DnaRel8ns.ancestor![0]).withContext(`data removed, should descend from mut8^gib primitive`).toEqual('mut8^gib');
+
+                const mut8DnaData = (mut8Dna.data as TransformOpts_Mut8<IbGib_V1>)!;
+
+                expect(mut8DnaData).withContext(`data removed, should have well-formed common transform opts`).toBeTruthy();
+                expect(mut8DnaData).withContext(`data removed, should have well-formed common transform opts`).toBeTruthy();
+                expect(mut8DnaData.dna).withContext(`data removed, should have well-formed common transform opts`).toBeTrue()
+                expect(mut8DnaData.srcAddr).withContext(`data removed, should have well-formed common transform opts`).toBeUndefined();
+                expect(mut8DnaData.src).withContext(`data removed, should have well-formed common transform opts`).toBeUndefined();
+
+                expect(mut8DnaData.type).withContext(`data removed, should have well-formed data specific to type of mut8`).toEqual("mut8");
+                expect(mut8DnaData.dataToRemove).withContext(`data removed, should have well-formed data specific to type of mut8`).toEqual(dataToRemove);
+            }
+
+            // #endregion
+
+            // #region pure dna functionality (placed here for code reuse, but slightly icky)
+
+            // we're going to repeat our transforms but using the dnas generated in the previous steps.
+            // (kinda like translating a foreign language translation back into the
+            // original language and making sure it says the same thing)
+            // we should produce an entirely new ibGib, because the first newIbGib was timestamped.
+            // but the dna "produced" (recreated) should be exactly the same as our initial dna.
+
+            // timestamp should be different (at least 1 second) making newIbGib2 unique
+
+            // these are the vars from above.
+            // let addDna: IbGib_V1, dataAddedIbGib1: IbGib_V1,
+            //     patchedDna: IbGib_V1, dataPatchedIbGib1: IbGib_V1,
+            //     renamedDna: IbGib_V1, dataRenamedIbGib1: IbGib_V1,
+            //     removedDna: IbGib_V1, dataRemovedIbGib1: IbGib_V1;
+            {
+                await delay(1010); // delay at least 1 second to guarantee UTC timestamp shows +1 second in timestamp
+                const optsClone: TransformOpts_Mut8<IbGib_V1> = clone(addDna!.data);
+                optsClone.src = src;
+                const { newIbGib: newIbGib2, dnas: dnas2 } = await mut8(optsClone);
+                expect(newIbGib2).withContext(`should be pure add mutation (expect delay)`).toBeTruthy();
+                expect(dnas2).withContext(`should be pure add mutation (expect delay)`).toBeTruthy();
+                const dna2 = dnas2![0];
+
+                // dna itself should be exactly the same
+                expect(dna2).withContext(`should be pure add mutation (expect delay)`).toEqual(addDna);
+
+                // the ibGibs **created** should NOT be the same because of timestamping
+                // (and later on, other factors would change like identity and other rel8ns)
+                expect(newIbGib2.gib).withContext(`should be pure add mutation (expect delay)`).not.toEqual(dataAddedIbGib1.gib);
+            }
+            {
+                await delay(500);
+                const optsClone: TransformOpts_Mut8<IbGib_V1> = clone(patchDna!.data);
+                optsClone.src = dataAddedIbGib1;
+                const { newIbGib: newIbGib2, dnas: dnas2 } = await mut8(optsClone);
+                expect(newIbGib2).withContext(`should be pure patch mutation (expect delay)`).toBeTruthy();
+                expect(dnas2).withContext(`should be pure patch mutation (expect delay)`).toBeTruthy();
+                const dna2 = dnas2![0];
+
+                // dna itself should be exactly the same
+                expect(dna2).withContext(`should be pure patch mutation (expect delay)`).toEqual(patchDna);
+
+                // the ibGibs **created** should NOT be the same because of timestamping
+                // (and later on, other factors would change like identity and other rel8ns)
+                expect(newIbGib2.gib).withContext(`should be pure patch mutation (expect delay)`).not.toEqual(dataPatchedIbGib1.gib);
+            }
+            {
+                await delay(500);
+                const optsClone: TransformOpts_Mut8<IbGib_V1> = clone(renameDna!.data);
+                optsClone.src = dataAddedIbGib1;
+                const { newIbGib: newIbGib2, dnas: dnas2 } = await mut8(optsClone);
+                expect(newIbGib2).withContext(`should be pure rename mutation (expect delay)`).toBeTruthy();
+                expect(dnas2).withContext(`should be pure rename mutation (expect delay)`).toBeTruthy();
+                const dna2 = dnas2![0];
+
+                // dna itself should be exactly the same
+                expect(dna2).withContext(`should be pure rename mutation (expect delay)`).toEqual(renameDna);
+
+                // the ibGibs **created** should NOT be the same because of timestamping
+                // (and later on, other factors would change like identity and other rel8ns)
+                expect(newIbGib2.gib).withContext(`should be pure rename mutation (expect delay)`).not.toEqual(dataRenamedIbGib1.gib);
+            }
+            {
+                await delay(500);
+                const optsClone: TransformOpts_Mut8<IbGib_V1> = clone(removeDna!.data);
+                optsClone.src = dataAddedIbGib1;
+                const { newIbGib: newIbGib2, dnas: dnas2 } = await mut8(optsClone);
+                expect(newIbGib2).withContext(`should be pure remove mutation (expect delay)`).toBeTruthy();
+                expect(dnas2).withContext(`should be pure remove mutation (expect delay)`).toBeTruthy();
+                const dna2 = dnas2![0];
+
+                // dna itself should be exactly the same
+                expect(dna2).withContext(`should be pure remove mutation (expect delay)`).toEqual(removeDna);
+
+                // the ibGibs **created** should NOT be the same because of timestamping
+                // (and later on, other factors would change like identity and other rel8ns)
+                expect(newIbGib2.gib).withContext(`should be pure remove mutation (expect delay)`).not.toEqual(dataRemovedIbGib1.gib);
+            }
+
+            // #endregion
+        });
+
+    }); // dna
+
+    describe(`with more complex data`, () => {
+        for (const primitive of PRIMITIVE_IBGIBS) {
+            it(`should add/rename/patch (${primitive.ib})`, async () => {
+
+                let { newIbGib: src } = await fork({ src: primitive, noTimestamp: true });
+
+                // #region add data
+
+                // we now have a non-primitive source and wish to
+                // add some internal data to it.
+
+                let { newIbGib: dataAddedIbGib } = await mut8({
+                    src,
+                    dataToAddOrPatch: DATA_COMPLEX_XY_NESTED,
+                    noTimestamp: true
+                });
+                let dataAddedAddr: IbGibAddr = getIbGibAddr({ ibGib: dataAddedIbGib });
+                expect(dataAddedIbGib).toBeTruthy();
+                expect(dataAddedIbGib.data).toBeTruthy();
+                expect(dataAddedIbGib.data).toBeTruthy();
+                expect(dataAddedIbGib.data).toEqual(DATA_COMPLEX_XY_NESTED);
+
+                // #endregion
+
+                // #region rename
+
+                // since it's freezing already, I suppose today I'll have to code offline...or off stream that is.
+                const valueForX = dataAddedIbGib.data!.x;
+                const dataToRename = {
+                    nested1: { [RENAME_ME_KEY]: RENAMED_KEY }
+                };
+
+                let { newIbGib: dataRenamedIbGib } =
+                    await mut8({ src: dataAddedIbGib, dataToRename, noTimestamp: true });
+                // let dataRenamedAddr: IbGibAddr = getIbGibAddr({ibGib: dataRenamedIbGib});
+                expect(dataRenamedIbGib).toBeTruthy();
+                expect(dataRenamedIbGib.data).toBeTruthy();
+                expect(dataRenamedIbGib.data).toBeTruthy();
+
+                // the data should have the new key name that we did
+                expect(dataRenamedIbGib.data!.nested1).toBeTruthy();
+                expect(dataRenamedIbGib.data!.nested1![RENAME_ME_KEY]).toBeUndefined();
+                expect(dataRenamedIbGib.data!.nested1![RENAMED_KEY]).toBeTruthy();
+
+                // the data value for that new key name should be the same as before, since we didn't change it
+                expect(dataRenamedIbGib.data!.nested1![RENAMED_KEY]).toEqual(RENAME_VALUE);
+
+                // the most recent past of the dataRenamed ibGib should be the src's (dataAddedIbGib) address
+                expect(dataRenamedIbGib.rel8ns!.past![dataRenamedIbGib.rel8ns!.past!.length - 1]).toEqual(dataAddedAddr);
+
+                //#endregion
+
+                // #region patch
+
+                const newValueForX = 42;
+                const dataToPatch = { xyObj: { x: newValueForX } };
+
+                let { newIbGib: dataPatchedIbGib } =
+                    await mut8({ src: dataAddedIbGib, dataToAddOrPatch: dataToPatch, noTimestamp: true });
+                expect(dataPatchedIbGib).toBeTruthy();
+                expect(dataPatchedIbGib.data).toBeTruthy();
+                expect(dataPatchedIbGib.data).toBeTruthy();
+                expect(dataPatchedIbGib.data!.xyObj).toBeTruthy();
+
+                // value should be changed to the new value
+                expect(dataPatchedIbGib.data!.xyObj!.x).toEqual(newValueForX);
+
+                // the most recent past of the dataRenamed ibGib should be the src's (dataAddedIbGib) address
+                expect(dataPatchedIbGib.rel8ns!.past![dataPatchedIbGib.rel8ns!.past!.length - 1]).toEqual(dataAddedAddr);
+
+                //#endregion
+
+                // #region remove
+
+                const dataToRemove = { xyObj: { x: '' } }; // just want mapping, value is ignored
+
+                let { newIbGib: dataRemovedIbGib } =
+                    await mut8({ src: dataAddedIbGib, dataToRemove, noTimestamp: true });
+                expect(dataRemovedIbGib).toBeTruthy();
+                expect(dataRemovedIbGib.data).toBeTruthy();
+                expect(dataRemovedIbGib.data).toBeTruthy();
+
+                // the data value for that new key name should be the same as before, since we didn't change it
+                expect(dataRemovedIbGib.data!.xyObj).toBeTruthy();
+                expect(dataRemovedIbGib.data!.xyObj!.x).toBeUndefined();
+
+                // the most recent past of the dataRemovedIbGib should be the src's address
+                expect(dataRemovedIbGib.rel8ns!.past![dataRemovedIbGib.rel8ns!.past!.length - 1]).toEqual(dataAddedAddr);
+
+                //#endregion
+            });
+        }
+    })
+
+    describe(`nCounter`, () => {
+        it(`should increment existing n counter`, async () => {
+            for (const primitive of PRIMITIVE_IBGIBS) {
+                let { newIbGib: src_0 } =
+                    await fork({ src: primitive, nCounter: true });
+
+                expect(src_0.data).toBeTruthy();
+                expect(src_0.data).toBeTruthy();
+                expect(src_0.data!.n).toEqual(0);
+
+                let { newIbGib: src_1 } =
+                    await mut8({
+                        src: src_0,
+                        dataToAddOrPatch: DATA_SIMPLE_XY,
+                        nCounter: true
+                    });
+                expect(src_1.data).toBeTruthy();
+                expect(src_1.data).toBeTruthy();
+                expect(src_1.data!.n).toBeTruthy();
+                expect(src_1.data!.n).toBeTruthy();
+                expect(src_1.data!.n).toEqual(1);
+            }
+        });
+        it(`should start new n counter, implicit nCounter falsy`, async () => {
+            for (const primitive of PRIMITIVE_IBGIBS) {
+                let { newIbGib: src_0 } =
+                    await fork({ src: primitive, noTimestamp: true });
+
+                expect(src_0.data).toBeUndefined();
+
+                let { newIbGib: src_1 } =
+                    await mut8({
+                        src: src_0,
+                        dataToAddOrPatch: DATA_SIMPLE_XY,
+                        nCounter: true
+                    });
+                expect(src_1.data).toBeTruthy();
+                expect(src_1.data).toBeTruthy();
+                expect(src_1.data!.n).toEqual(0);
+            }
+        });
+        it(`should start new n counter, explicit nCounter falsy`, async () => {
+            for (const primitive of PRIMITIVE_IBGIBS) {
+                let { newIbGib: src_0 } =
+                    await fork({ src: primitive, noTimestamp: true, nCounter: false });
+
+                expect(src_0.data).toBeUndefined();
+
+                let { newIbGib: src_1 } =
+                    await mut8({
+                        src: src_0,
+                        dataToAddOrPatch: DATA_SIMPLE_XY,
+                        nCounter: true
+                    });
+                expect(src_1.data).toBeTruthy();
+                expect(src_1.data).toBeTruthy();
+                expect(src_1.data!.n).toEqual(0);
+            }
+        });
+    });
+
+    describe(`when mut8 with dna`, () => {
+        it(`should have gibs that is corroborated with getGib`, async () => {
+            for (const primitive of PRIMITIVE_IBGIBS) {
+                let { newIbGib, intermediateIbGibs, dnas } =
+                    await fork({ src: primitive, nCounter: false, dna: true });
+
+                const ibGibs_fork = [newIbGib, ...(intermediateIbGibs ?? []), ...(dnas ?? [])];
+                // we now have a non-primitive 1st gen source and wish to
+                // add rel8ns in it pointing to other ibGibs.
+
+                let resMut8 =
+                    await mut8({
+                        src: newIbGib,
+                        dataToAddOrPatch: DATA_COMPLEX_XY_NESTED,
+                        noTimestamp: true,
+                        nCounter: true,
+                        dna: true,
+                    });
+
+                const ibGibs_mut8 = [resMut8.newIbGib, ...(resMut8.intermediateIbGibs ?? []), ...(resMut8.dnas ?? [])];
+                const ibGibs = [...ibGibs_fork, ...ibGibs_mut8];
+                for (let i = 0; i < ibGibs.length; i++) {
+                    const ibGib = ibGibs[i];
+                    const gottenGib = await getGib({ ibGib });
+                    expect(ibGib.gib).toEqual(gottenGib);
+                }
+            }
+        });
+    });
+});