@ibgib/ts-gib 0.4.9

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

@@ -0,0 +1,410 @@
+/**
+ * Test basic fork transforms.
+ *
+ * A 'fork' transform creates a "new" ibgib datum by taking an existing
+ * source ibgib record (src), clones it, appends the source to the list
+ * of ancestors, and clears the ibgibs past (if any).
+ *
+ * Sometimes you want a thing to be unique when it is created (forked).
+ * When this is done, you give that first address a special name, kinda
+ * like the OPPOSITE of a HEAD revision. This is called the temporal
+ * junction point (from Back to the Future II), or just tjp. It's like
+ * the "name" of the ibgib's timeline.
+ *
+ * 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 { fork } from './fork.mjs';
+import { TransformOpts_Fork, IbGibAddr, Ib, TransformResult } from '../../types.mjs';
+import { pretty, clone, delay, getIbGibAddr } from '../../helper.mjs';
+import { ROOT, ROOT_ADDR } from '../constants.mjs';
+import { mut8 } from './mut8.mjs';
+import { getGib } from './transform-helper.mjs';
+
+describe(`when forking the root`, () => {
+
+    const src = ROOT;
+
+    it(`should create a new ibgib`, async () => {
+        const { newIbGib } = await fork({ src });
+        expect(newIbGib).toBeTruthy();
+    });
+
+    it(`should have no rel8ns (because forked from the root)`, async () => {
+        const { newIbGib } = await fork({ src });
+        expect(newIbGib.rel8ns).toBeUndefined();
+    });
+
+    describe(`should respect param`, () => {
+        it(`noTimestamp`, async () => {
+            const { newIbGib } = await fork({ src, noTimestamp: true });
+            if (newIbGib?.data) {
+                expect(newIbGib.data!.timestamp).toBeUndefined();
+            } else {
+                // data being falsy is passing so no expect statement needed
+            }
+        });
+
+        it(`destIb`, async () => {
+            // just an example, ib can be any value/metadata per use case
+            // in this example, we have a canonical form tag [tagName]
+            // this way, we can just pass around the address (tag like ^ABCD123)
+            // and operate on it (the metadata) without having to send the
+            // entire data record.
+            const destIb = 'tag like';
+            const { newIbGib } = await fork({ src, destIb });
+            expect(newIbGib.ib).toEqual(destIb);
+        });
+
+        it(`dna`, async () => {
+            // NOTE: more extensive dna testing is below in other tests
+            const destIb = "This will be the new ib";
+            const { newIbGib, dnas } = await fork({ src, dna: true, destIb });
+            expect(dnas).toBeTruthy();
+        });
+
+        it(`uuid`, async () => {
+            const { newIbGib } = await fork({ src, uuid: true });
+            expect(newIbGib?.data).toBeTruthy();
+            expect(newIbGib!.data?.uuid).toBeTruthy();
+        });
+
+        describe(`tjp...`, () => {
+            it(`timestamp`, async () => {
+                const { newIbGib } = await fork({ src, tjp: { timestamp: true } });
+                expect(newIbGib?.data).toBeTruthy();
+                expect(newIbGib!.data?.timestamp).toBeTruthy();
+                const testDate = new Date(newIbGib!.data!.timestamp!);
+                expect(testDate).toBeTruthy();
+                expect(testDate).toBeTruthy();
+                expect(testDate.toString()).not.toEqual("Invalid Date");
+                // counting on environment (node) to be consistent with invalid dates in the future
+                const invalidDate = new Date("asdf");
+                expect(invalidDate.toString()).toEqual("Invalid Date");
+                expect(newIbGib!.data?.isTjp).withContext("isTjp").toBeTrue();
+            });
+            it(`uuid`, async () => {
+                const { newIbGib } = await fork({ src, tjp: { uuid: true } });
+                expect(newIbGib?.data).toBeTruthy();
+                expect(newIbGib!.data?.uuid).toBeTruthy();
+                expect(newIbGib!.data?.isTjp).withContext("isTjp").toBeTrue()
+            });
+            it(`timestamp && uuid`, async () => {
+                const { newIbGib } = await fork({ src, tjp: { timestamp: true, uuid: true } });
+                expect(newIbGib?.data).toBeTruthy();
+                expect(newIbGib!.data?.timestamp).toBeTruthy();
+                const testDate = new Date(newIbGib!.data!.timestamp!);
+                expect(testDate).toBeTruthy();
+                expect(testDate).toBeTruthy();
+                expect(testDate.toString()).not.toEqual("Invalid Date");
+                expect(newIbGib!.data?.uuid).toBeTruthy();
+                expect(newIbGib!.data?.isTjp).withContext("isTjp").toBeTrue()
+            });
+        });
+
+        it(`nCounter`, async () => {
+            const { newIbGib } = await fork({ src, nCounter: true });
+            expect(newIbGib?.data).toBeTruthy();
+            expect(newIbGib!.data?.n).toEqual(0);
+        });
+
+
+        it(`cloneRel8ns (setting should be ignored since forking root)`, async () => {
+            const { newIbGib } = await fork({ src, cloneRel8ns: true, noTimestamp: true });
+            expect(newIbGib?.rel8ns).toBeUndefined();
+        });
+
+        it(`cloneData (setting should be ignored since forking root)`, async () => {
+            const { newIbGib } = await fork({ src, cloneData: true, noTimestamp: true });
+            expect(newIbGib?.data).toBeUndefined();
+        });
+    });
+
+    describe(`...and creating dna`, () => {
+        it(`should have well-formed dna, like...`, async () => {
+            const destIb = "This will be the new ib";
+            const { newIbGib, intermediateIbGibs, dnas } = await fork({ src, dna: true, destIb });
+            const forkDna = dnas![0];
+
+            expect(forkDna.ib).withContext(`ib should be fork`).toEqual('fork');
+
+            let ibGibs = [newIbGib, ...(intermediateIbGibs ?? []), ...(dnas ?? [])];
+            for (let i = 0; i < ibGibs.length; i++) {
+                const ibGib = ibGibs[i];
+                let gottenGib = await getGib({ ibGib });
+                expect(ibGib.gib).withContext(`should have a gib that is corroborated with getGib`).toEqual(gottenGib);
+            }
+
+            expect(forkDna?.rel8ns).withContext(`should descend from fork^gib primitive`).toBeTruthy();
+            const forkDnaRel8ns: IbGibRel8ns_V1 = forkDna?.rel8ns!;
+            expect(forkDnaRel8ns.ancestor).withContext(`should descend from fork^gib primitive`).toBeTruthy();
+            expect(forkDnaRel8ns.ancestor!.length).withContext(`should descend from fork^gib primitive`).toEqual(1);
+            expect(forkDnaRel8ns.ancestor![0]).withContext(`should descend from fork^gib primitive`).toEqual('fork^gib');
+
+            const forkDnaData = (forkDna.data as TransformOpts_Fork<IbGib_V1>)!;
+
+            expect(forkDna.data).withContext(`should have well-formed common transform opts`).toBeTruthy();
+            expect(forkDnaData.dna).withContext(`should have well-formed common transform opts`).toBeTrue()
+            expect(forkDnaData.srcAddr).withContext(`should have well-formed common transform opts`).toBeUndefined();
+            expect(forkDnaData.src).withContext(`should have well-formed common transform opts`).toBeUndefined();
+
+            expect(forkDnaData.type).withContext(`should have well-formed data specific to fork transform`).toEqual("fork");
+            expect(forkDnaData.destIb).withContext(`should have well-formed data specific to fork transform`).toEqual(destIb);
+
+            // we're going to do another fork with the same options gotten from the dna
+            // (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
+            await delay(1100);
+
+            // NOTE: we're getting the new fork args from the **generated dna**, NOT from
+            // our initial fork args. This ensures that we're saving all of the required
+            // data in the dna record.
+            const forkOpts2: TransformOpts_Fork<IbGib_V1> = clone(forkDnaData);
+            forkOpts2.src = ROOT;
+            const { newIbGib: newIbGib2, dnas: dnas2 } = await fork(forkOpts2);
+            expect(newIbGib2).withContext(`should produce pure dna function, and non-unique dna (without timestamps, tjp, or uuid) (1s delay)`).toBeTruthy();
+            expect(dnas2).withContext(`should produce pure dna function, and non-unique dna (without timestamps, tjp, or uuid) (1s delay)`).toBeTruthy();
+            const forkDna2 = dnas2![0];
+
+            // dna itself should be exactly the same
+            expect(forkDna2).withContext(`should produce pure dna function, and non-unique dna (without timestamps, tjp, or uuid) (1s delay)`).toEqual(forkDna);
+
+            // 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 produce pure dna function, and non-unique dna (without timestamps, tjp, or uuid) (1s delay)`).not.toEqual(newIbGib.gib);
+
+            // when forking using the same options, the ib should be the same
+            expect(newIbGib2.ib).withContext(`should produce pure dna function, and non-unique dna (without timestamps, tjp, or uuid) (1s delay)`).toEqual(newIbGib.ib);
+        });
+    }); // dna
+
+});
+
+
+describe(`when forking a regular ibgib`, () => {
+
+    let src: IbGib_V1;
+    let srcAddr: IbGibAddr;
+
+    beforeEach(async () => {
+        // This will be the src we're working off of.
+        const beforeResult = await fork({ src: ROOT, uuid: true });
+        src = beforeResult.newIbGib;
+
+        expect(src).toBeTruthy();
+    });
+
+    it(`should create a new ibgib`, async () => {
+        const { newIbGib } = await fork({ src });
+        expect(newIbGib).toBeTruthy();
+    });
+
+    it(`should have src ib^gib address in ancestor rel8n`, async () => {
+        const { newIbGib } = await fork({ src });
+        expect(newIbGib?.rel8ns).toBeTruthy();
+        expect(newIbGib?.rel8ns).toBeTruthy();
+        expect(newIbGib?.rel8ns!.ancestor).toBeTruthy();
+        expect(newIbGib?.rel8ns!.ancestor).toBeTruthy();
+        expect(newIbGib?.rel8ns!.ancestor!.length).toEqual(1);
+        srcAddr = getIbGibAddr({ ibGib: src });
+        expect(newIbGib?.rel8ns!.ancestor![0]).toEqual(srcAddr);
+    });
+
+    // TODO: TEST FORK cloneRel8ns option ONCE REL8 IS IMPLEMENTED
+    // it(`cloneRel8ns`, async () => {
+    //     const testData = {x: 1, y: 2, deeper: { zzz: 333 }};
+    //     const { newIbGib: grandparent } = await fork({ src, cloneData: true});
+    //     const { newIbGib: parent } = await mut8({ src: grandparent, dataToAddOrPatch: testData });
+    //     const { newIbGib } = await fork({ src: parent, cloneData: true});
+
+    //     expect(newIbGib).toBeTruthy();
+    //     expect(newIbGib!.rel8ns).toBeTruthy();
+    //     expect(newIbGib!.rel8ns).toBeTruthy();
+    //     expect(newIbGib!.rel8ns!.ancestor).toBeTruthy();
+    //     expect(newIbGib!.rel8ns!.ancestor).toBeTruthy();
+    //     const parentAddr = getIbGibAddr({ibGib: parent});
+    //     expect(newIbGib!.rel8ns!.ancestor![newIbGib!.rel8ns!.ancestor!.length-1]).toEqual(parentAddr);
+    //     expect(newIbGib!.data).toBeTruthy();
+    //     expect(newIbGib!.data).toEqual(testData);
+    // });
+
+    it(`cloneData`, async () => {
+        // adding uuid/timestamp for testing hack
+        // need to reconsider inability to rename/remove timestamp data
+        // seems silly since bad actors can always do this and security is
+        // really through other means.
+        const testData = { x: 1, y: 2, deeper: { zzz: 333 }, uuid: 'tbd', timestamp: 'tbd' };
+        const { newIbGib: grandparent } = await fork({ src, cloneData: true, noTimestamp: true });
+        testData.uuid = grandparent.data!.uuid!;
+        testData.timestamp = grandparent.data!.timestamp!;
+        const { newIbGib: parent } =
+            await mut8({
+                src: grandparent,
+                dataToAddOrPatch: testData,
+                noTimestamp: true
+            });
+        const { newIbGib } = await fork({ src: parent, cloneData: true, noTimestamp: true });
+
+        expect(newIbGib).toBeTruthy();
+        expect(newIbGib!.rel8ns).toBeTruthy();
+        expect(newIbGib!.rel8ns).toBeTruthy();
+        expect(newIbGib!.rel8ns!.ancestor).toBeTruthy();
+        expect(newIbGib!.rel8ns!.ancestor).toBeTruthy();
+        const parentAddr = getIbGibAddr({ ibGib: parent });
+        expect(newIbGib!.rel8ns!.ancestor![newIbGib!.rel8ns!.ancestor!.length - 1]).toEqual(parentAddr);
+        expect(newIbGib!.data).toBeTruthy();
+        expect(newIbGib!.data).toEqual(testData);
+    });
+
+    // it(`should clone data`, async () => {
+    // });
+});
+
+describe(`when forking multiple regular ibgibs, NON LINKED REL8NS`, () => {
+
+    const ibs: Ib[] = ["a", "b", "c", "d"];
+    let srcForks: { [ib: string]: TransformResult<IbGib_V1> } = {};
+    let srcIbGibs: { [ib: string]: IbGib_V1 } = {};
+
+    beforeEach(async () => {
+        // These will be the srcs we're working off of.
+        // a forked from root, b forked from a, etc.
+        let prevIbGib: IbGib_V1 | undefined;
+        for (let ib of ibs) {
+            const forkResult = await fork({ src: prevIbGib || ROOT, destIb: ib });
+            srcForks[ib] = forkResult;
+            srcIbGibs[ib] = forkResult.newIbGib;
+            prevIbGib = forkResult.newIbGib;
+        }
+    });
+    afterEach(() => {
+        srcForks = {};
+        srcIbGibs = {};
+    })
+
+    it(`should create a new ibgib`, async () => {
+        ibs.forEach(ib => {
+            const ibGib = srcIbGibs[ib];
+            expect(ibGib).toBeTruthy();
+            expect(ibGib).toBeTruthy();
+            expect(ibGib.ib).toEqual(ib);
+        })
+    });
+
+    it(`should have src ib^gib (address) in ancestor rel8n`, async () => {
+        const getPrev: (ib: Ib) => IbGib_V1 | null = (ib) => {
+            switch (ib) {
+                case "a": return null;
+                case "b": return srcIbGibs.a;
+                case "c": return srcIbGibs.b;
+                case "d": return srcIbGibs.c;
+                default: throw new Error("unknown ib")
+            }
+        };
+        // the first one forks from the root, so the rel8ns should be undefined which is tested elsewhere
+        ibs.filter(ib => ib !== "a").forEach(ib => {
+            const newIbGib = srcIbGibs[ib]!;
+            const prevIbGib = getPrev(ib)!;
+            expect(newIbGib?.rel8ns).toBeTruthy();
+            expect(newIbGib?.rel8ns).toBeTruthy();
+            expect(newIbGib?.rel8ns!.ancestor).toBeTruthy();
+            expect(newIbGib?.rel8ns!.ancestor).toBeTruthy();
+            expect(newIbGib?.rel8ns!.ancestor!.length).toBeGreaterThan(0);
+            const prevIbGibAddr = getIbGibAddr({ ibGib: prevIbGib });
+            expect(newIbGib?.rel8ns!.ancestor![newIbGib!.rel8ns!.ancestor!.length - 1]).toEqual(prevIbGibAddr);
+        })
+    });
+
+    // TODO: need to implement mut8 before the clone data can be tested
+    // it(`should clone data`, async () => {
+    //     throw new Error('not implemented yet');
+    //     const testData = { yo: "there" }
+    //     const { newIbGib } = await fork({ src });
+    //     expect(newIbGib?.rel8ns).toBeTruthy();
+    //     expect(newIbGib?.rel8ns).toBeTruthy();
+    //     expect(newIbGib?.rel8ns!.ancestor).toBeTruthy();
+    //     expect(newIbGib?.rel8ns!.ancestor).toBeTruthy();
+    //     expect(newIbGib?.rel8ns!.ancestor!.length).toEqual(1);
+    //     srcAddr = getIbGibAddr({ibGib: src});
+    //     expect(newIbGib?.rel8ns!.ancestor![0]).toEqual(srcAddr);
+    // });
+});
+
+describe(`when forking with YES LINKED 'ancestor' rel8n...`, () => {
+
+    const ibs: Ib[] = ["a", "b", "c", "d"];
+    let srcForks: { [ib: string]: TransformResult<IbGib_V1> } = {};
+    let srcIbGibs: { [ib: string]: IbGib_V1 } = {};
+
+    beforeEach(async () => {
+        // These will be the srcs we're working off of.
+        // a forked from root, b forked from a, etc.
+        let prevIbGib: IbGib_V1 | undefined;
+        for (let i = 0; i < ibs.length; i++) {
+            const ib = ibs[i];
+            const forkResult = await fork({
+                src: prevIbGib || ROOT,
+                destIb: ib,
+                linkedRel8ns: [Rel8n.ancestor],
+            });
+            srcForks[ib] = forkResult;
+            srcIbGibs[ib] = forkResult.newIbGib;
+            prevIbGib = forkResult.newIbGib;
+
+        }
+    });
+    afterEach(() => {
+        srcForks = {};
+        srcIbGibs = {};
+    })
+
+    it(`should create a new ibgib`, async () => {
+        ibs.forEach(ib => {
+            const ibGib = srcIbGibs[ib];
+            expect(ibGib).toBeTruthy();
+            expect(ibGib).toBeTruthy();
+            expect(ibGib.ib).toEqual(ib);
+        })
+    });
+
+    it(`should have src ib^gib (address) in ancestor rel8n`, async () => {
+        const getPrevIbGib: (ib: Ib) => IbGib_V1 | null = (ib) => {
+            switch (ib) {
+                case "a": return null;
+                case "b": return srcIbGibs.a;
+                case "c": return srcIbGibs.b;
+                case "d": return srcIbGibs.c;
+                default: throw new Error("unknown ib")
+            }
+        };
+        // the first one forks from the root, so the rel8ns should be undefined which is tested elsewhere
+        ibs.filter(ib => ib === "a").forEach(ib => {
+            const newIbGib = srcIbGibs[ib]!;
+            expect(newIbGib?.rel8ns).toBeUndefined();
+            // expect(newIbGib?.rel8ns!.ancestor).toBeTruthy();
+            // expect(newIbGib?.rel8ns!.ancestor).toBeTruthy();
+            // expect(newIbGib?.rel8ns!.ancestor!.length).toEqual(1);
+            // const prevIbGibAddr = getIbGibAddr({ibGib: prevIbGib});
+            // expect(newIbGib?.rel8ns!.ancestor![0]).toEqual(prevIbGibAddr);
+        });
+        ibs.filter(ib => ib !== "a").forEach(ib => {
+            const newIbGib = srcIbGibs[ib]!;
+            const prevIbGib = getPrevIbGib(ib)!;
+            expect(newIbGib?.rel8ns).toBeTruthy();
+            expect(newIbGib?.rel8ns).toBeTruthy();
+            expect(newIbGib?.rel8ns!.ancestor).toBeTruthy();
+            expect(newIbGib?.rel8ns!.ancestor).toBeTruthy();
+            expect(newIbGib?.rel8ns!.ancestor!.length).toEqual(1);
+            const prevIbGibAddr = getIbGibAddr({ ibGib: prevIbGib });
+            expect(newIbGib?.rel8ns!.ancestor![0]).toEqual(prevIbGibAddr);
+        });
+    });
+
+});

package/src/V1/transforms/index.mts

@@ -0,0 +1,4 @@
+export * from './fork.mjs';
+export * from './mut8.mjs';
+export * from './rel8.mjs';
+export { isPrimitive, isDna } from './transform-helper.mjs';

package/src/V1/transforms/mut8.mts

@@ -0,0 +1,239 @@
+import { getIbGibAddr, clone, getTimestamp } from '../../helper.mjs';
+import { IbGib_V1, IbGibData_V1, IbGibRel8ns_V1, Rel8n } from '../types.mjs';
+import { TransformOpts_Mut8, TransformResult } from '../../types.mjs';
+import { IBGIB_DELIMITER, } from '../constants.mjs';
+import { buildDna, isPrimitive, getGib } from './transform-helper.mjs';
+
+/**
+ * Original-ish V1 transform behavior.
+ * Going to create a new ibGib which mut8s internal data (or the ib) from the src ibgib.
+ *
+ * Takes the immutable src ibGib record, applies a mutation to its internal (intrinsic)
+ * `data` field, creates a new ibGib with the new intrinsic data.
+ *
+ * ### remember, ibgib basic structure
+ *
+ * Remember, the ibGib has the following basic structure (here represented in JSON):
+ * {
+ *   ib: 'some ib, can be a simple name, or other metadata, up to very complex metadata.',
+ *   gib: 'ABC123', // hash of the other three fields of our JSON data structure
+ *   rel8ns: {
+ *      'link name': [ 'other ibgib^ABC345', 'yo^456789' ],
+ *      'called an edge in other jargon': [ 'ib^gib' ],
+ *      'past': ['ib^gib']
+ *      ...
+ *   },
+ *   data: {
+ *     'intrinsic data': 'intrinsic value',
+ *     'copied each datum': 'so should be relatively small in practice',
+ *     'can...': {
+ *       '...also be objects if you really': ['want']
+ *      }
+ *   }
+ * }
+ *
+ * So this transform is primarily concerned with that `data` property (though we can mut8 the ib also).
+ * If it's really anything complex, most likely it would be better to do
+ * another ibGib and link to it via the `rel8ns` (in the same way that in OOP it
+ * is good to have single responsibility for class architecture).
+ *
+ * ### what we can do with mutations
+ *
+ * We can mutate the `ib` value. So if we need to change metadata (e.g. a 'rename'), we can.
+ * This has implications for updating pointer refs and the tjp, but that's more advanced.
+ *
+ * We can also mutate the intrinsic `data` property, which is basically a JS object style of
+ * key/value store.
+ *
+ * ### notes
+ *   * This is NOT going to do the plan^gib stuff ATM.
+ *   * This does NOT add any identity information ATM.
+ *
+ */
+export async function mut8<TNewData = any>(
+    opts: TransformOpts_Mut8<IbGib_V1, TNewData>
+): Promise<TransformResult<IbGib_V1>> {
+    const {
+        noTimestamp, dna, linkedRel8ns,
+        dataToRename, dataToRemove, dataToAddOrPatch,
+        mut8Ib,
+        type = 'mut8'
+    } = opts;
+    let src = opts.src;
+    const lc = '[mut8_v1]';
+    // #region validation
+
+    if (type !== 'mut8') { throw new Error(`${lc} not a mut8 transform.`); }
+    if (!opts.type) { opts.type = 'mut8' }
+
+    if (!src) { throw new Error(`${lc} src required to mut8.`); }
+    if (!src!.ib) { throw new Error(`${lc} src.ib required.`); }
+    if (src!.ib!.includes(IBGIB_DELIMITER)) {
+        throw new Error(`${lc} ib can't contain hardcoded delimiter (${IBGIB_DELIMITER}) right now.`);
+    }
+    if (!src!.gib) { throw new Error(`${lc} src.gib required.`); }
+
+    if (!mut8Ib && !dataToRename && !dataToRemove && !dataToAddOrPatch) {
+        throw new Error(`${lc} gotta provide either a mut8Ib or some data to change.`);
+    }
+
+    const srcAddr = getIbGibAddr({ ib: src!.ib, gib: src.gib });
+    if (opts.srcAddr && srcAddr !== opts.srcAddr) { throw new Error(`${lc} srcAddr from src does not equal opts.srcAddr`); }
+    opts.srcAddr = srcAddr;
+
+    // const srcIsPrimitive = src.gib === GIB || !src.gib;
+    // if (srcIsPrimitive) { throw new Error(`${lc} cannot mutate primitive ibgib`); }
+    if (isPrimitive({ ibGib: src })) { throw new Error(`${lc} cannot mutate primitive ibgib`); }
+
+    // #endregion
+
+    // we want to forget `src` proper very quickly because it may have other
+    // non-IbGib properties that are not relevant to our transform.
+    let dto: IbGib_V1 = { ib: src.ib, gib: src.gib, };
+    if (src.data && Object.keys(src.data).length > 0) { dto.data = src.data; }
+    if (src.rel8ns && Object.keys(src.rel8ns).length > 0) { dto.rel8ns = src.rel8ns; }
+    src = dto;
+
+    const newIbGib = clone(src) as IbGib_V1<IbGibData_V1>;
+
+    const srcRel8ns = src.rel8ns ? src.rel8ns : {};
+    const rel8ns: IbGibRel8ns_V1 = clone(srcRel8ns);
+    rel8ns.past = linkedRel8ns?.includes(Rel8n.past) ?
+        [srcAddr] :
+        (rel8ns.past || []).concat([srcAddr]);
+
+    let data: any = src?.data ? clone(src!.data) : {};
+    if (dataToRename) { data = renameOrRemove(data, dataToRename, 'rename'); }
+    if (dataToRemove) { data = renameOrRemove(data, dataToRemove, 'remove'); }
+    if (dataToAddOrPatch) { data = patch(data, dataToAddOrPatch); }
+    if (!noTimestamp) { data.timestamp = getTimestamp(); }
+
+    // n-related
+    if (opts.nCounter || Object.keys(data).includes('n')) {
+        if (Object.keys(data).includes('n')) {
+            if (Number.isInteger(data.n)) {
+                if (data.n >= 0) {
+                    data.n = data.n + 1;
+                } else {
+                    console.warn(`${lc} data.n is less than 0, which is unexpected. Resetting data.n to 0.`);
+                    data.n = 0;
+                }
+            } else {
+                throw new Error('cannot increment nCounter because data.n is not a number.');
+            }
+        } else {
+            data.n = 0;
+        }
+    }
+
+    // tjp-related
+    // let tjpAddr: IbGibAddr | undefined = undefined;
+
+    // const srcIsTjp = data.isTjp && (rel8ns.tjp ?? []).length === 0; // if we only want one tjp
+    const srcIsTjp = data.isTjp; // if we want to allow more than one tjp
+    if (srcIsTjp) {
+        // if the src is tjp, e.g. is the first ibgib after a fork,
+        // then srcAddr is the tjpAddr
+        const tjpRel8n: string[] = rel8ns.tjp ?? [];
+        tjpRel8n.push(srcAddr);
+        rel8ns.tjp = tjpRel8n;
+        delete data.isTjp;
+    }
+
+    // dna-related
+    let transformDna: IbGib_V1 | null = null;
+    if (dna) {
+        transformDna = await buildDna(opts);
+        const dnaAddr = getIbGibAddr({ ibGib: transformDna });
+        rel8ns.dna = linkedRel8ns?.includes(Rel8n.dna) ?
+            rel8ns.dna = [dnaAddr] :
+            rel8ns.dna = (rel8ns.dna || []).concat(dnaAddr);
+    }
+
+    // set final ib, data, rel8ns, gib values
+    newIbGib.ib = mut8Ib ? mut8Ib : newIbGib.ib;
+    newIbGib.rel8ns = rel8ns;
+    if (Object.keys(data).length > 0) {
+        newIbGib.data = data;
+    } else {
+        // we've removed the last key in the data object so delete it
+        delete newIbGib.data;
+    }
+    const hasTjp = (rel8ns.tjp?.length ?? 0) > 0;
+    newIbGib.gib = await getGib({ ibGib: newIbGib, hasTjp });
+
+    // wrap in the result and return
+    const result: TransformResult<IbGib_V1> = { newIbGib };
+    if (transformDna) { result.dnas = [transformDna]; }
+    return result;
+}
+
+
+function renameOrRemove(obj: any, info: any, which: 'rename' | 'remove'): any {
+    const lc = `[renameOrRemove]`;
+    const FORBIDDEN_RENAME_REMOVE_KEYS = ['timestamp'];
+    Object.keys(info).forEach(key => {
+        if (FORBIDDEN_RENAME_REMOVE_KEYS.includes(key)) {
+            throw new Error(`${lc} Cannot rename to ${key}.`);
+        }
+        if (Object.keys(obj).includes(key)) {
+            let infoVal = info[key];
+            if (typeof (infoVal) === 'string') {
+                // rename
+                if (FORBIDDEN_RENAME_REMOVE_KEYS.includes(infoVal)) {
+                    throw new Error(`${lc} Cannot rename to ${infoVal}.`);
+                }
+                if (which === 'rename') {
+                    obj[infoVal] = obj[key];
+                }
+                delete obj[key];
+            }
+            else {
+                // recurse
+                obj[key] = renameOrRemove(obj[key], infoVal, which);
+            }
+        }
+        else {
+            console.log(`${lc} key to ${which} does not exist`);
+        }
+    });
+    return obj;
+};
+
+/**
+ * Patches obj (active mutate, does not copy) with patchObj data. Special keys
+ * can rename/remove keys, otherwise is an additive patch.
+ *
+ * @param obj source obj to patch, possibly is a subobject in a recursive call
+ * @param patchInfo data to patch into obj, possibly containing nested objects
+ */
+function patch(obj: any, patchInfo: any): any {
+    Object.keys(patchInfo).forEach(patchKey => {
+        // grab the patchVal before updating patchKey
+        let patchVal = patchInfo[patchKey];
+        let objVal = obj[patchKey];
+        if (objVal) {
+            if (Array.isArray(patchVal) || Array.isArray(objVal)) {
+                // both are arrays, so full replace
+                obj[patchKey] = patchVal;
+            }
+            else if (typeof (patchVal) === 'object' && typeof (objVal) === 'object') {
+                // {a: {b: 2}}, {a: {b: 3, c: 4}}
+                // patchKey = 'a';
+                // patchVal = {b: 3, c: 4}
+                // objVal = {b: 2}
+                // recurse
+                obj[patchKey] = patch(objVal, patchVal);
+            }
+            else {
+                // not both objects, so full replace
+                obj[patchKey] = patchVal;
+            }
+        }
+        else {
+            // does not exist yet, so set new
+            obj[patchKey] = patchVal;
+        }
+    });
+    return obj;
+};