@ibgib/core-gib 0.0.90 → 0.0.92

package/src/common/alias/alias-helper.mts

@@ -0,0 +1,259 @@
+import { extractErrorMsg, getSaferSubstring } from "@ibgib/helper-gib/dist/helpers/utils-helper.mjs";
+import { IbGibAddr } from "@ibgib/ts-gib/dist/types.mjs";
+import { IbGib_V1, Rel8n } from "@ibgib/ts-gib/dist/V1/types.mjs";
+import { getIbAndGib, getIbGibAddr } from "@ibgib/ts-gib/dist/helper.mjs";
+import { rel8 } from "@ibgib/ts-gib/dist/V1/transforms/rel8.mjs";
+import { Factory_V1 } from "@ibgib/ts-gib/dist/V1/factory.mjs";
+
+import { GLOBAL_LOG_A_LOT } from "../../core-constants.mjs";
+import { AliasIbGib_V1, AliasInfo } from "./alias-types.mjs";
+import { ALIAS_ATOM, ALIAS_MAX_LENGTH, ALIAS_REL8N_NAME, ALIAS_TARGET_REL8N_NAME, DEFAULT_ALIAS_DESCRIPTION } from "./alias-constants.mjs";
+import { MetaspaceService } from "../../witness/space/metaspace/metaspace-types.mjs";
+import { IbGibSpaceAny } from "../../witness/space/space-base-v1.mjs";
+import { SpecialIbGibType } from "../other/other-types.mjs";
+import { rel8ToSpecialIbGib } from "../../witness/space/space-helper.mjs";
+
+const logalot = GLOBAL_LOG_A_LOT;
+
+/**
+ * relates an ibgib provided by {@link ibGib} or {@link addr} to the latest
+ * version of the given {@link aliasIbGib}.
+ *
+ * If the alias already exists, this will replace the target ibgib with the ibgib passed in.
+ * if the alias does not exist, this will create the new alias first.
+ *
+ * persists this result in the same {@link space} and registers the newly
+ * created alias ibgib via the {@link metaspace}.
+ *
+ * @returns the new/latest alias ibgib
+ *
+ * @throws an error if the aliases special ibgib index does not exist in the
+ * given {@link space}
+ *
+ * @see {@link ALIAS_TARGET_REL8N_NAME}
+ */
+export async function setAlias({
+    ibGib,
+    addr,
+    aliasIbGib,
+    aliasName,
+    metaspace,
+    space,
+    lock,
+}: {
+    /**
+     * the ibgib that we're relating to the alias. can also provide just the
+     * {@link addr}.
+     */
+    ibGib?: IbGib_V1,
+    /**
+     * the ibgib addr that we're relating to the alias.
+     */
+    addr?: IbGibAddr,
+    /**
+     * the alias that we're relating to
+     */
+    aliasIbGib?: AliasIbGib_V1,
+    aliasName?: string,
+    /**
+     * it's meta
+     */
+    metaspace: MetaspaceService,
+    /**
+     * space in which the alias exists on the aliases special ibgib index
+     */
+    space: IbGibSpaceAny,
+    /**
+     * lock on operations
+     */
+    lock?: boolean,
+}): Promise<AliasIbGib_V1> {
+    const lc = `[${setAlias.name}]`;
+    try {
+        if (logalot) { console.log(`${lc} starting... (I: f6a2969d2948482cac073467a010fe1b)`); }
+
+        if (addr && ibGib && addr !== getIbGibAddr({ ibGib })) { throw new Error(`both addr (${addr}) and ibGib (${getIbGibAddr({ ibGib })}) are provided but addr does not match addr of ibGib. (E: a0bfe5acf9c643cbbd20cc3936580ce9)`); }
+
+        if (!addr && !ibGib) { throw new Error(`either addr or ibGib required (E: 8f02309770504046960c64fae00c0fcc)`); }
+        addr ??= getIbGibAddr({ ibGib });
+
+        let aliasAddr: IbGibAddr | undefined = aliasIbGib ?
+            getIbGibAddr({ ibGib: aliasIbGib }) :
+            undefined;
+
+        if (!aliasIbGib) {
+            // get the alias ibgib if exists. if doesn't exist, will create
+            // later in code
+            if (!aliasName) { throw new Error(`(UNEXPECTED) !aliasIbGib && !aliasName? either aliasIbGib or aliasName required (E: 7dda32d1803ac02b4c80f415fd726f24)`); }
+
+            let info = await getAliasInfo({ aliasName, metaspace, space, lock });
+            if (info) {
+                aliasIbGib = info.ibGib;
+                aliasAddr = getIbGibAddr({ ibGib: aliasIbGib });
+            }
+        }
+
+        let newAliasIbGib: AliasIbGib_V1;
+
+        let latestAliasAddr: IbGibAddr | undefined = aliasAddr ?
+            await metaspace.getLatestAddr({ addr: aliasAddr, space }) :
+            undefined;
+
+        if (latestAliasAddr) {
+            // alias exists, so update
+
+            if (!aliasIbGib || latestAliasAddr !== getIbGibAddr({ ibGib: aliasIbGib })) {
+                let resGetLatestAlias = await metaspace.get({ addr: latestAliasAddr, space });
+                if (!resGetLatestAlias.success || resGetLatestAlias.ibGibs?.length !== 1) {
+                    throw new Error(`could not get latest alias (${latestAliasAddr}) from space (${space.ib}). error: ${resGetLatestAlias.errorMsg ?? '[unknown error (E: faae3a4b5f6b4e28b99d089f1a8be13a)]'} (E: c5fc6dc7326242e48618b240266e63b7)`);
+                }
+                aliasIbGib = resGetLatestAlias.ibGibs!.at(0)! as AliasIbGib_V1;
+                aliasAddr = getIbGibAddr({ ibGib: aliasIbGib });
+            }
+
+            // at this point, the aliasIbGib and its addr are guaranteed to be
+            // truthy and latest
+
+            const rel8nsToAddByAddr = { [ALIAS_TARGET_REL8N_NAME]: [addr] };
+            const resRel8ToAlias =
+                await rel8({
+                    src: aliasIbGib,
+                    rel8nsToAddByAddr,
+                    // linked because an alias only points to a single target
+                    linkedRel8ns: [ALIAS_TARGET_REL8N_NAME],
+                    dna: true, nCounter: true,
+                });
+            newAliasIbGib = resRel8ToAlias.newIbGib as AliasIbGib_V1;
+
+            await metaspace.persistTransformResult({ resTransform: resRel8ToAlias, space });
+
+            // update the special ibgib index to point to the new alias
+            const _newAliasesIndexIbGib = await metaspace.rel8ToSpecialIbGib({
+                type: SpecialIbGibType.aliases,
+                rel8nName: ALIAS_REL8N_NAME,
+                space,
+                ibGibsToRel8: [newAliasIbGib],
+                ibGibsToUnRel8: [aliasIbGib],
+            });
+        } else {
+            // alias does not yet exist, so create new
+
+            if (!aliasName) { throw new Error(`(UNEXPECTED) !latestAliasAddr and !aliasName? alias should either exist in space (${space.ib}) and have a latest addr or aliasName should be provided. (E: ab1cc9d24f356b888f877131d5dff824)`); }
+
+            const saferizedAliasName = getSaferSubstring({ text: aliasName });
+
+            const resNewAlias = await Factory_V1.firstGen({
+                parentIbGib: Factory_V1.primitive({ ib: ALIAS_ATOM }),
+                ib: `${ALIAS_ATOM} ${saferizedAliasName}`,
+                data: {
+                    name: saferizedAliasName,
+                    rawName: aliasName, // just in case probably yagni yada yada
+                    description: DEFAULT_ALIAS_DESCRIPTION,
+                },
+                // linked because an alias only points to a single target
+                linkedRel8ns: [ALIAS_TARGET_REL8N_NAME],
+                tjp: { uuid: true, timestamp: true },
+                dna: true,
+                nCounter: true,
+            });
+            newAliasIbGib = resNewAlias.newIbGib as AliasIbGib_V1;
+            await metaspace.persistTransformResult({ resTransform: resNewAlias, space });
+
+            const _newAliasesIndexIbGib = await metaspace.rel8ToSpecialIbGib({
+                type: SpecialIbGibType.aliases,
+                rel8nName: ALIAS_REL8N_NAME,
+                space,
+                ibGibsToRel8: [newAliasIbGib],
+            });
+        }
+
+        await metaspace.registerNewIbGib({ ibGib: newAliasIbGib, space });
+        return newAliasIbGib;
+    } catch (error) {
+        console.error(`${lc} ${extractErrorMsg(error)}`);
+        throw error;
+    } finally {
+        if (logalot) { console.log(`${lc} complete.`); }
+    }
+}
+
+/**
+ * gets the alias ibgib and sundry based on given `aliasName`.
+ *
+ * @returns info about the alias registered or undefined if no matching alias
+ * exists
+ */
+export async function getAliasInfo({
+    aliasName,
+    metaspace,
+    lock,
+    space,
+}: {
+    aliasName: string,
+    /**
+     * space in which the alias exists on the aliases special ibgib index
+     */
+    space: IbGibSpaceAny,
+    metaspace: MetaspaceService,
+    /**
+     * lock on operations
+     */
+    lock?: boolean,
+}): Promise<AliasInfo | undefined> {
+    const lc = `[${getAliasInfo.name}]`;
+    try {
+        if (logalot) { console.log(`${lc} starting... (I: 40bc11ee4d0e182047ffa28d046a0324)`); }
+
+        if (aliasName.length > ALIAS_MAX_LENGTH) { throw new Error(`invalid aliasName. cannot be greater than ALIAS_MAX_LENGTH (${ALIAS_MAX_LENGTH}). (E: b1a03c3893519b8bdbaef52ee1d4ab24)`); }
+
+        // get the alias via aliasName from the special ibgib index
+        let aliasesIbGib = await metaspace.getSpecialIbGib({
+            type: SpecialIbGibType.aliases,
+            initialize: false,
+            lock,
+            space,
+        });
+        if (!aliasesIbGib) { throw new Error(`no aliases special ibgib (index) exists in given space (${space.ib}). This index must be initialized first. (E: 7f4cb726cafb93534e2d893945867b24)`); }
+
+        // find the alias
+        const saferizedAliasName = getSaferSubstring({ text: aliasName! });
+        let rel8dTargets = (aliasesIbGib.rel8ns ?? {})[ALIAS_TARGET_REL8N_NAME] ?? [];
+
+        // alias ibs atow (04/2024) are just `alias_atom saferizedAliasName`
+        let aliasAddr = rel8dTargets.find(aliasAddr => {
+            let { ib: targetAliasIb } = getIbAndGib({ ibGibAddr: aliasAddr });
+            let saferizedAliasName_target = targetAliasIb.substring(`${ALIAS_ATOM} `.length);
+            return saferizedAliasName_target === saferizedAliasName;
+        });
+
+        if (aliasAddr) {
+            let latestAliasAddr = await metaspace.getLatestAddr({ addr: aliasAddr, space });
+            if (!latestAliasAddr) { throw new Error(`(UNEXPECTED) alias addr exists on special ibgib in space but getLatestAddr returns falsy? (E: 854b7209fe851ee4ea4034d5db229924)`); }
+
+            let resGetLatestAlias = await metaspace.get({ addr: latestAliasAddr, space });
+            if (!resGetLatestAlias.success || resGetLatestAlias.ibGibs?.length !== 1) {
+                throw new Error(`could not get latest alias (${latestAliasAddr}) from space (${space.ib}). error: ${resGetLatestAlias.errorMsg ?? '[unknown error (E: 3f4a79a1603c40e285816a81d693a488)]'} (E: b2e8fe50fbbc44a5ac973c23d3a40fef)`);
+            }
+            let aliasIbGib = resGetLatestAlias.ibGibs!.at(0)! as AliasIbGib_V1;
+            if (!aliasIbGib.rel8ns) { throw new Error(`(UNEXPECTED) !aliasIbGib.rel8ns? (E: 1d78faaf1c73c27d5cee2edbd1a14a24)`); }
+            if (!aliasIbGib.rel8ns[ALIAS_TARGET_REL8N_NAME]) { throw new Error(`(UNEXPECTED) !aliasIbGib.rel8ns[ALIAS_TARGET_REL8N_NAME]? (E: b7b2d8ac1c3d6e910b56891e56c9ab24)`); }
+            if (aliasIbGib.rel8ns[ALIAS_TARGET_REL8N_NAME].length !== 1) { throw new Error(`(UNEXPECTED) aliasIbGib.rel8ns[ALIAS_TARGET_REL8N_NAME].length !== 1? (E: 8da0d9566ca9c6b8519f46157404eb24)`); }
+            return {
+                ibGib: aliasIbGib,
+                targetAddr: aliasIbGib.rel8ns[ALIAS_TARGET_REL8N_NAME].at(0)!,
+                rawName: aliasName,
+                saferizedName: saferizedAliasName,
+            };
+        } else {
+            return undefined;
+        }
+    } catch (error) {
+        console.error(`${lc} ${extractErrorMsg(error)}`);
+        throw error;
+    } finally {
+        if (logalot) { console.log(`${lc} complete.`); }
+    }
+}
+
+// todo: removeAlias function
+// todo: updateAlias function

package/src/common/alias/alias-types.mts

@@ -0,0 +1,36 @@
+import { IbGibAddr } from '@ibgib/ts-gib/dist/types.mjs';
+import { IbGibData_V1, IbGibRel8ns_V1, IbGib_V1 } from '@ibgib/ts-gib/dist/V1/index.mjs';
+
+import { ALIAS_TARGET_REL8N_NAME } from './alias-constants.mjs';
+
+
+export interface AliasData_V1 extends IbGibData_V1 {
+}
+
+export interface AliasRel8ns_V1 extends IbGibRel8ns_V1 {
+    [ALIAS_TARGET_REL8N_NAME]?: IbGibAddr[];
+}
+
+export interface AliasIbGib_V1 extends IbGib_V1<AliasData_V1, AliasRel8ns_V1> {
+
+}
+
+export interface AliasInfo {
+    /**
+     * reference to the actual ibgib
+     */
+    ibGib: AliasIbGib_V1;
+    /**
+     * addr that the alias ibgib points to
+     */
+    targetAddr: IbGibAddr;
+    /**
+     * this is what we actually go by
+     */
+    saferizedName: string;
+    /**
+     * vague thoughts on storing the raw name in case there are issues or in
+     * case we want to load full records....yada hrmm
+     */
+    rawName: string;
+}

package/src/common/other/other-constants.mts

@@ -14,7 +14,7 @@ export const DEFAULT_UUID = undefined;
 import { ROBBOT_REL8N_NAME } from '../../witness/robbot/robbot-constants.mjs';
 import { SYNC_SPACE_REL8N_NAME } from '../../witness/space/space-constants.mjs';
 import { DEFAULT_ROOT_REL8N_NAME, ROOT_REL8N_NAME } from '../root/root-constants.mjs';
-import { TAGGED_REL8N_NAME, TAG_REL8N_NAME } from '../tag/tag-constants.mjs';
+import { TAG_TARGET_REL8N_NAME, TAG_REL8N_NAME } from '../tag/tag-constants.mjs';
 
 export const AUTOSYNC_ALWAYS_REL8N_NAME = 'always';
 export const ARCHIVE_REL8N_NAME = 'archive';
@@ -29,7 +29,7 @@ export const DEFAULT_LIST_REL8N_NAMES: string[] = [
     'pic', 'comment', 'link',
     'result', 'import',
     'tagged',
-    TAGGED_REL8N_NAME,
+    TAG_TARGET_REL8N_NAME,
     TAG_REL8N_NAME,
     ROOT_REL8N_NAME, // hack for now to get all to show
     DEFAULT_ROOT_REL8N_NAME,

package/src/common/other/other-types.mts

@@ -144,8 +144,7 @@ export interface DeleteIbGibResult extends FileResult { }
  *     should be extensible per use case in consuming apps.
  */
 export type SpecialIbGibType =
-    "tags" | "roots" |
-    // "latest" |
+    "tags" | "aliases" | "roots" |
     "outerspaces" | "secrets" |
     "encryptions" | "autosyncs" | "robbots" | "apps" | "history" |
     string;
@@ -159,13 +158,10 @@ export type SpecialIbGibType =
 export const SpecialIbGibType = {
     /** indexes all tag ibgibs within a space */
     tags: "tags" as SpecialIbGibType,
+    /** indexes all aliases within a space */
+    aliases: "aliases" as SpecialIbGibType,
     /** indexes all root ibgibs within a space */
     roots: "roots" as SpecialIbGibType,
-    // /**
-    //  * Ephemeral index ibgib that maps a tjp address -> latest local address in
-    //  * a space.
-    //  */
-    // latest: "latest" as SpecialIbGibType,
     /** indexes all outerspace ibgibs, including sync spaces, within a space */
     outerspaces: "outerspaces" as SpecialIbGibType,
     /** indexes all secret ibgibs within a space */

package/src/common/tag/tag-constants.mts

@@ -10,7 +10,7 @@ export const TAG_REL8N_NAME = 'tag';
 /**
  * A tag ibGib uses this rel8n name for the ibgibs that it targets.
  */
-export const TAGGED_REL8N_NAME = 'target';
+export const TAG_TARGET_REL8N_NAME = 'target';
 
 
 export const ILLEGAL_TAG_TEXT_CHARS = [

package/src/common/tag/tag-helper.mts

@@ -6,7 +6,7 @@ import { rel8 } from "@ibgib/ts-gib/dist/V1/transforms/rel8.mjs";
 
 import { GLOBAL_LOG_A_LOT } from "../../core-constants.mjs";
 import { TagIbGib_V1 } from "./tag-types.mjs";
-import { TAGGED_REL8N_NAME } from "./tag-constants.mjs";
+import { TAG_TARGET_REL8N_NAME } from "./tag-constants.mjs";
 import { MetaspaceService } from "../../witness/space/metaspace/metaspace-types.mjs";
 import { IbGibSpaceAny } from "../../witness/space/space-base-v1.mjs";
 
@@ -20,7 +20,7 @@ const logalot = GLOBAL_LOG_A_LOT;
  * created tag ibgib via the {@link metaspace}.
  *
  * @returns new tag ibgib that has the ibgib related to it
- * @see {@link TAGGED_REL8N_NAME}
+ * @see {@link TAG_TARGET_REL8N_NAME}
  */
 export async function rel8ToTag({
     ibGib,
@@ -39,7 +39,8 @@ export async function rel8ToTag({
      */
     addr?: IbGibAddr,
     /**
-     * the tag that we're relating to
+     * the tag that we're relating to. Note that this gets the latest of this
+     * tag in the given {@link space}.
      */
     tagIbGib: TagIbGib_V1,
     /**
@@ -55,12 +56,12 @@ export async function rel8ToTag({
     try {
         if (logalot) { console.log(`${lc} starting... (I: b1fd25ec28bce8f1916b4ab55f48a724)`); }
 
-        if (addr && ibGib && addr !== getIbGibAddr({ ibGib })) { throw new Error(`both addr (${addr}) and ibGib (${getIbGibAddr({ ibGib })}) are provided but addr does not match addr of ibGib. (E: f2c14234a78c917fb9f587beaee89324)`); }
 
         if (!addr && !ibGib) { throw new Error(`either addr or ibGib required (E: 3d580f8ecc251a0c81c7ea8bc3d38524)`); }
         addr ??= getIbGibAddr({ ibGib });
+        if (addr !== getIbGibAddr({ ibGib })) { throw new Error(`addr (${addr}) differs from incoming ibGib's addr (${getIbGibAddr({ ibGib })}). (E: f2c14234a78c917fb9f587beaee89324)`); }
 
-        const latestTagAddr = await metaspace.getLatestAddr({ addr, ibGib, space });
+        const latestTagAddr = await metaspace.getLatestAddr({ ibGib: tagIbGib, space });
         if (latestTagAddr !== getIbGibAddr({ ibGib: tagIbGib })) {
             let resGetLatestTag = await metaspace.get({ addr: latestTagAddr, space });
             if (!resGetLatestTag.success || resGetLatestTag.ibGibs?.length !== 1) {
@@ -69,7 +70,7 @@ export async function rel8ToTag({
             tagIbGib = resGetLatestTag.ibGibs!.at(0)! as TagIbGib_V1;
         }
 
-        const rel8nsToAddByAddr = { [TAGGED_REL8N_NAME]: [addr] };
+        const rel8nsToAddByAddr = { [TAG_TARGET_REL8N_NAME]: [addr] };
         const resRel8ToTag =
             await rel8({ src: tagIbGib, rel8nsToAddByAddr, dna: true, nCounter: true });
         const newTagIbGib = resRel8ToTag.newIbGib as TagIbGib_V1;

package/src/witness/space/metaspace/metaspace-base.mts

@@ -548,6 +548,9 @@ export abstract class MetaspaceBase implements MetaspaceService {
             await this.getSpecialIbGib({ type: "tags", initialize: true });
             if (logalot) { console.timeLog(timerName); }
 
+            await this.getSpecialIbGib({ type: SpecialIbGibType.aliases, initialize: true });
+            if (logalot) { console.timeLog(timerName); }
+
             await this.getSpecialIbGib({ type: "robbots", initialize: true });
             if (logalot) { console.timeLog(timerName); }
 
@@ -1478,7 +1481,7 @@ export abstract class MetaspaceBase implements MetaspaceService {
      * * This was written early and makes many assumptions.
      * * Meant to work with Ionic space atow.
      *
-     * @returns latest addr in a given space (or localUserSpace)
+     * @returns latest addr in a given space (or localUserSpace) or undefined if does not exist
      */
     async getLatestAddr({
         ibGib,

package/src/witness/space/metaspace/metaspace-types.mts

@@ -447,7 +447,7 @@ export interface MetaspaceService {
      * * This was written early and makes many assumptions.
      * * Meant to work with Ionic space atow.
      *
-     * @returns latest addr in a given space (or localUserSpace)
+     * @returns latest addr in a given space (or localUserSpace) or undefined if does not exist
      */
     getLatestAddr(arg: {
         ibGib?: IbGib_V1<any>,

package/src/witness/space/space-helper.mts

@@ -1621,7 +1621,6 @@ export async function createTagIbGibAndSundry({
             parentIbGib: tagPrimitive,
             ib: tagIb,
             data: { text, icon, description },
-            linkedRel8ns: [Rel8n.past, Rel8n.ancestor],
             tjp: { uuid: true, timestamp: true },
             dna: true,
             nCounter: true,