@ibgib/core-gib 0.0.8 → 0.0.11

package/src/witness/space/{space-spec-helper.mts → space-respec-helper.mts}

@@ -1,3 +1,9 @@
+import {
+    firstOfEach, firstOfAll, ifWe,
+    lastOfEach, lastOfAll,
+    ifWeMight, iReckon, respecfully
+} from '@ibgib/helper-gib/dist/respec-gib/respec-gib.mjs';
+// const maam = `[${import.meta.url}]`, sir = maam;
 import { IbGibAddr, getIbGibAddr } from "@ibgib/ts-gib";
 import { IbGib_V1, } from "@ibgib/ts-gib/dist/V1/types.mjs";
 import { Factory_V1 as factory } from '@ibgib/ts-gib/dist/V1/factory.mjs';
@@ -7,6 +13,10 @@ import { IbGibSpaceAny } from "./space-base-v1.mjs";
 import { getGib } from "@ibgib/ts-gib/dist/V1/index.mjs";
 
 export interface CommonSpaceSpecOptions {
+    /**
+     * sir, maam, whatever the title is
+     */
+    respecfulTitle: string,
     /** @optional additional description label for testing */
     desc?: string,
     /**
@@ -27,7 +37,7 @@ export interface CommonSpaceSpecOptions {
     /**
      * if true, will use `fit` to short-circuit testing.
      */
-    useFit?: boolean,
+    shortcircuitRespec?: boolean,
     fnBeforeEach?: () => Promise<void>,
     fnAfterEach?: () => Promise<void>,
 }
@@ -42,71 +52,76 @@ export interface CommonSpaceSpecOptions {
  * run tests on an ibgib space that are common to all/most spaces.
  *
  * So, we can run these against any space, inner, outer, local ionic/filesystem based, etc.
+ *
+ * NOTE: Be sure to await these tests.
  */
-export function testSpace_createAndInit({
+export async function testSpace_createAndInit({
+    respecfulTitle: sir,
     desc,
     fnGetInitialData,
     fnGetInitialRel8ns,
     fnGetSpace,
-    useFit,
+    shortcircuitRespec,
     fnBeforeEach, fnAfterEach,
 }: CommonSpaceSpecOptions): Promise<void> {
     const logContext = `[${testSpace_PutGetDelete.name}]${desc ?? ''}`;
 
-    return new Promise<void>((resolve) => {
+    debugger;
+    await respecfully(sir, logContext, async () => {
+
         let initialData: any | undefined;
         let initialRel8ns: any | undefined;
         let space: IbGibSpaceAny;
 
-        beforeEach(async () => {
+        firstOfEach(sir, async () => {
             if (fnBeforeEach) { await fnBeforeEach(); }
             initialData = await fnGetInitialData();
             initialRel8ns = await fnGetInitialRel8ns();
         });
 
         if (fnAfterEach) {
-            afterEach(async () => {
+            lastOfEach(sir, async () => {
                 await fnAfterEach();
             });
         }
 
-        const fnIt: any = useFit ? fit : it;
+        const fnIfWeBlock: any = shortcircuitRespec ? ifWeMight : ifWe;
 
-        fnIt(`when created and initialized, space should be initialized`, async () => {
+        debugger;
+        await fnIfWeBlock(sir, `when created and initialized, space should be initialized`, async () => {
             space = await fnGetSpace(initialData, initialRel8ns);
             await space.initialized;
 
-            expect(space).withContext('space').toBeTruthy();
-            expect(space.ib).withContext('ib').toBeTruthy();
-            expect(space.gib).withContext('gib').toBeTruthy();
+            iReckon(sir, space).asTo('space').isGonnaBeTruthy();
+            iReckon(sir, space.ib).asTo('ib').isGonnaBeTruthy();
+            iReckon(sir, space.gib).asTo('gib').isGonnaBeTruthy();
             if (initialData) {
-                expect(space.data).withContext('data, initialData truthy').toBeTruthy();
+                iReckon(sir, space.data).asTo('data, initialData truthy').isGonnaBeTruthy();
             } else {
-                expect(space.rel8ns).withContext('data, initialData falsy').toBeUndefined();
+                iReckon(sir, space.rel8ns).asTo('data, initialData falsy').isGonnaBeUndefined();
             }
             if (initialRel8ns) {
-                expect(space.rel8ns).withContext('rel8ns, initialRel8ns truthy').toBeTruthy();
+                iReckon(sir, space.rel8ns).asTo('rel8ns, initialRel8ns truthy').isGonnaBeTruthy();
             } else {
-                expect(space.rel8ns).withContext('rel8ns, initialRel8ns falsy').toBeUndefined();
+                iReckon(sir, space.rel8ns).asTo('rel8ns, initialRel8ns falsy').isGonnaBeUndefined();
             }
         });
 
-        fnIt(`space.ib should contain correct info per initialData`, async () => {
+        await fnIfWeBlock(sir, `space.ib should contain correct info per initialData`, async () => {
             space = await fnGetSpace(initialData, initialRel8ns);
             await space.initialized;
 
-            expect(space.ib).toContain(initialData.name);
-            expect(space.ib).toContain(initialData.uuid);
+            iReckon(sir, space.ib).includes(initialData.name);
+            iReckon(sir, space.ib).includes(initialData.uuid);
 
             let { spaceClassname, spaceId, spaceName, } = parseSpaceIb({ spaceIb: space.ib });
-            expect(space.data?.classname).withContext('space.data?.classname').toEqual(spaceClassname);
-            expect(space.data?.name).withContext('space.data?.name, initial').toEqual(initialData.name);
-            expect(space.data?.name).withContext('space.data?.name, spaceName').toEqual(spaceName);
-            expect(space.data?.uuid).withContext('space.data?.uuid, initial').toEqual(initialData.uuid);
-            expect(space.data?.uuid).withContext('space.data?.uuid, spaceId').toEqual(spaceId);
+            iReckon(sir, space.data?.classname).asTo('space.data?.classname').isGonnaBe(spaceClassname);
+            iReckon(sir, space.data?.name).asTo('space.data?.name, initial').isGonnaBe(initialData.name);
+            iReckon(sir, space.data?.name).asTo('space.data?.name, spaceName').isGonnaBe(spaceName);
+            iReckon(sir, space.data?.uuid).asTo('space.data?.uuid, initial').isGonnaBe(initialData.uuid);
+            iReckon(sir, space.data?.uuid).asTo('space.data?.uuid, spaceId').isGonnaBe(spaceId);
         });
 
-        resolve();
     });
 }
 
@@ -120,24 +135,27 @@ export function testSpace_createAndInit({
  * run tests on an ibgib space that are common to all/most spaces.
  *
  * So, we can run these against any space, inner, outer, local ionic/filesystem based, etc.
+ *
+ * NOTE: Be sure to await these tests.
  */
-export function testSpace_PutGetDelete({
+export async function testSpace_PutGetDelete({
+    respecfulTitle: sir,
     desc,
     fnGetInitialData,
     fnGetInitialRel8ns,
     fnGetSpace,
-    useFit,
+    shortcircuitRespec,
     fnBeforeEach, fnAfterEach,
 }: CommonSpaceSpecOptions): Promise<void> {
     const logContext = `[${testSpace_PutGetDelete.name}]${desc ?? ''}`;
 
-    return new Promise<void>((resolve) => {
+    await respecfully(sir, logContext, async () => {
         let initialData: any | undefined;
         let initialRel8ns: any | undefined;
         let space: IbGibSpaceAny;
 
 
-        beforeEach(async () => {
+        firstOfEach(sir, async () => {
             if (fnBeforeEach) { await fnBeforeEach(); }
             initialData = await fnGetInitialData();
             initialRel8ns = await fnGetInitialRel8ns();
@@ -146,14 +164,14 @@ export function testSpace_PutGetDelete({
         });
 
         if (fnAfterEach) {
-            afterEach(async () => {
+            lastOfEach(sir, async () => {
                 await fnAfterEach();
             });
         }
 
-        const fnIt: any = useFit ? fit : it;
+        const fnIfWeBlock: any = shortcircuitRespec ? ifWeMight : ifWe;
 
-        fnIt(`${logContext}, should put/get/delete`, async () => {
+        await fnIfWeBlock(sir, `${logContext}, should put/get/delete`, async () => {
             let newIbGib: IbGib_V1 = {
                 ib: 'test ib',
                 data: { x: 1 },
@@ -164,28 +182,26 @@ export function testSpace_PutGetDelete({
 
             // put
             let resPut = await putInSpace({ ibGib: newIbGib, space });
-            expect(resPut).withContext('resPut').toBeTruthy();
-            expect(resPut.success).toBeTrue();
+            iReckon(sir, resPut).asTo('resPut').isGonnaBeTruthy();
+            iReckon(sir, resPut.success).isGonnaBeTrue();
 
             // get
             let resGet = await getFromSpace({ addr: newIbGibAddr, space });
-            expect(resGet).withContext('resGet').toBeTruthy();
-            expect(resGet.success).withContext('resGet').toBeTrue();
-            expect(resGet.errorMsg).withContext('resGet').toBeFalsy();
-            expect(resGet.ibGibs).withContext('resGet').toBeTruthy();
-            expect(resGet.ibGibs!.length).withContext('resGet').toEqual(1);
-            expect(resGet.ibGibs![0]).withContext('resGet').toEqual(newIbGib);
+            iReckon(sir, resGet).asTo('resGet').isGonnaBeTruthy();
+            iReckon(sir, resGet.success).asTo('resGet').isGonnaBeTrue();
+            iReckon(sir, resGet.errorMsg).asTo('resGet').isGonnaBeFalsy();
+            iReckon(sir, resGet.ibGibs).asTo('resGet').isGonnaBeTruthy();
+            iReckon(sir, resGet.ibGibs!.length).asTo('resGet').isGonnaBe(1);
+            iReckon(sir, resGet.ibGibs![0]).asTo('resGet').isGonnaBe(newIbGib);
 
             // delete
             await deleteFromSpace({ addr: newIbGibAddr, space });
             resGet = await getFromSpace({ addr: newIbGibAddr, space });
-            expect(resGet).withContext('resGet after delete').toBeTruthy();
-            expect(resGet.success).withContext('resGet after delete').toBeFalse();
-            expect(resGet.errorMsg).withContext('resGet after delete').toBeTruthy();
-            expect(resGet.ibGibs).withContext('resGet after delete').toBeUndefined();
+            iReckon(sir, resGet).asTo('resGet after delete').isGonnaBeTruthy();
+            iReckon(sir, resGet.success).asTo('resGet after delete').isGonnaBeFalse();
+            iReckon(sir, resGet.errorMsg).asTo('resGet after delete').isGonnaBeTruthy();
+            iReckon(sir, resGet.ibGibs).asTo('resGet after delete').isGonnaBeUndefined();
         });
-
-        resolve();
     });
 }
 
@@ -197,31 +213,35 @@ export function testSpace_PutGetDelete({
  * run tests on an ibgib space that are common to all/most spaces.
  *
  * So, we can run these against any space, inner, outer, local ionic/filesystem based, etc.
+ *
+ * NOTE: Be sure to await these tests.
  */
-export function testSpace_persistTransformResult({
+export async function testSpace_persistTransformResult({
+    respecfulTitle: sir,
     desc,
     fnGetInitialData,
     fnGetInitialRel8ns,
     fnGetSpace,
-    useFit,
+    shortcircuitRespec,
 }: CommonSpaceSpecOptions): Promise<void> {
     const logContext = `[${testSpace_persistTransformResult.name}]${desc ?? ''}`;
 
-    return new Promise<void>((resolve) => {
+    await respecfully(sir, logContext, async () => {
+
         let initialData: any | undefined;
         let initialRel8ns: any | undefined;
         let space: IbGibSpaceAny;
 
-        beforeEach(async () => {
+        firstOfEach(sir, async () => {
             initialData = await fnGetInitialData();
             initialRel8ns = await fnGetInitialRel8ns();
             space = await fnGetSpace(initialData, initialRel8ns);
             await space.initialized;
         });
 
-        const fnIt: any = useFit ? fit : it;
+        const fnIfWeBlock: any = shortcircuitRespec ? ifWeMight : ifWe;
 
-        fnIt(`${logContext} should persist all ibgibs (new, dna, intermediate)`, async () => {
+        await fnIfWeBlock(sir, `${logContext} should persist all ibgibs (new, dna, intermediate)`, async () => {
             let resNew = await factory.firstGen({
                 ib: 'test ib',
                 parentIbGib: factory.primitive({ ib: 'test ib' }),
@@ -241,13 +261,12 @@ export function testSpace_persistTransformResult({
 
             let resGet = await getFromSpace({ addrs: allAddrs, space });
 
-            expect(resGet).withContext('resGet').toBeTruthy();
-            expect(resGet.success).toBeTrue();
-            expect(resGet.ibGibs).toBeTruthy();
-            expect(resGet.ibGibs!.length).toEqual(allAddrs.length);
-            expect(resGet.ibGibs![0]).toEqual(newIbGib);
+            iReckon(sir, resGet).asTo('resGet').isGonnaBeTruthy();
+            iReckon(sir, resGet.success).isGonnaBeTrue();
+            iReckon(sir, resGet.ibGibs).isGonnaBeTruthy();
+            iReckon(sir, resGet.ibGibs!.length).isGonnaBe(allAddrs.length);
+            iReckon(sir, resGet.ibGibs![0]).isGonnaBe(newIbGib);
         });
 
-        resolve();
     });
 }

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

@@ -2,11 +2,12 @@ import { IbGibRel8ns_V1, IbGib_V1 } from '@ibgib/ts-gib/dist/V1/index.mjs';
 import { IbGibAddr, IbGib, IbGibRel8ns, TjpIbGibAddr } from '@ibgib/ts-gib';
 
 import {
-    Witness, WitnessCmdData, WitnessCmdIbGib, WitnessCmdRel8ns,
+    Witness,
     WitnessData_V1, WitnessResultData, WitnessResultIbGib, WitnessResultRel8ns,
 } from '../witness-types.mjs';
 import { IbGibSpaceAny } from './space-base-v1.mjs';
 import { ENCRYPTION_REL8N_NAME } from '../../common/encrypt/encrypt-constants.mjs';
+import { WitnessCmdData, WitnessCmdIbGib, WitnessCmdRel8ns, } from '../witness-cmd/witness-cmd-types.mjs';
 
 /**
  * Marker type to show intent that it should be the spaceId, i.e.

package/src/witness/witness-base-v1.mts

@@ -9,6 +9,8 @@ import { validateGib, validateIb, validateIbGibIntrinsically } from '@ibgib/ts-g
 import { ErrorIbGib_V1 } from '../common/error/error-types.mjs';
 import { toDto } from '../common/other/ibgib-helper.mjs';
 import { GLOBAL_LOG_A_LOT } from '../core-constants.mjs';
+import { IbGibLocalSpaceService_AllPowerful } from '../core-types.mjs';
+import { clone, pretty } from '@ibgib/helper-gib';
 
 const logalot = GLOBAL_LOG_A_LOT || false;
 
@@ -165,8 +167,8 @@ export abstract class WitnessBase_V1<
 
         // let dtoIbGib: IbGib_V1<TData, TRel8ns> = { ib: (this.ib || '').slice() };
         // if (this.gib) { dtoIbGib.gib = this.gib.slice(); };
-        // if (this.data) { dtoIbGib.data = h.clone(this.data); }
-        // if (this.rel8ns) { dtoIbGib.rel8ns = h.clone(this.rel8ns); }
+        // if (this.data) { dtoIbGib.data = clone(this.data); }
+        // if (this.rel8ns) { dtoIbGib.rel8ns = clone(this.rel8ns); }
 
         // return dtoIbGib;
     }
@@ -190,14 +192,14 @@ export abstract class WitnessBase_V1<
             if (!dto.ib) { console.warn(`${lc} dto.ib is falsy.`); }
             if (!dto.gib) { console.warn(`${lc} dto.gib is falsy.`); }
 
-            this.ib = h.clone(dto.ib);
-            this.gib = h.clone(dto.gib);
+            this.ib = clone(dto.ib);
+            this.gib = clone(dto.gib);
             if (dto.data) {
-                this.data = h.clone(dto.data);
+                this.data = clone(dto.data);
             } else {
                 delete this.data;
             }
-            if (dto.rel8ns) { this.rel8ns = h.clone(dto.rel8ns); } else { delete this.rel8ns; }
+            if (dto.rel8ns) { this.rel8ns = clone(dto.rel8ns); } else { delete this.rel8ns; }
 
             return Promise.resolve();
         } catch (error) {

package/src/witness/witness-cmd/witness-cmd-types.mts

@@ -0,0 +1,38 @@
+import { IbGibRel8ns_V1 } from "@ibgib/ts-gib/dist/V1/types.mjs";
+import { WitnessArgData, WitnessArgIbGib } from "../witness-types.mjs";
+import { IbGib } from "@ibgib/ts-gib/dist/types.mjs";
+
+/**
+ * Base information for cmd with optional modifiers to interact with a witness.
+ *
+ * Note that it is not necessary for a witness to listen to these types of
+ * ibgibs, this is just convenient plumbing for those who wish to listen to
+ * command-style ibgibs.
+ */
+export interface WitnessCmdData<TCmds, TCmdModifiers> extends WitnessArgData {
+    /**
+     * The `cmd` property is the name of the command, analogous to a function
+     * name.
+     */
+    cmd: TCmds | string;
+    /**
+     * Optional modifier flag(s) to the command.
+     *
+     * ## notes
+     *
+     * An implementing class can always use/extend these or extend the interface
+     * of the options data.
+     */
+    cmdModifiers?: (TCmdModifiers | string)[];
+}
+
+export interface WitnessCmdRel8ns extends IbGibRel8ns_V1 {
+}
+
+export interface WitnessCmdIbGib<
+    TIbGib extends IbGib,
+    TCmds, TCmdModifiers,
+    TCmdData extends WitnessCmdData<TCmds, TCmdModifiers>,
+    TCmdRel8ns extends WitnessCmdRel8ns,
+> extends WitnessArgIbGib<TIbGib, TCmdData, TCmdRel8ns> {
+}

package/src/witness/witness-helper.mts

@@ -7,6 +7,7 @@ import {
 import { GLOBAL_LOG_A_LOT } from '../core-constants.mjs';
 import { WITNESS_ARG_METADATA_STRING, WITNESS_RESULT_METADATA_STRING } from './witness-constants.mjs';
 
+import { WitnessCmdData } from './witness-cmd/witness-cmd-types.mjs';
 
 const logalot = GLOBAL_LOG_A_LOT || false;
 
@@ -254,3 +255,33 @@ export function validateWitnessClassname({
         if (logalot) { console.log(`${lc} complete.`); }
     }
 }
+
+/**
+ * @throws if `ibGib` falsy.
+ *
+ * @returns true ibGib indicates a cmd arg ibgib, else false
+ */
+export function isCommand({
+    ibGib,
+}: {
+    ibGib: IbGib_V1,
+}): boolean {
+    const lc = `[${isCommand.name}]`;
+    try {
+        if (logalot) { console.log(`${lc} starting...`); }
+
+        if (!ibGib) { throw new Error(`ibGib required (E: e11cee2a6c59a5e7a4d39ea55751c423)`); }
+
+        if (!ibGib.data) {
+            return false; /* <<<< returns early */
+        }
+
+        const cmdData = (ibGib.data as WitnessCmdData<any, any>);
+        return (cmdData.cmd && typeof (cmdData.cmd) === 'string');
+    } catch (error) {
+        console.error(`${lc} ${error.message}`);
+        throw error;
+    } finally {
+        if (logalot) { console.log(`${lc} complete.`); }
+    }
+}

package/src/witness/witness-types.mts

@@ -19,8 +19,8 @@ import { ErrorIbGib_V1 } from '../common/error/error-types.mjs';
 export interface Witness<
     TIbGibIn extends IbGib,
     TIbGibOut extends IbGib,
-    TData = any,
-    TRel8ns extends IbGibRel8ns = IbGibRel8ns,
+    TData extends WitnessData_V1 = WitnessData_V1,
+    TRel8ns extends WitnessRel8ns_V1 = WitnessRel8ns_V1,
 >
     extends IbGibWithDataAndRel8ns<TData, TRel8ns> {
     witness(arg: TIbGibIn): Promise<TIbGibOut | undefined>;
@@ -132,61 +132,45 @@ export interface Witness_V1<
  * ibgibs, this is just convenient plumbing for those who wish to listen to
  * command-style ibgibs.
  */
-export interface WitnessCmdData<TCmds, TCmdModifiers> {
+export interface WitnessArgData {
     /**
      * Not really in use atm, but will use in the future.
      */
     version?: string;
     /**
-     * The `cmd` property is the name of the command, analogous to a function
-     * name.
-     */
-    cmd: TCmds | string;
-    /**
-     * Optional modifier flag(s) to the command.
-     *
-     * ## notes
-     *
-     * An implementing class can always use/extend these or extend the interface
-     * of the options data.
-     */
-    cmdModifiers?: (TCmdModifiers | string)[];
-    /**
-     * Addrs of ibgibs to get/delete
+     * Addrs of ibgibs that this witness arg is wrapping.
      */
     ibGibAddrs?: IbGibAddr[];
 }
 
-export interface WitnessCmdRel8ns extends IbGibRel8ns_V1 {
+export interface WitnessArgRel8ns extends IbGibRel8ns_V1 {
 }
 
-export interface WitnessCmdIbGib<
+
+
+/**
+ * Shape of an arg wrapper ibgib with a couple common-use properties in data and
+ * the object class itself.
+ *
+ * This is meant to serve as a base class for others, most notably command arg
+ * ibgibs, when using witness ibgibs.
+ */
+export interface WitnessArgIbGib<
     TIbGib extends IbGib,
-    TCmds, TCmdModifiers,
-    TCmdData extends WitnessCmdData<TCmds, TCmdModifiers>,
-    TCmdRel8ns extends WitnessCmdRel8ns,
-> extends IbGib_V1<TCmdData, TCmdRel8ns> {
+    TArgData extends WitnessArgData,
+    TArgRel8ns extends WitnessArgRel8ns,
+> extends IbGib_V1<TArgData, TArgRel8ns> {
     /**
-     * When putting ibGibs, we don't want to persist the entire graph in the
-     * data object. So these ibGibs live on the ibGib arg object itself.
-     *
-     * If only ibGibs are passed in, and not their corresponding ibGibAddrs in
-     * the `TOptsData`, then you can't confirm cryptographically if the ibGibs
-     * are legit.  But if you include their corresponding ibGibAddrs in that
-     * data, then the space can confirm that the ibGibs have not been altered
-     * from the expected cryptographic audit trail.
-     *
-     * This doesn't mean that the ibGibs are kosher completely, but at least
-     * there is internal agreement and an audit trail.
+     * ibgib(s) that this arg wraps.
      *
-     * ## example
-     *
-     * For an example, check out sync space saga
+     * So when you pass in an arg to a witness, this is used often as the
+     * payload. For example, a space witness acts like a repo with puts and
+     * gets command args. This will contain the references to the ibgibs being
+     * put into the space.
      */
     ibGibs?: TIbGib[];
 }
 
-
 export interface WitnessResultData {
     /**
      * The address of the options ibGib that corresponds this space result.
@@ -242,8 +226,14 @@ export interface WitnessResultIbGib<
     extends IbGibWithDataAndRel8ns<TResultData, TResultRel8ns> {
 
     /**
-     * When expecting ibGibs back, we don't want to persist the graph. So this property of
-     * ibGibs lives on the ibGib result object, but not in the `data` property.
+     * Reference to list of result ibgibs from witness operation.
+     *
+     * ## notes
+     *
+     * * this does not have to be the only property on the concrete result
+     *   ibgib. From my experience so far, this is convenient for when there is
+     *   one and only one obvious result from a witness operation, like a get
+     *   command that returns a list of ibgibs.
      */
     ibGibs?: TIbGib[];
 }