feat: support reference mutation through IPC

src/shared-resources.ts

@@ -182,7 +182,7 @@ const remoteProcedureCall = async (
       type: SHARED_RESOURCE_MESSAGE_TYPES.REMOTE_PROCEDURE_CALL,
       name,
       method,
-      args,
+      args: args.map(encodeArg),
       id: requestId,
     } satisfies IPCRemoteProcedureCallMessage,
     validator: (message): message is IPCRemoteProcedureCallResultMessage =>
@@ -200,6 +200,144 @@ const remoteProcedureCall = async (
   return response.value;
 };
 
+const ENC_TAG = '__sr_enc';
+
+const isPlainObject = (v: unknown): v is Record<string, unknown> => {
+  if (v === null || typeof v !== 'object' || Array.isArray(v)) return false;
+  const proto = Object.getPrototypeOf(v) as unknown;
+  return proto === Object.prototype || proto === null;
+};
+
+const encodeObjectValues = (
+  obj: Record<string, unknown>
+): Record<string, unknown> => {
+  const result: Record<string, unknown> = {};
+  for (const key of Object.keys(obj)) result[key] = encodeArg(obj[key]);
+  return result;
+};
+
+const encodeObject = (v: Record<string, unknown>): unknown =>
+  ENC_TAG in v
+    ? { [ENC_TAG]: 'esc', v: encodeObjectValues(v) }
+    : encodeObjectValues(v);
+
+export const encodeArg = (v: unknown): unknown => {
+  if (v === undefined) return { [ENC_TAG]: 'u' };
+  if (typeof v === 'bigint') return { [ENC_TAG]: 'bi', v: v.toString() };
+  if (v instanceof Date) return { [ENC_TAG]: 'd', v: v.toISOString() };
+  if (v instanceof Map)
+    return {
+      [ENC_TAG]: 'm',
+      v: Array.from(v.entries(), (e) => [encodeArg(e[0]), encodeArg(e[1])]),
+    };
+  if (v instanceof Set) return { [ENC_TAG]: 's', v: Array.from(v, encodeArg) };
+  if (Array.isArray(v)) return v.map(encodeArg);
+  if (isPlainObject(v)) return encodeObject(v);
+  return v;
+};
+
+const decodeObjectValues = (
+  obj: Record<string, unknown>
+): Record<string, unknown> => {
+  const result: Record<string, unknown> = {};
+  for (const key of Object.keys(obj)) result[key] = decodeArg(obj[key]);
+  return result;
+};
+
+const decodeEncoded = (enc: Record<string, unknown>): unknown => {
+  const t = enc[ENC_TAG];
+  if (t === 'u') return undefined;
+  if (t === 'bi') return BigInt(enc.v as string);
+  if (t === 'd') return new Date(enc.v as string);
+  if (t === 'm') {
+    const entries = enc.v as [unknown, unknown][];
+    return new Map(
+      entries.map(
+        (e) => [decodeArg(e[0]), decodeArg(e[1])] as [unknown, unknown]
+      )
+    );
+  }
+  if (t === 's') return new Set((enc.v as unknown[]).map(decodeArg));
+  if (t === 'esc') return decodeObjectValues(enc.v as Record<string, unknown>);
+  return decodeObjectValues(enc);
+};
+
+export const decodeArg = (v: unknown): unknown => {
+  if (Array.isArray(v)) return v.map(decodeArg);
+  if (isPlainObject(v))
+    return ENC_TAG in v ? decodeEncoded(v) : decodeObjectValues(v);
+  return v;
+};
+
+const writeBackDate = (original: Date, mutated: Date): void => {
+  original.setTime(mutated.getTime());
+};
+
+const writeBackMap = (
+  original: Map<unknown, unknown>,
+  mutated: Map<unknown, unknown>
+): void => {
+  original.clear();
+  for (const [k, v] of mutated) original.set(k, v);
+};
+
+const writeBackSet = (original: Set<unknown>, mutated: Set<unknown>): void => {
+  original.clear();
+  for (const v of mutated) original.add(v);
+};
+
+const tryReconcileInPlace = (original: unknown, mutated: unknown): boolean => {
+  if (isPlainObject(original) && isPlainObject(mutated)) {
+    writeBackObject(original, mutated);
+    return true;
+  }
+  if (Array.isArray(original) && Array.isArray(mutated)) {
+    writeBackArray(original, mutated);
+    return true;
+  }
+  if (original instanceof Map && mutated instanceof Map) {
+    writeBackMap(original, mutated);
+    return true;
+  }
+  if (original instanceof Set && mutated instanceof Set) {
+    writeBackSet(original, mutated);
+    return true;
+  }
+  if (original instanceof Date && mutated instanceof Date) {
+    writeBackDate(original, mutated);
+    return true;
+  }
+  return false;
+};
+
+const writeBackArray = (original: unknown[], mutated: unknown[]): void => {
+  const minLen = Math.min(original.length, mutated.length);
+
+  for (let i = 0; i < minLen; i++) {
+    if (!tryReconcileInPlace(original[i], mutated[i])) original[i] = mutated[i];
+  }
+
+  if (original.length > mutated.length) original.splice(mutated.length);
+
+  for (let i = original.length; i < mutated.length; i++)
+    original.push(mutated[i]);
+};
+
+const writeBackObject = (
+  orig: Record<string, unknown>,
+  mut: Record<string, unknown>
+): void => {
+  for (const key of Object.keys(orig)) if (!(key in mut)) delete orig[key];
+
+  for (const key of Object.keys(mut)) {
+    if (!tryReconcileInPlace(orig[key], mut[key])) orig[key] = mut[key];
+  }
+};
+
+export const writeBack = (original: unknown, mutated: unknown): void => {
+  tryReconcileInPlace(original, mutated);
+};
+
 export const extractFunctionNames = (obj: Record<string, unknown>) => {
   const seen = new Set<string>();
   let current = obj;
@@ -335,14 +473,16 @@ export const handleRemoteProcedureCall = async (
 
   try {
     const method = methodCandidate.bind(entry.state);
-    const result = await method(...(message.args || []));
+    const callArgs = (message.args || []).map(decodeArg);
+    const result = await method(...callArgs);
 
     child.send({
       type: SHARED_RESOURCE_MESSAGE_TYPES.REMOTE_PROCEDURE_CALL_RESULT,
       id: message.id,
       value: {
         result,
         latest: state,
+        mutatedArgs: callArgs.map(encodeArg),
       },
     } satisfies IPCResponse);
   } catch (error) {
@@ -366,6 +506,10 @@ const constructSharedResourceWithRPCs = (
       if (typeof prop === 'string' && rpcs.includes(prop)) {
         return async (...args: unknown[]) => {
           const rpcResult = await remoteProcedureCall(name, prop, args);
+          const decodedMutatedArgs = rpcResult.mutatedArgs.map(decodeArg);
+
+          for (let i = 0; i < args.length; i++)
+            writeBack(args[i], decodedMutatedArgs[i]);
 
           for (const rpcKey of rpcs) {
             if (rpcKey in rpcResult.latest) {

src/types.ts

@@ -58,7 +58,11 @@ export type IPCResourceResultMessage = {
 export type IPCRemoteProcedureCallResultMessage = {
   type: typeof SHARED_RESOURCE_MESSAGE_TYPES.REMOTE_PROCEDURE_CALL_RESULT;
   id: string;
-  value?: { result: unknown; latest: Record<string, unknown> };
+  value?: {
+    result: unknown;
+    latest: Record<string, unknown>;
+    mutatedArgs: unknown[];
+  };
   error?: string;
 };
 

test/__fixtures__/references/mutation-resource.test.ts

@@ -0,0 +1,17 @@
+import { assert, test, waitForExpectedResult } from 'poku';
+import { resource } from '../../../src/index.js';
+import { MutatorContext } from './resource.js';
+
+test('Test second resource only', async () => {
+  const mutator = await resource.use(MutatorContext);
+  const value = await mutator.getValue();
+  const array: number[] = [];
+
+  await mutator.mutateArray(array);
+
+  assert.strictEqual(
+    array[0],
+    value,
+    'Array should contain the value returned by getValue()'
+  );
+});

test/__fixtures__/references/nested-mutation.test.ts

@@ -0,0 +1,43 @@
+import { assert, test } from 'poku';
+import { resource } from '../../../src/index.js';
+import { NestedMutatorContext } from './resource.js';
+
+test('Deeply nested array mutation via IPC', async () => {
+  const mutator = await resource.use(NestedMutatorContext);
+  const value = await mutator.getValue();
+  const obj = { nested: { arr: [] as number[] } };
+
+  await mutator.pushToNestedArray(obj);
+
+  assert.strictEqual(
+    obj.nested.arr[0],
+    value,
+    'Nested array should contain the value pushed by the remote method'
+  );
+});
+
+test('Array of objects mutation via IPC', async () => {
+  const mutator = await resource.use(NestedMutatorContext);
+  const arr = [{ x: 1 }, { x: 2 }, { x: 3 }];
+
+  await mutator.mutateArrayOfObjects(arr);
+
+  assert.deepStrictEqual(
+    arr,
+    [{ x: 2 }, { x: 3 }, { x: 4 }],
+    'Each object in the array should have its x property incremented'
+  );
+});
+
+test('Array truncation via IPC', async () => {
+  const mutator = await resource.use(NestedMutatorContext);
+  const arr = [10, 20, 30, 40];
+
+  await mutator.truncateArray(arr);
+
+  assert.deepStrictEqual(
+    arr,
+    [10, 20, 30],
+    'Array should be truncated to all but the last element'
+  );
+});

test/__fixtures__/references/object-mutation.test.ts

@@ -0,0 +1,31 @@
+import { assert, test } from 'poku';
+import { resource } from '../../../src/index.js';
+import { ObjectMutatorContext } from './resource.js';
+
+test('Object property mutation via IPC', async () => {
+  const mutator = await resource.use(ObjectMutatorContext);
+  const value = await mutator.getValue();
+  const obj: Record<string, unknown> = {};
+
+  await mutator.mutateObject(obj);
+
+  assert.strictEqual(
+    obj.key,
+    value,
+    'Object property should be set by the remote method'
+  );
+});
+
+test('Object property deletion via IPC', async () => {
+  const mutator = await resource.use(ObjectMutatorContext);
+  const obj: Record<string, unknown> = { toDelete: 'remove-me', keep: 42 };
+
+  await mutator.deleteKey(obj);
+
+  assert.strictEqual(
+    'toDelete' in obj,
+    false,
+    'Deleted property should not exist on the original object'
+  );
+  assert.strictEqual(obj.keep, 42, 'Non-deleted property should remain');
+});

test/__fixtures__/references/resource.ts

@@ -0,0 +1,73 @@
+import { resource } from '../../../src/index.js';
+
+export const MutatorContext = resource.create(() => {
+  const value = Math.random();
+  return {
+    mutateArray(arr: number[]) {
+      arr.push(value);
+    },
+    getValue() {
+      return value;
+    },
+  };
+});
+
+export const ObjectMutatorContext = resource.create(() => {
+  const value = Math.random();
+  return {
+    mutateObject(obj: Record<string, unknown>) {
+      obj.key = value;
+    },
+    deleteKey(obj: Record<string, unknown>) {
+      delete obj.toDelete;
+    },
+    getValue() {
+      return value;
+    },
+  };
+});
+
+export const NestedMutatorContext = resource.create(() => {
+  const value = Math.random();
+  return {
+    pushToNestedArray(obj: { nested: { arr: number[] } }) {
+      obj.nested.arr.push(value);
+    },
+    mutateArrayOfObjects(arr: Array<{ x: number }>) {
+      for (const item of arr) item.x += 1;
+    },
+    truncateArray(arr: number[]) {
+      arr.splice(arr.length - 1);
+    },
+    getValue() {
+      return value;
+    },
+  };
+});
+
+export const SpecialTypesMutatorContext = resource.create(() => ({
+  mutateDate(d: Date) {
+    d.setFullYear(2000);
+  },
+  mutateMap(m: Map<string, number>) {
+    m.set('added', 99);
+    m.delete('toRemove');
+  },
+  mutateSet(s: Set<number>) {
+    s.add(99);
+    s.delete(0);
+  },
+  setPropertyToUndefined(obj: Record<string, unknown>) {
+    obj.a = undefined;
+  },
+  pushUndefined(arr: (number | undefined)[]) {
+    arr.push(undefined);
+  },
+  mutateBigIntArray(arr: bigint[]) {
+    arr.push(99n);
+  },
+  mutateBigIntMap(m: Map<string, bigint>) {
+    m.set('added', 42n);
+    m.delete('toRemove');
+  },
+}));