@ibgib/ts-gib 0.4.9

package/src/V1/transforms/transform-helper.mts

@@ -0,0 +1,263 @@
+import { TransformOpts, IbGib, Gib, Ib, IbGibAddr, } from "../../types.mjs";
+import { clone, getIbGibAddr, getIbAndGib, HashAlgorithm, extractErrorMsg, } from "../../helper.mjs";
+import { sha256v1, } from "../sha256v1.mjs";
+import { GibInfo, IbGib_V1, } from "../types.mjs";
+import { IBGIB_DELIMITER, GIB, GIB_DELIMITER } from "../constants.mjs";
+
+export async function buildDna<TSrc extends IbGib_V1, TOpts extends TransformOpts<TSrc>>(
+    opts: TOpts,
+): Promise<IbGib_V1> {
+    const transformData: TOpts = clone(opts);
+    let lc = `[${buildDna.name}]`;
+
+    // remove references to the srcAddr, as this will be captured
+    // by the ibGib's `past` rel8n. This way, we can reapply dna
+    // to different src's more easily, as well as have less unique dna
+    if (transformData.srcAddr) { delete transformData.srcAddr; }
+
+    // remove all references to actual objects in this, we just
+    // want the data. ATOW, src is a reference to the src object
+    // and we only want the srcAddr
+    delete transformData.src;
+
+    // dna is never timestamped or uniquely identified hmm...
+    // or rel8d to anything...hmmm
+    // so much dna, best to minimize though of course we dont
+    // want to prematurely optimize...but there's a looooot of dna.
+    // best to share/reuse as much as possible.
+    const result: IbGib_V1 = {
+        ib: transformData.type!,
+        data: transformData,
+        rel8ns: {
+            ancestor: [
+                `${transformData.type!.toString()}${IBGIB_DELIMITER}${GIB}` // e.g. fork^gib
+            ]
+        }
+    };
+
+    result.gib = await sha256v1(result);
+
+    return result;
+}
+
+export function isDna({ ibGib }: { ibGib: IbGib }): boolean {
+    const lc = `[${isDna.name}]`;
+    try {
+        if (!ibGib) { throw new Error(`ibGib required.`); }
+
+        // console.log(`${lc} ibGib: ${pretty(ibGib)}`);
+
+        // ancestor is known transform is the best way for v1 ATOW
+        const knownTransformPrimitiveAddrs =
+            ['fork', 'mut8', 'rel8', 'plan'].map(x => `${x}^${GIB}`); // plan from prev versions
+        const hasTransformAncestor =
+            ((ibGib as any).rel8ns) &&
+            ((ibGib as any).rel8ns.ancestor) &&
+            (Array.isArray((ibGib as any).rel8ns.ancestor)) &&
+            ((((ibGib as any).rel8ns.ancestor) as any) as any).
+                some((x: any) => knownTransformPrimitiveAddrs.includes(x));
+
+        return hasTransformAncestor || false;
+    } catch (error) {
+        console.error(`${lc} ${extractErrorMsg(error)}`);
+        throw error;
+    }
+}
+
+export function isPrimitive({ ibGib, gib }: { ibGib?: IbGib_V1, gib?: Gib }): boolean {
+    if (ibGib) {
+        return isPrimitive({ gib: ibGib.gib });
+    } else if (gib) {
+        return gib === GIB;
+    } else {
+        // falsy gib means it's primitive or a programming error...hmm
+        return true;
+    }
+}
+
+/**
+ * Generates the gib of a given `ibGib` depending on
+ * @returns gib - either bare hash for those with no tjp; or tjp-scoped hash; or 'gib' for primitives
+ */
+export async function getGib({
+    ibGib,
+    hasTjp,
+    tjpAddr,
+    gibDelimiter,
+    isPrimitive,
+    hashAlgorithm,
+}: {
+    /**
+     * We'll take the `ib`, `data`, and `rel8ns` from this
+     */
+    ibGib: IbGib_V1,
+    /**
+     * If true, then we'll treat this as having a tjp.
+     * If falsy, then we'll check the internals of the ibGib to see if it has a tjp.
+     */
+    hasTjp?: boolean;
+    /**
+     * @deprecated
+     *
+     * IGNORED
+     *
+     * This is now always searched for in the ibGib itself.
+     */
+    tjpAddr?: IbGibAddr,
+    /**
+     * What to use as the delimiter for the `gib`.
+     *
+     * @default GIB_DELIMITER
+     *
+     * ## notes
+     *
+     * This is not the same thing necessarily as the ib^gib delimiter.
+     * In fact the default gibDelimiter ATOW ('.') is different than the
+     * default ib^gib delimiter ('^').
+     */
+    gibDelimiter?: string,
+    /**
+     * If this is primitive, then the `gib` is always GIB ("gib" string literal).
+     */
+    isPrimitive?: boolean,
+    /**
+     * Hash algorithm to use when calculating the gib hash of the ibgib datum.
+     *
+     * ## notes
+     *
+     * * I'm just including this now to show where we will expand when working with
+     *   multiple hash algorithms. For now though, in all of V1, we use 'SHA-256'
+     *   when calculating the gib hashes. This is why I'm hard-coding the type
+     *   here instead of using this lib's `HashAlgorithm` type.
+     *   * This param is actually ignored ATOW.
+     * * In my current consuming use case (ionic-gib), though,
+     *   I am indeed using SHA-512 when encrypting using encrypt-gib. I only note
+     *   this in case someone sees "SHA-512" code somewhere and is confused.
+     */
+    hashAlgorithm?: 'SHA-256',
+}): Promise<string> {
+    const lc = `[${getGib.name}]`;
+    try {
+        if (!ibGib) { throw new Error(`ibGib required. (E: 17d073226b9d42fd841e5a94b065ef21)`); }
+        if (isPrimitive) { return GIB; }
+        const ibGibHash = await sha256v1(ibGib, '');
+        const rel8ns = ibGib.rel8ns ?? {};
+        const data = ibGib.data ?? {};
+        gibDelimiter = gibDelimiter || GIB_DELIMITER;
+        if (!hasTjp) { hasTjp = (rel8ns.tjp?.length ?? []) > 0 || data.isTjp || false; }
+        if (hasTjp) {
+            let tjpAddrGib: string | undefined;
+            if (rel8ns.tjp) {
+                if (rel8ns.tjp.length === 1) {
+                    if (rel8ns.tjp[0]) { // checking for empty string
+                        tjpAddr = rel8ns.tjp[0];
+                    } else {
+                        throw new Error(`rel8ns.tjp[0] is falsy. (E: ed879d2b039543f8b1902e8b7b5a5a7b)`);
+                    }
+                } else if (rel8ns.tjp.length > 1) {
+                    if (rel8ns.tjp[rel8ns.tjp.length - 1]) {
+                        console.warn(`${lc} found more than one tjp addr...only expecting 1 ATOW. (W: 10ed43f716e743e0afd1954f1ab46789)`);
+                        tjpAddr = rel8ns.tjp[rel8ns.tjp.length - 1];
+                    } else {
+                        throw new Error(`multiple tjp addrs, and the last (most recent) one is falsy. (E: bc835dc89be24075bba8b2b6616ea069)`);
+                    }
+                } else {
+                    // empty rel8ns.tjp array?
+                    throw new Error(`hasTjp is true but rel8ns.tjp is empty array. (E: d08b2f9e86494814b5e7d7b4602b2ab7)`);
+                }
+            } else if (data.isTjp) {
+                // the ibGib itself is the tjp
+                tjpAddr = getIbGibAddr({ ib: ibGib.ib, gib: ibGibHash });
+            } else {
+                throw new Error(`hasTjp is true, but both ibGib.rel8ns.tjp and ibGib.data.isTjp are falsy. (E: 4e246897e52044789594d853bb5b66ee)`)
+            }
+            tjpAddrGib = tjpAddr ? getIbAndGib({ ibGibAddr: tjpAddr }).gib : undefined;
+
+            if (tjpAddrGib) {
+                // if the ibGib IS the tjp, then the gib is only the hash
+
+                // if the ibGib is NOT the tjp, then the gib is the hash plus
+                // tjpGib. note in the future, if multiple tjps are going, then
+                // tjpAddrGib itself may have another delim inside it, so we
+                // will end up with a gib with multiple delimiters.
+                return data.isTjp ? ibGibHash : `${ibGibHash}${GIB_DELIMITER}${tjpAddrGib}`;
+            } else {
+                throw new Error(`hasTjp is true but could not find tjpAddrGib. (E: 1863df626b754744a1d431a683cb0ba0)`);
+            }
+        } else {
+            // no tjp, so gib is just the hash
+            return ibGibHash;
+        }
+    } catch (error) {
+        console.error(`${lc} ${extractErrorMsg(error)}`);
+        throw error;
+    }
+
+}
+
+/**
+ * Parses gib (either via `gib` param or `ibGibAddr.gib`) and returns information
+ * about it.
+ *
+ * @returns Information about the given `gib` (or `gib` extracted from `ibGibAddr`)
+ */
+export function getGibInfo({
+    ibGibAddr,
+    gib,
+    gibDelimiter,
+}: {
+    /**
+     * If given, will extract `gib` from this.
+     */
+    ibGibAddr?: IbGibAddr,
+    /**
+     * `gib` to analyze.
+     */
+    gib?: Gib,
+    /**
+     * Delimiter among pieces of gib, if applicable.
+     *
+     * @default GIB_DELIMITER (ATOW '.')
+     *
+     * ## notes
+     *
+     * Some `gib` values will include tjp information, while others
+     * are just the hash.
+     */
+    gibDelimiter?: string,
+}): GibInfo {
+    const lc = `[${getGibInfo.name}]`;
+    try {
+        if (!ibGibAddr && !gib) { throw new Error(`Either ibGibAddr or gib required. (E: 25e3dcbe63cd44909032df12af9df75e)`); }
+        gib = gib || getIbAndGib({ ibGibAddr }).gib;
+
+        if (gib === GIB) { return { isPrimitive: true } }
+
+        gibDelimiter = gibDelimiter ?? GIB_DELIMITER;
+
+        if (gib.includes(gibDelimiter)) {
+            const pieces = gib.split(gibDelimiter);
+            if (pieces.some(p => p === '')) { throw new Error(`unexpected gib that contains gibDelimiter (${gibDelimiter}) but has at least one piece with empty string. (E: 75a94280045541009ee68182d12d3449)`); }
+
+            const piecesCount = pieces.length;
+            if (piecesCount > 2) { console.warn(`${lc} gib only expected to have two pieces ATOW. re-examine please. (W: aa4283ac5a5747a386a69966ecdad39d)`); }
+
+            const punctiliarHashPiece = pieces.splice(0, 1);
+            return {
+                punctiliarHash: punctiliarHashPiece[0],
+                tjpGib: pieces.join(gibDelimiter), // after splice, piece/s is/are tjp
+                piecesCount,
+                delimiter: gibDelimiter,
+            }
+        } else {
+            return {
+                punctiliarHash: gib,
+                piecesCount: 1,
+                delimiter: gibDelimiter,
+            }
+        }
+    } catch (error) {
+        console.error(`${lc} ${extractErrorMsg(error)}`);
+        throw error;
+    }
+}

package/src/V1/transforms/transform-helper.spec.mts

@@ -0,0 +1,45 @@
+/**
+ * Test transform-helper.
+ */
+
+
+import { IbGib_V1, IbGibRel8ns_V1, Rel8n } from '../types.mjs';
+import { TransformOpts_Rel8, IbGibAddr, IbGibRel8ns } from '../../types.mjs';
+import { pretty, clone, delay, getIbGibAddr } from '../../helper.mjs';
+import { ROOT, ROOT_ADDR } from '../constants.mjs';
+import { fork } from './fork.mjs';
+// import { mut8 } from './mut8.mjs';
+import { rel8 } from './rel8.mjs';
+import { Factory_V1 as factory } from '../factory.mjs';
+import { isDna } from './transform-helper.mjs';
+
+const PRIMITIVE_IBGIBS = [
+    factory.root(),
+    ...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,
+        ]
+    }),
+];
+
+describe(`isDna`, () => {
+    for (const src of PRIMITIVE_IBGIBS) {
+
+        it(`should return true for dna ibgibs`, async () => {
+            const resFork = await fork({ src, dna: true });
+            resFork.dnas?.every(x => {
+                const resIsDna = isDna({ ibGib: x });
+                expect(resIsDna).toBeTrue()
+            });
+        });
+
+        it(`should return false for non-dna ibgibs`, async () => {
+            const resFork = await fork({ src, dna: true });
+            const resIsDna = isDna({ ibGib: resFork.newIbGib });
+            expect(resIsDna).toBeFalse();
+        });
+
+    }
+});

package/src/V1/types.mts

@@ -0,0 +1,84 @@
+/**
+ * The core of the simplicity of the ibGib protocol is that you are
+ * taking two (or more) ibGibs and producing other ibGibs.
+ *
+ * There are three primary functions: mut8, rel8, fork
+ *
+ * These are actually different aspects of the single function of
+ * relationship and time, either:
+ *   1) Creating a 'new' timeline, or...
+ *   2) Extending an existing one.
+ *
+ * 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.
+ */
+import {
+    IbGibRel8ns, IbGibAddr, IbGibWithDataAndRel8ns, Gib,
+} from '../types.mjs';
+
+/**
+ * Need to see if I can remove this...
+ */
+export declare type IbGibData_V1 = {
+    [key: string]: any;
+    isTjp?: boolean;
+    n?: number;
+    timestamp?: string;
+    uuid?: string;
+};
+
+/**
+ * Convenience enum to avoid spelling mistakes. (optional)
+ */
+export enum Rel8n {
+    past = 'past',
+    ancestor = 'ancestor',
+    dna = 'dna',
+    identity = 'identity',
+    tjp = 'tjp',
+}
+export interface IbGibRel8ns_V1 extends IbGibRel8ns {
+    [Rel8n.past]?: IbGibAddr[];
+    [Rel8n.identity]?: IbGibAddr[];
+    [Rel8n.ancestor]?: IbGibAddr[];
+    [Rel8n.dna]?: IbGibAddr[];
+    [Rel8n.tjp]?: IbGibAddr[];
+}
+export interface IbGib_V1<TData = IbGibData_V1, TRel8ns extends IbGibRel8ns_V1 = IbGibRel8ns_V1>
+    extends IbGibWithDataAndRel8ns<TData, TRel8ns> {
+}
+
+export interface GibInfo {
+    /**
+     * Hash for this ibgib frame in time.
+     */
+    punctiliarHash?: string;
+    /**
+     * The gib for this ibgib's most recent tjp.
+     *
+     * ## notes
+     *
+     * ATOW, only one tjp expected really, though I've been coding
+     * with the possibility of having multiple tjp's similar to
+     * checkpoints.
+     */
+    tjpGib?: Gib;
+    /**
+     * If
+     */
+    piecesCount?: number;
+    /**
+     * If a delimiter is used in this gib, this is the delimiter.
+     *
+     * ## notes
+     *
+     * ATOW, the caller already knows the delimiter. But I'm thinking that
+     * I may be persisting this at some point and it would be good to include.
+     */
+    delimiter?: string;
+    /**
+     * True the gib is just 'gib' (GIB constant), else falsy.
+     */
+    isPrimitive?: boolean;
+}

package/src/helper.mts

@@ -0,0 +1,192 @@
+import { Ib, Gib, IbGib, IbGibAddr, IbAndGib } from './types.mjs';
+let crypto: any = globalThis.crypto;
+let { subtle } = crypto;
+
+export type HashAlgorithm = 'SHA-256' | 'SHA-512';
+export const HashAlgorithm: { [key: string]: HashAlgorithm } = {
+    'sha_256': 'SHA-256' as HashAlgorithm,
+    'sha_512': 'SHA-512' as HashAlgorithm,
+}
+
+export function clone(obj: any) {
+    return JSON.parse(JSON.stringify(obj));
+}
+export function getTimestamp() {
+    return (new Date()).toUTCString();
+}
+/**
+ * Gets the ib^gib address from the given ib and gib or
+ * from the ibGib object.
+ *
+ * Need to refactor to getIbGibAddr
+ */
+export function getIbGibAddr({
+    ib, gib, ibGib, delimiter = '^'
+}: {
+    ib?: Ib,
+    gib?: Gib,
+    ibGib?: IbGib,
+    delimiter?: string
+}) {
+    ib = ib || ibGib?.ib || '';
+    gib = gib || ibGib?.gib || '';
+    return ib + delimiter + gib;
+}
+
+/**
+ * Get the ib and gib fields from an ibGib object or ibGibAddr
+ * with the given `delimiter`.
+ */
+export function getIbAndGib({
+    ibGib,
+    ibGibAddr,
+    delimiter = '^'
+}: {
+    ibGibAddr?: IbGibAddr,
+    ibGib?: IbGib,
+    delimiter?: string
+}): IbAndGib {
+    const lc = '[getIbAndGib]';
+    if (!ibGibAddr) {
+        if (ibGib) {
+            ibGibAddr = getIbGibAddr({ ibGib });
+        } else {
+            throw new Error(`${lc} We need either an address or an ibGib object`);
+        }
+    }
+    if (!ibGibAddr) { throw new Error(`${lc} Couldn't get ibGibAddr. ibGib invalid?`); }
+
+    if (!delimiter) { delimiter = '^'; }
+
+    const pieces = ibGibAddr.split(delimiter);
+    if (pieces.length === 2) {
+        // normal v1 case, e.g. 'ib^gib' or 'tag home^ABC123'
+        return { ib: pieces[0], gib: pieces[1] };
+    } else if (pieces.length === 1 && ibGibAddr.endsWith(delimiter)) {
+        // normal v1 primitive, e.g. '7^' or 'name^'
+        return { ib: pieces[0], gib: '' };
+    } else if (pieces.length === 1 && ibGibAddr.startsWith(delimiter)) {
+        // only gib/hash is provided like maybe a binary file
+        // e.g. ^ABC123 or ^XYZ456 or ^some_gib_that_isnt_a_hash
+        return { ib: '', gib: pieces[0] };
+    } else if (pieces.length === 2 && pieces[0] === '' && pieces[1] === '') {
+        // edge case of address is only the delimiter.
+        // So it's the primitive for that delimiter
+        return { ib: delimiter, gib: '' };
+        // } else if (pieces.length === 0 ) {
+        // ibGibAddr is falsy, so would have thrown earlier in this function
+        // I'm just noting this case for intent ATOW
+    } else {
+        console.warn(`${lc} multiple delimiters found in ibGibAddr. Considering last delimiter as the demarcation of gib hash`);
+        // e.g. 'ib^ABC123^gib'
+        // ib: 'ib^ABC123'
+        // gib: 'gib'
+        return {
+            ib: pieces.slice(0, pieces.length - 1).join(delimiter),
+            gib: pieces.slice(pieces.length - 1)[0],
+        }
+    }
+}
+
+/**
+ * Simple hash function.
+ *
+ * NOTE:
+ *   This is not used for ibGib.gib values (ATOW)
+ *   but rather as a helper function for generating random UUIDs.
+ *
+ * @param s string to hash
+ * @param algorithm to use, currently only 'SHA-256'
+ */
+export async function hash({
+    s,
+    algorithm = 'SHA-256',
+}: {
+    s: string,
+    algorithm?: HashAlgorithm,
+}): Promise<string> {
+    if (!s) { return ''; }
+
+    const validAlgorithms = Object.values(HashAlgorithm);
+    if (!validAlgorithms.includes(algorithm)) {
+        console.error(`Only ${validAlgorithms} implemented`); return '';
+    }
+    try {
+        const msgUint8 = new TextEncoder().encode(s);
+        const buffer = await subtle.digest(algorithm, msgUint8);
+        const asArray = Array.from(new Uint8Array(buffer));
+        return asArray.map(b => b.toString(16).padStart(2, '0')).join('');
+    } catch (e) {
+        console.error(extractErrorMsg(e.message));
+        return '';
+    }
+}
+
+/**
+ * Simple func to generate UUID (sha-256 hash basically).
+ *
+ * @param seedSize size of seed for UUID generation
+ */
+export async function getUUID(seedSize = 64): Promise<string> {
+    let uuid: string = '';
+    if (seedSize < 32) { throw new Error(`Seed size must be at least 32`); }
+    if (!globalThis.crypto) { throw new Error(`Cannot create UUID, as unknown crypto library version. If using node.js, v19+ is required. (E: c02cee3fd8a94f678d3f4ebe9dc49797)`); }
+
+    const values = crypto.getRandomValues(new Uint8Array(16));
+    uuid = await hash({ s: values.join('') });
+
+    if (!uuid) { throw new Error(`Did not create UUID...hmm...`); }
+
+    return uuid;
+}
+
+/**
+ * Syntactic sugar for JSON.stringify(obj, null, 2);
+ *
+ * @param obj to pretty stringify
+ */
+export function pretty(obj: any): string {
+    return JSON.stringify(obj, null, 2);
+}
+
+/**
+ * Just delays given number of ms.
+ *
+ * @param ms milliseconds to delay
+ */
+export async function delay(ms: number): Promise<void> {
+    return new Promise<void>(resolve => {
+        setTimeout(() => {
+            resolve();
+        }, ms);
+    });
+}
+
+/**
+ * extracts the error message from an error object/string/falsy arg.
+ *
+ * ## notes
+ *
+ * * some libs throw errors, some throw just strings.
+ * * who knows what else it could be.
+ *
+ * ## todo
+ *
+ * * extract inner errors/causes if we ever use this function extensively.
+ *
+ * @param error the error object in the catch area of the try..catch block.
+ * @returns error.message if it's a string, error itself if it's a string, or canned error messages if it's falsy or none of the above.
+ */
+export function extractErrorMsg(error: any): string {
+    if (!error && error !== 0) {
+        return '[error is falsy]';
+    } else if (typeof error === 'string') {
+        return error;
+    } else if (typeof error.message === 'string') {
+        return error.message;
+    } else if (typeof error === 'number') {
+        return JSON.stringify(error);
+    } else {
+        return `[error is not a string and error.message is not a string. typeof error: ${typeof error}]`;
+    }
+}