@ibgib/ts-gib 0.4.9

package/src/helper.spec.mts

@@ -0,0 +1,127 @@
+/**
+ * Test helper functions.
+ */
+
+import * as h from './helper.mjs';
+import { HashAlgorithm } from './helper.mjs';
+
+const SOME_STRING = "This is some stringy stuff...";
+const SOME_STRING_HASH = "5DC14EA1027B956AD6BA51F11372DF823FCF3429B5F2063F1DDA358E0F4F2992";
+const SOME_STRING_HASH_512 = "C48C780DA7C43EE7047CDAB0D7A2FDF5DC050DF3291D3CAE973FB0F51BE8535668592EB25A730C95A23D3B4D57924893E7E87C86DC0F52C6D5D2E34EE41203E5";
+const SOME_OTHER_STRING = "This is quite a different string of stuff.";
+const TEST_HASHES: { [key: string]: string } = {
+    [SOME_STRING + h.HashAlgorithm.sha_256]: SOME_STRING_HASH,
+    [SOME_STRING + h.HashAlgorithm.sha_512]: SOME_STRING_HASH_512,
+    [SOME_OTHER_STRING + h.HashAlgorithm.sha_256]: 'AE4C18B37B2329770E05EA3F946C6EB6DE56D2DC568E1F5CBB395E2A1556F58A',
+    [SOME_OTHER_STRING + h.HashAlgorithm.sha_512]: '2F1A72B21C914ED459319DF4B5D70E81CEE67C4B48BC74CD6BA8F41DCEC20DCD100C914913F370B2782985268D05C590B46F3FE9005A7477BA952935D2454E53',
+}
+
+describe(`when cloning`, () => {
+
+    it(`should copy deep objects`, async () => {
+        const objSimple = { a: SOME_STRING };
+        const objADeep = {
+            levelOne: {
+                levelTwo: {
+                    buckle: "your shoe",
+                    three: "four",
+                    objSimple: objSimple,
+                }
+            }
+        };
+        const cloneADeep = h.clone(objADeep);
+        expect(cloneADeep?.levelOne?.levelTwo?.buckle).toBe("your shoe");
+        expect(cloneADeep?.levelOne?.levelTwo?.three).toBe("four");
+        expect(cloneADeep?.levelOne?.levelTwo?.objSimple).toEqual(objSimple);
+
+        cloneADeep.levelOne.levelTwo.objSimple.a = SOME_OTHER_STRING;
+
+        // original should **still** be the first value
+        expect(objSimple.a).toBe(SOME_STRING);
+        // clone should be changed.
+        expect(cloneADeep.levelOne.levelTwo.objSimple.a).toBe(SOME_OTHER_STRING);
+    });
+});
+
+describe(`when getting timestamp`, () => {
+    it(`should get the current date as UTCString`, async () => {
+        // implementation detail hmm....
+        const timestamp = h.getTimestamp();
+        const date = new Date(timestamp);
+        const dateAsUTCString = date.toUTCString();
+        expect(timestamp).toBe(dateAsUTCString);
+    });
+});
+
+describe(`when hashing (helper)`, () => {
+    const TEST_ALGORITHMS: h.HashAlgorithm[] = Object.values(h.HashAlgorithm);
+
+    // implicit is just SHA-256
+    it(`should hash consistently with implicit SHA-256`, async () => {
+        const hash = await h.hash({ s: SOME_STRING }) || "";
+        expect(hash.toUpperCase()).toBe(TEST_HASHES[SOME_STRING + 'SHA-256']);
+    });
+
+    for (let algorithm of TEST_ALGORITHMS) {
+        it(`should hash consistently with explicit ${algorithm}`, async () => {
+            // const hash = await h.hash({s: SOME_STRING, algorithm: "SHA-256"}) || "";
+            let hash = await h.hash({ s: SOME_STRING, algorithm }) || "";
+            expect(hash.toUpperCase()).toBe(TEST_HASHES[SOME_STRING + algorithm]);
+            hash = await h.hash({ s: SOME_OTHER_STRING, algorithm }) || "";
+            expect(hash.toUpperCase()).toBe(TEST_HASHES[SOME_OTHER_STRING + algorithm]);
+        });
+        it(`should hash without collisions, 1000 times, ${algorithm}`, async () => {
+            const hashes: string[] = [];
+            const salt = await h.getUUID(1024);
+            // console.log(`salt: ${salt}`);
+            for (let i = 0; i < 1000; i++) {
+                const hash = await h.hash({ s: salt + i.toString(), algorithm }) || "";
+                // console.log(hash);
+                expect(hashes).not.toContain(hash);
+                hashes.push(hash);
+            }
+        });
+    };
+});
+
+describe(`when generating UUIDs`, () => {
+    it(`shouldn't duplicate UUIDs`, async () => {
+        const ids: string[] = [];
+        for (let i = 0; i < 100; i++) {
+            const id = await h.getUUID();
+            expect(ids).not.toContain(id);
+            ids.push(id);
+        }
+    });
+});
+
+describe(`when extractErrorMsg`, () => {
+    it(`should return canned msg when error is falsy`, () => {
+        const defaultMsg = '[error is falsy]'; // duplicate of code in helper.mjs
+        [null, undefined, ''].forEach(error => {
+            expect(h.extractErrorMsg(error)).withContext(JSON.stringify(error)).toEqual(defaultMsg);
+        });
+    });
+    it(`should return incoming error if it is a string`, () => {
+        ['string here', 'undefined', '42', 'ibgib'].forEach(stringError => {
+            expect(h.extractErrorMsg(stringError)).withContext(JSON.stringify(stringError)).toEqual(stringError);
+        });
+    });
+    it(`should return error.message if it's a thrown error`, () => {
+        ['string here', 'undefined', 'something went wrong', 'danger. out of memory (E: ce86ffd7a0174c1d8ce5e56c807dd4b1)']
+            .map(x => new Error(x))
+            .forEach(error => {
+                expect(h.extractErrorMsg(error)).withContext(error.message).toEqual(error.message);
+            });
+    });
+    it(`should return incoming error stringified if it is a number`, () => {
+        [1234, 0, 1_000, Number.MAX_SAFE_INTEGER, Number.MIN_SAFE_INTEGER, -5, 1 / 23].forEach(numberError => {
+            expect(h.extractErrorMsg(numberError)).withContext(JSON.stringify(numberError)).toEqual(JSON.stringify(numberError));
+        });
+    });
+    it(`should return canned response with type if incoming error is none of the above`, () => {
+        let error = { x: 1, y: 2 };
+        let msg = h.extractErrorMsg(error);
+        expect(msg).withContext(JSON.stringify(error)).toBeTruthy();
+    });
+});

package/src/index.cts

@@ -0,0 +1,3 @@
+export * as V1 from './V1/index.mjs';
+export * from './types.mjs';
+export * from './helper.mjs';

package/src/index.mts

@@ -0,0 +1,3 @@
+export * as V1 from './V1/index.mjs';
+export * from './types.mjs';
+export * from './helper.mjs';

package/src/types.mts

@@ -0,0 +1,242 @@
+/**
+ * The core of the simplicity of the ibGib protocol is that
+ * fundamentally you are taking two ibGibs and producing a third.
+ *
+ * There are three primary functions: mut8, rel8, fork
+ *
+ * These are actually different aspects of the single function of
+ * relationship and time, either extending or creating a timeline.
+ *
+ * Mut8 is intrinsic, rel8 is extrinsic, fork is a new timeline.
+ * Mut8 changes a timeline, rel8 changes a timeline's link(s),
+ * fork creates a new timeline.
+ */
+export declare type Ib = '' | string;
+export declare type Gib = '' | 'gib' | string;
+/**
+ * Convenient for when destructuring an IbGibAddr
+ */
+export interface IbAndGib {
+    ib: Ib,
+    gib: Gib,
+}
+/**
+ * Mostly a marker type of address.
+ *
+ * Not sure how to enforce schema on demand in TypeScript, but
+ * that's to decide for future.
+ */
+export declare type IbGibAddr = string;
+export declare type IbGibRel8ns = {
+    /**
+     * The key is the rel8nName.
+     *
+     * TS doesnt allow for the indexer to have a non-number/string value
+     * even if it's an alias for one of these types to be more readable.
+     * Otherwise I would type the `key` here as a `Rel8nName` alias of
+     * `string.`
+     */
+    [key: string]: IbGibAddr[] | null | undefined;
+};
+/**
+ * At the base ibGib, the bare minimum is that an ib (data) is required,
+ * with an optional gib (metadata).
+ */
+export interface IbGib {
+    ib: Ib;
+    gib?: Gib;
+}
+/**
+ * When adding additional structure to an ibGib, the first representation
+ * mechanism (from V1) was having explicit Data and Rel8ns keys.
+ *
+ * This is, however, not the only way to represent this. As just one example,
+ * you could also have a prefix for keys that are meant to be the relationships
+ * to other ibGibs.
+ *
+ * I'm including this shape at the core here and not just in V1 because it could
+ * be reused for other versions that are different tweaks with different default
+ * relationships and data structures but still adhere to this data/rel8ns split
+ * (and naming convention).
+ */
+export interface IbGibWithDataAndRel8ns<TData = any, TRel8ns extends IbGibRel8ns = IbGibRel8ns> extends IbGib {
+    /**
+     * Intrinsic data to this ibGib, most likely with primitives e.g. strings or numbers,
+     * that will be statically copied from mutation to mutation.
+     */
+    data?: TData | undefined;
+    /**
+     * Extrinsic data WRT this ibGib, which can track their own timelines of changes.
+     *
+     * Note that even if the relationships here point to the same address, i.e. do
+     * not change, the other ibGibs can be seen as changing or not. It all depends
+     * on how you want to interpret the relationship.
+     *
+     * For example, if you want to pause/freeze a relationship, then this would be
+     * handled by the viewer of the relationship. It just wouldn't check anywhere for
+     * the more up-to-date version.
+     */
+    rel8ns?: TRel8ns | undefined;
+}
+export declare type TransformType = 'fork' | 'mut8' | 'rel8';
+export interface TransformOpts<TSrc extends IbGib = IbGib> {
+    /**
+     * Fork, mut8, rel8
+     */
+    type?: TransformType;
+    /**
+     * If truthy, does NOT add a timestamp to the new ibGib.
+     */
+    noTimestamp?: boolean;
+    /**
+     * If truthy, creates dna ibGibs like V1.
+     * If falsy, skips the dna and only creates the resultant ibGib.
+     */
+    dna?: boolean;
+    /**
+     * Src to apply the transform to.
+     *
+     * Used at runtime, NOT persisted in space.
+     */
+    src?: TSrc;
+    /**
+     * Address of Src. Used in the space persistence.
+     */
+    srcAddr?: IbGibAddr;
+    /**
+     * There are two ways of creating rel8ns to other ibgibs:
+     *
+     * 1) Concat previous ones with new one
+     *   * e.g. past: ['a^gib'] --> past: ['a^gib', 'b^gib'] --> past: ['a^gib', 'b^gib', 'c^gib']
+     * 2) Only have most recent one, linked list style:
+     *   * e.g. past: ['a^gib'] --> past: ['b^gib'] --> past: ['c^gib']
+     *
+     * If you choose #1, then you have the advantage of not needing to load up all of the previous
+     * records to evaluate. So this will give you minimal runtime requirements, but take up more space.
+     * If you choose #2, like in a blockchain e.g., then you will have a smaller space footprint but
+     * it takes longer to build the entire list.
+     *
+     * This gives flexibility for having rel8ns that only wish to have a single value at most.
+     *
+     */
+    linkedRel8ns?: string[];
+    /**
+     * If truthy, this will include a data['n'] value that acts as an incremented
+     * counter for a naive versioning tracker.
+     *
+     * So A0^123.data.n = 0, A1^456.data.n = 1, etc.
+     */
+    nCounter?: boolean;
+}
+export interface TemporalJunctionPointOptions {
+    timestamp?: boolean;
+    uuid?: boolean;
+}
+export interface TransformOpts_Fork<TSrc extends IbGib = IbGib> extends TransformOpts<TSrc> {
+    type?: 'fork';
+    /**
+     * Destination ib for the transform.
+     */
+    destIb?: string;
+    /**
+     * If truthy, creates a UUID to encourage local uniqueness of the fork.
+     */
+    uuid?: boolean;
+    /**
+     * If truthy, the forked ibGib will be a temporal junction point using
+     * the specified
+     * This will provide a UUID to encourage local uniqueness of the fork.
+     *
+     * For what a temporal junction point is, refer to
+     * Back to the Future II (or ask me).
+     */
+    tjp?: TemporalJunctionPointOptions;
+    /**
+     * If true, retains parent/source's extrinsic rel8ns.
+     */
+    cloneRel8ns?: boolean;
+    /**
+     * If true, retains parent/source's intrinsic data.
+     */
+    cloneData?: boolean;
+}
+export interface TransformOpts_Mut8<TSrc extends IbGib = IbGib, TNewData = any> extends TransformOpts<TSrc> {
+    type?: 'mut8';
+    /**
+     * Info to rename keys. Should be an object where each value should either be
+     * a string or an object. If it's a string, then the corresponding key will
+     * be renamed to that value. If it's an object, then it will recurse at that
+     * key.
+     *
+     * @example
+     * data = { a: 'aaa', b: { rename: 'me', ignore: 'me' }}
+     * dataToRemove = { a: 'aRenamed', b: { rename: 'renamed' } }
+     * data = { aRenamed: 'aaa', b: { renamed: 'me', ignore: 'me' }}
+     */
+    dataToRename?: {
+        [key: string]: any;
+    };
+    /**
+     * Info to remove keys. Should be an object where each value should either be
+     * a string or an object. If it's a string, then the corresponding key will
+     * be removed (the value is ignored). If it's an object, then it will recurse at that
+     * key.
+     *
+     * @example
+     * data = { a: 'aaa', b: { remove: 'me', ignore: 'me' }}
+     * dataToRemove = { b: { remove: '' } }
+     * data = { a: 'aaa', b: { ignore: 'me' }}
+     */
+    dataToRemove?: {
+        [key: string]: any;
+    };
+    /**
+     * Data object that contains only additive information for ibGib's intrinsic data.
+     */
+    dataToAddOrPatch?: TNewData;
+    /**
+     * If given, will mut8 the ib (without forking the entire ibGib).
+     *
+     * Often this will act as a 'rename', e.g. (if the ib is acting as the 'name')
+     */
+    mut8Ib?: string;
+}
+export interface TransformOpts_Rel8<TSrc extends IbGib = IbGib> extends TransformOpts<TSrc> {
+    type?: 'rel8';
+    /**
+     * Relationships to add to an ibGib, either by creating new relationships or by
+     * concatenating the arrays to existing ones.
+     *
+     * NOTES:
+     *   - Moving relationships can be performed by combining add/remove rel8ns.
+     *   - How the relations are actually represented in the ibGib record is
+     *     left to the compiler. The same goes for how this information is
+     *     recorded in the dna, if generating dna.
+     */
+    rel8nsToAddByAddr?: IbGibRel8ns;
+    /**
+     * Relationships to remove from an ibGib.
+     *
+     * NOTES:
+     *   - Moving relationships can be performed by combining add/remove rel8ns.
+     *   - Attempting to remove a non-existing relationship may or may not cause
+     *     an error, depending on the compiler.
+     */
+    rel8nsToRemoveByAddr?: IbGibRel8ns;
+}
+
+export interface TransformResult<TOut extends IbGib> {
+    /**
+     * The final result of the transformation
+     */
+    newIbGib: TOut,
+    /**
+     * DNA side effects created in the transformation.
+     */
+    dnas?: TOut[],
+    /**
+     * If you're performing a transform with multiple steps,
+     * then there will be intermediate ibGibs created.
+     */
+    intermediateIbGibs?: TOut[],
+}

package/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "declaration": true, /* Generates corresponding '.d.ts' file. */
+    "declarationMap": true, /* Generates a sourcemap for each corresponding '.d.ts' file. */
+    "sourceMap": true, /* Generates corresponding '.map' file. */
+    "rootDir": "./src", /* Specify the root directory of input files. Use to control the output directory structure with --outDir. */
+    "composite": true, /* Enable project compilation */
+    "outDir": "./dist", /* Redirect output structure to the directory. */
+    "module": "ESNext", /* https://www.typescriptlang.org/docs/handbook/esm-node.html */
+  },
+  "exclude": [
+    "**/*.spec.mts"
+  ]
+}

package/tsconfig.test.json

@@ -0,0 +1,10 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "outDir": "./dist", /* Redirect output structure to the directory. */
+    "module": "ESNext", /* https://www.typescriptlang.org/docs/handbook/esm-node.html */
+  },
+  "exclude": [
+    // override inherited exclude of spec files
+  ]
+}