@jay-framework/serialization 0.5.0

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+import { JSONPatch, ArrayContexts } from '@jay-framework/json-patch';
+
+type Deserialize<T extends object> = (jsonPatch: JSONPatch) => [T, Deserialize<T>];
+declare function deserialize<T extends object>(jsonPatch: JSONPatch): [T, Deserialize<T>];
+
+type Serialize<T extends object> = (entity: any, contexts?: ArrayContexts) => [JSONPatch, Serialize<T>];
+declare function serialize<T extends object>(entity: any, contexts?: ArrayContexts): [JSONPatch, Serialize<T>];
+
+export { type Deserialize, type Serialize, deserialize, serialize };

package/dist/index.js

@@ -0,0 +1,29 @@
+import { ADD, REPLACE, patch, diff } from "@jay-framework/json-patch";
+function deserialize(jsonPatch) {
+  return _deserialize(void 0)(jsonPatch);
+}
+function _deserialize(obj) {
+  return (jsonPatch) => {
+    if (jsonPatch.length === 1 && jsonPatch[0].path.length === 0 && (jsonPatch[0].op === ADD || jsonPatch[0].op === REPLACE)) {
+      obj = jsonPatch[0].value;
+      return [obj, _deserialize(obj)];
+    }
+    if (!obj)
+      obj = {};
+    let newObj = patch(obj, jsonPatch);
+    return [newObj, _deserialize(newObj)];
+  };
+}
+function serialize(entity, contexts) {
+  return _serialize(void 0, contexts)(entity);
+}
+function _serialize(lastEntity, contexts) {
+  return (entity) => {
+    let patch2 = diff(entity, lastEntity, contexts);
+    return [patch2[0], _serialize(entity, contexts)];
+  };
+}
+export {
+  deserialize,
+  serialize
+};

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@jay-framework/serialization",
+  "version": "0.5.0",
+  "type": "module",
+  "license": "Apache-2.0",
+  "main": "dist/index.js",
+  "files": [
+    "dist",
+    "readme.md"
+  ],
+  "scripts": {
+    "build": "npm run build:js && npm run build:types",
+    "build:watch": "npm run build:js -- --watch & npm run build:types -- --watch",
+    "build:js": "vite build",
+    "build:types": "tsup lib/index.ts --dts-only --format esm",
+    "build:check-types": "tsc",
+    "clean": "rimraf dist",
+    "confirm": "npm run clean && npm run build && npm run build:check-types && npm run test",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "@jay-framework/json-patch": "workspace:^"
+  },
+  "devDependencies": {
+    "@jay-framework/dev-environment": "workspace:^",
+    "@types/node": "^20.11.5",
+    "rimraf": "^5.0.5",
+    "tsup": "^8.0.1",
+    "typescript": "^5.3.3",
+    "vite": "^5.0.11",
+    "vitest": "^1.2.1"
+  }
+}

package/readme.md

@@ -0,0 +1,69 @@
+# Jay Serialization
+
+A **stateful serialization** implementation that serializes an **object** into a **diff** to be applied to another
+**object** on the other side.
+
+The algorithm is useful when two parties have frequent updates of an updated object sent from party `A` to party `B`.
+
+1. Party `A` calls the `serialize` function which produces a `JSONPatch` and a new `seralize`
+   function to compute the next patch.
+2. Party `B` receives the `JSONPatch`, using `deserialize` gets the updated object and a new `deserialize` function
+   to apply the next patch.
+
+## Signature
+
+```typescript
+export type Serialize<T extends object> = (
+  entity: any,
+  contexts?: ArrayContexts,
+) => [JSONPatch, Serialize<T>];
+declare function serialize<T extends object>(
+  entity: any,
+  contexts?: ArrayContexts,
+): [JSONPatch, Serialize<T>];
+
+export type Deserialize<T extends object> = (jsonPatch: JSONPatch) => [T, Deserialize<T>];
+declare function deserialize<T extends object>(jsonPatch: JSONPatch): [T, Deserialize<T>];
+```
+
+## library notes
+
+- The library assumes the object to serialize and deserialize are immutable objects.
+  It always creates new instances in deserialization.
+- The library serialization always serializes the first object in full on the path `[]`,
+  which is then deserialized as is.
+- It is using the `@jay-framework/json-patch` library to compute and apply the `JSONPatch`es.
+- The `ArrayContexts` parameter is the same from the `@jay-framework/json-patch` library.
+- The library is used by `@jay-framework/secure` for the worker - main context communication.
+- The library can also be used for server - client communication if also using global object version management,
+  such as optimistic locking.
+
+## examples
+
+Serialization:
+
+```typescript
+let [patch, nextSerialize] = serialize({ a: 1, b: 2, c: 'abcd', d: true });
+expect(patch).toEqual([{ op: ADD, path: [], value: { a: 1, b: 2, c: 'abcd', d: true } }]);
+
+[patch, nextSerialize] = nextSerialize({ a: 11, b: 2, c: 'abcd', d: true });
+expect(patch).toEqual([{ op: REPLACE, path: ['a'], value: 11 }]);
+
+[patch, nextSerialize] = nextSerialize({ a: 11, b: 12, c: 'abcd', d: true });
+expect(patch).toEqual([{ op: REPLACE, path: ['b'], value: 12 }]);
+```
+
+Deserialization:
+
+```typescript
+let [target, nextSerialize] = deserialize([
+  { op: ADD, path: [], value: { a: 1, b: 2, c: 'abcd', d: true } },
+]);
+expect(target).toEqual({ a: 1, b: 2, c: 'abcd', d: true });
+
+[target, nextSerialize] = nextSerialize([{ op: REPLACE, path: ['a'], value: 11 }]);
+expect(target).toEqual({ a: 11, b: 2, c: 'abcd', d: true });
+
+[target, nextSerialize] = nextSerialize([{ op: REPLACE, path: ['b'], value: 12 }]);
+expect(target).toEqual({ a: 11, b: 12, c: 'abcd', d: true });
+```