@ibgib/core-gib 0.1.20 → 0.1.22

package/src/sync/sync-saga-context/sync-saga-context-helpers.mts

@@ -2,27 +2,24 @@
  * @module sync saga context helpers
  */
 
-import { extractErrorMsg } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
+import { extractErrorMsg, getTimestamp } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
 import { Factory_V1 } from '@ibgib/ts-gib/dist/V1/factory.mjs';
 import { getIbGibAddr } from '@ibgib/ts-gib/dist/helper.mjs';
 import { IbGib_V1, } from '@ibgib/ts-gib/dist/V1/types.mjs';
 import { Ib } from '@ibgib/ts-gib/dist/types.mjs';
 
 import { SYNC_SAGA_CONTEXT_ATOM } from './sync-saga-context-constants.mjs';
-import { SYNC_SAGA_PAYLOAD_ADDRS_REL8N_NAME } from '../sync-constants.mjs';
+import { SYNC_SAGA_PAYLOAD_ADDRS_DOMAIN } from '../sync-constants.mjs';
 import {
-    SyncSagaContextCmd, SyncSagaContextData_V1, SyncSagaContextIbGib_V1,
+    SyncSagaContextData_V1, SyncSagaContextIbGib_V1,
     SyncSagaContextIb_V1, SyncSagaContextRel8ns_V1
 } from './sync-saga-context-types.mjs';
+import { getTimestampInfo } from '../../common/other/ibgib-helper.mjs';
 
 /**
  * Options for creating a SyncSagaContext ibgib.
  */
 export interface CreateSyncSagaContextOptions {
-    /**
-     * Optional command string (e.g. 'process').
-     */
-    cmd?: SyncSagaContextCmd | string;
     /**
      * The main saga frame (Init, Ack, etc.).
      */
@@ -32,9 +29,10 @@ export interface CreateSyncSagaContextOptions {
      */
     sessionKeystones?: IbGib_V1[];
     /**
-     * Payload addresses (strings) for bulk data.
+     * Domain payload ibgibs when the sync saga frame includes actual domain
+     * payloads to send, e.g., in a Delta frame.
      */
-    payloadAddrs?: string[];
+    payloadIbGibsDomain?: IbGib_V1[];
 }
 
 /**
@@ -48,11 +46,12 @@ export async function getSyncSagaContextIb({
     const lc = `[${getSyncSagaContextIb.name}]`;
     try {
         if (!data) { throw new Error(`data required (E: 839d82138c234b3e89582855594191fe)`); }
-        const cmd = data.cmd || 'default';
+
+        const payloadCount = data['@payloadAddrsDomain'] ? data['@payloadAddrsDomain'].length : 0;
         // sync_sagacontext cmd
         const ib = [
             SYNC_SAGA_CONTEXT_ATOM,
-            cmd
+            payloadCount,
         ].join(' ');
 
         return ib;
@@ -73,17 +72,25 @@ export async function parseSyncSagaContextIb({
     const lc = `[${parseSyncSagaContextIb.name}]`;
     try {
         const parts = ib.split(' ');
-        if (parts.length < 2) {
-            throw new Error(`Invalid sync saga context ib. Expected at least 2 parts [atom cmd]. Got ${parts.length}. (E: 8b06c88820c74f5fb9f21f148459422a)`);
+        if (parts.length !== 2) {
+            throw new Error(`Invalid sync saga context ib. Expected at least 2 parts [atom, payloadCount]. Got ${parts.length}. (E: 8b06c88820c74f5fb9f21f148459422a)`);
         }
-        const [atom, ...rest] = parts;
-        const cmd = rest.join(' '); // cmd might have spaces if it's not a strict enum? but usually single word key.
+        const [
+            atom,
+            payloadCountStr,
+        ] = parts;
 
         if (atom !== SYNC_SAGA_CONTEXT_ATOM) {
             throw new Error(`Atom mismatch. Expected ${SYNC_SAGA_CONTEXT_ATOM}. Got ${atom}. (E: 67d71fc0f8d04840b178652309f471f5)`);
         }
 
-        return { atom, cmd };
+        if (!payloadCountStr) { throw new Error(`invalid ib. second piece should be payloadCount but is falsy (E: 0bb7580793d800ca02227828a7294826)`); }
+        const payloadCount = parseInt(payloadCountStr);
+        if (isNaN(payloadCount)) {
+            throw new Error(`payloadCountStr is not a number. (E: 49457814282a44069871630987588722)`);
+        }
+
+        return { atom, payloadCount };
     } catch (error) {
         console.error(`${lc} ${extractErrorMsg(error)}`);
         throw error;
@@ -96,26 +103,32 @@ export async function parseSyncSagaContextIb({
  * @returns The context ibGib.
  */
 export async function createSyncSagaContext({
-    cmd,
     sagaFrame,
     sessionKeystones,
-    payloadAddrs,
+    payloadIbGibsDomain,
 }: CreateSyncSagaContextOptions): Promise<SyncSagaContextIbGib_V1> {
 
+    const date = new Date();
+    const timestamp = getTimestamp(date);
+    const timestampMs = date.getMilliseconds();
+
     const data: SyncSagaContextData_V1 = {
-        cmd,
+        timestamp,
+        timestampMs,
     };
-    if (payloadAddrs && payloadAddrs.length > 0) {
-        data[SYNC_SAGA_PAYLOAD_ADDRS_REL8N_NAME] = payloadAddrs;
-    }
-
-    const rel8ns: SyncSagaContextRel8ns_V1 = {};
 
-    if (sagaFrame) {
-        rel8ns.sagaFrame = [getIbGibAddr(sagaFrame)];
+    // Domain Payloads 
+    const payloadAddrsDomain = payloadIbGibsDomain ? payloadIbGibsDomain?.map(x => getIbGibAddr({ ibGib: x })) : undefined;
+    if (payloadAddrsDomain && payloadAddrsDomain.length > 0) {
+        data[SYNC_SAGA_PAYLOAD_ADDRS_DOMAIN] = payloadAddrsDomain;
     }
+
+    // rel8ns should always have saga frame, sometimes have keystone
+    const rel8ns: SyncSagaContextRel8ns_V1 = {
+        sagaFrame: [getIbGibAddr({ ibGib: sagaFrame })],
+    };
     if (sessionKeystones && sessionKeystones.length > 0) {
-        rel8ns.sessionKeystone = sessionKeystones.map(getIbGibAddr);
+        rel8ns.sessionKeystone = sessionKeystones.map(x => getIbGibAddr({ ibGib: x }));
     }
 
     // Generate standard ib
@@ -126,7 +139,12 @@ export async function createSyncSagaContext({
         ib,
         data,
         rel8ns,
-    });
+    }) as SyncSagaContextIbGib_V1;
+
+    // Attach actual ibgibs for transport 
+    if (payloadIbGibsDomain && payloadIbGibsDomain.length > 0) {
+        contextIbGib.payloadIbGibsDomain = payloadIbGibsDomain;
+    }
 
-    return contextIbGib as SyncSagaContextIbGib_V1;
+    return contextIbGib;
 }

package/src/sync/sync-saga-context/sync-saga-context-types.mts

@@ -4,28 +4,17 @@
 
 import { IbGibAddr } from '@ibgib/ts-gib/dist/types.mjs';
 import { IbGibData_V1, IbGibRel8ns_V1, IbGib_V1 } from '@ibgib/ts-gib/dist/V1/types.mjs';
-import { SYNC_SAGA_PAYLOAD_ADDRS_REL8N_NAME } from '../sync-constants.mjs';
 
-// #region SyncSagaContextCmd
-/**
- * Commands for the Sync Saga Context.
- */
-export type SyncSagaContextCmd =
-    | 'process'
-    | 'ping';
-export const SyncSagaContextCmd = {
-    process: 'process' as SyncSagaContextCmd,
-    ping: 'ping' as SyncSagaContextCmd,
-} satisfies { [key in SyncSagaContextCmd]: SyncSagaContextCmd };
-export const SYNC_SAGA_CONTEXT_CMD_VALID_VALUES = Object.values(SyncSagaContextCmd);
-export function isValidSyncSagaContextCmd(cmd: string): cmd is SyncSagaContextCmd {
-    return SYNC_SAGA_CONTEXT_CMD_VALID_VALUES.includes(cmd as SyncSagaContextCmd);
-}
-// #endregion SyncSagaContextCmd
+import { SYNC_SAGA_PAYLOAD_ADDRS_DOMAIN } from '../sync-constants.mjs';
+import { SyncIbGib_V1 } from '../sync-types.mjs';
+import { SYNC_SAGA_CONTEXT_ATOM } from './sync-saga-context-constants.mjs';
 
 export interface SyncSagaContextIb_V1 {
-    atom: string; // SYNC_SAGA_CONTEXT_ATOM
-    cmd: SyncSagaContextCmd | string;
+    atom: typeof SYNC_SAGA_CONTEXT_ATOM;
+    /**
+     * simple metadata count of data["@payloadAddrsDomain"]
+     */
+    payloadCount: number;
 }
 
 /**
@@ -33,16 +22,10 @@ export interface SyncSagaContextIb_V1 {
  */
 export interface SyncSagaContextData_V1 extends IbGibData_V1 {
     /**
-     * Contextual command or metadata for the transport layer.
-     * e.g. "process", "ping".
-     */
-    cmd?: SyncSagaContextCmd | string;
-
-    /**
-     * Payload data (ibGibs) being transported in this context (e.g. for Delta stage).
+     * Payload data addresses for DOMAIN ibGibs (Timeline frames, user content).
      * Soft-linked via data property to avoid hard-linking graph dependencies.
      */
-    [SYNC_SAGA_PAYLOAD_ADDRS_REL8N_NAME]?: IbGibAddr[];
+    [SYNC_SAGA_PAYLOAD_ADDRS_DOMAIN]?: IbGibAddr[];
 }
 
 /**
@@ -52,9 +35,10 @@ export interface SyncSagaContextData_V1 extends IbGibData_V1 {
 export interface SyncSagaContextRel8ns_V1 extends IbGibRel8ns_V1 {
     /**
      * The primary Saga Frame being transported (Init, Ack, Delta, etc.).
-     * 0..1 (Optional only if trivial ping or strict metadata update)
+     * 
+     * Should be a single addr.
      */
-    sagaFrame?: IbGibAddr[];
+    sagaFrame: IbGibAddr[];
 
     /**
      * The Ephemeral Session Keystone Identity used for this saga.
@@ -67,4 +51,19 @@ export interface SyncSagaContextRel8ns_V1 extends IbGibRel8ns_V1 {
  * The SyncSagaContext is a full-fledged ibGib used as the payload
  * between Sync Peers.
  */
-export interface SyncSagaContextIbGib_V1 extends IbGib_V1<SyncSagaContextData_V1, SyncSagaContextRel8ns_V1> { }
+export interface SyncSagaContextIbGib_V1 extends IbGib_V1<SyncSagaContextData_V1, SyncSagaContextRel8ns_V1> {
+    /**
+     * Domain ibgibs - OUTBOUND only.
+     * 
+     * For inbound, the domain payload ibgibs are streamed via observable in the
+     * peer.
+     */
+    payloadIbGibsDomain?: IbGib_V1[];
+
+    /**
+     * Reference to the actual sync saga frame that this context conveys.
+     * 
+     * This frame's addr should be {@link SyncSagaContextRel8ns_V1.sagaFrame}.
+     */
+    sagaFrame: SyncIbGib_V1;
+}