@fluidframework/shared-object-base 0.54.0 → 0.55.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fluidframework/shared-object-base",
-  "version": "0.54.0",
+  "version": "0.55.0",
   "description": "Fluid base class for shared distributed data structures",
   "homepage": "https://fluidframework.com",
   "repository": "https://github.com/microsoft/FluidFramework",
@@ -11,54 +11,90 @@
   "module": "lib/index.js",
   "types": "dist/index.d.ts",
   "scripts": {
+    "bench": "ts-node bench/src/index.ts",
     "build": "npm run build:genver && concurrently npm:build:compile npm:lint && npm run build:docs",
-    "build:compile": "concurrently npm:tsc npm:build:esnext",
+    "build:commonjs": "npm run tsc && npm run build:test",
+    "build:compile": "concurrently npm:build:commonjs npm:build:esnext",
     "build:docs": "api-extractor run --local --typescript-compiler-folder ../../../node_modules/typescript && copyfiles -u 1 ./_api-extractor-temp/doc-models/* ../../../_api-extractor-temp/",
     "build:esnext": "tsc --project ./tsconfig.esnext.json",
     "build:full": "npm run build",
     "build:full:compile": "npm run build:compile",
     "build:genver": "gen-version",
+    "build:test": "tsc --project ./src/test/tsconfig.json",
     "ci:build:docs": "api-extractor run --typescript-compiler-folder ../../../node_modules/typescript && copyfiles -u 1 ./_api-extractor-temp/* ../../../_api-extractor-temp/",
     "clean": "rimraf dist lib *.tsbuildinfo *.build.log",
     "eslint": "eslint --format stylish src",
-    "eslint:fix": "eslint --format stylish src --fix",
+    "eslint:fix": "eslint --format stylish src --fix --fix-type problem,suggestion,layout",
     "lint": "npm run eslint",
     "lint:fix": "npm run eslint:fix",
+    "test": "npm run test:mocha",
+    "test:coverage": "nyc npm test -- --reporter xunit --reporter-option output=nyc/junit-report.xml",
+    "test:mocha": "mocha --recursive dist/test -r node_modules/@fluidframework/mocha-test-setup --unhandled-rejections=strict",
+    "test:mocha:verbose": "cross-env FLUID_TEST_VERBOSE=1 npm run test:mocha",
     "tsc": "tsc",
     "tsfmt": "tsfmt --verify",
     "tsfmt:fix": "tsfmt --replace"
   },
+  "nyc": {
+    "all": true,
+    "cache-dir": "nyc/.cache",
+    "exclude": [
+      "src/test/**/*.ts",
+      "dist/test/**/*.js"
+    ],
+    "exclude-after-remap": false,
+    "include": [
+      "src/**/*.ts",
+      "dist/**/*.js"
+    ],
+    "report-dir": "nyc/report",
+    "reporter": [
+      "cobertura",
+      "html",
+      "text"
+    ],
+    "temp-directory": "nyc/.nyc_output"
+  },
   "dependencies": {
     "@fluidframework/common-definitions": "^0.20.1",
     "@fluidframework/common-utils": "^0.32.1",
     "@fluidframework/container-definitions": "^0.44.0",
-    "@fluidframework/container-utils": "^0.54.0",
+    "@fluidframework/container-utils": "^0.55.0",
     "@fluidframework/core-interfaces": "^0.41.0",
-    "@fluidframework/datastore": "^0.54.0",
-    "@fluidframework/datastore-definitions": "^0.54.0",
+    "@fluidframework/datastore": "^0.55.0",
+    "@fluidframework/datastore-definitions": "^0.55.0",
     "@fluidframework/protocol-definitions": "^0.1026.0",
-    "@fluidframework/runtime-definitions": "^0.54.0",
-    "@fluidframework/runtime-utils": "^0.54.0",
-    "@fluidframework/telemetry-utils": "^0.54.0",
+    "@fluidframework/runtime-definitions": "^0.55.0",
+    "@fluidframework/runtime-utils": "^0.55.0",
+    "@fluidframework/telemetry-utils": "^0.55.0",
     "uuid": "^8.3.1"
   },
   "devDependencies": {
     "@fluidframework/build-common": "^0.23.0",
-    "@fluidframework/eslint-config-fluid": "^0.24.0",
+    "@fluidframework/eslint-config-fluid": "^0.25.0",
+    "@fluidframework/mocha-test-setup": "^0.55.0",
     "@microsoft/api-extractor": "^7.16.1",
+    "@rushstack/eslint-config": "^2.5.1",
+    "@types/benchmark": "^2.1.0",
+    "@types/mocha": "^8.2.2",
     "@types/node": "^14.18.0",
-    "@typescript-eslint/eslint-plugin": "~4.14.0",
-    "@typescript-eslint/parser": "~4.14.0",
+    "@typescript-eslint/eslint-plugin": "~5.9.0",
+    "@typescript-eslint/parser": "~5.9.0",
+    "benchmark": "^2.1.4",
     "concurrently": "^6.2.0",
     "copyfiles": "^2.1.0",
-    "eslint": "~7.18.0",
+    "cross-env": "^7.0.2",
+    "eslint": "~8.6.0",
+    "eslint-plugin-editorconfig": "~3.2.0",
     "eslint-plugin-eslint-comments": "~3.2.0",
-    "eslint-plugin-import": "~2.22.1",
+    "eslint-plugin-import": "~2.25.4",
     "eslint-plugin-no-null": "~1.0.2",
-    "eslint-plugin-prefer-arrow": "~1.2.2",
-    "eslint-plugin-react": "~7.22.0",
-    "eslint-plugin-unicorn": "~26.0.1",
+    "eslint-plugin-react": "~7.28.0",
+    "eslint-plugin-unicorn": "~40.0.0",
+    "mocha": "^8.4.0",
+    "nyc": "^15.0.0",
     "rimraf": "^2.6.2",
+    "ts-node": "^7.0.1",
     "typescript": "~4.1.3",
     "typescript-formatter": "7.1.0"
   }

package/src/index.ts

@@ -3,6 +3,7 @@
  * Licensed under the MIT License.
  */
 
+export * from "./serializer";
 export * from "./sharedObject";
 export * from "./summarySerializer";
 export * from "./types";

package/src/packageVersion.ts

@@ -6,4 +6,4 @@
  */
 
 export const pkgName = "@fluidframework/shared-object-base";
-export const pkgVersion = "0.54.0";
+export const pkgVersion = "0.55.0";

package/src/remoteObjectHandle.ts

@@ -0,0 +1,79 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { assert } from "@fluidframework/common-utils";
+import {
+    IFluidHandle,
+    IFluidHandleContext,
+    IRequest,
+    IResponse,
+    FluidObject,
+    IFluidRouter,
+} from "@fluidframework/core-interfaces";
+import { create404Response, exceptionToResponse, responseToException } from "@fluidframework/runtime-utils";
+
+/**
+ * This handle is used to dynamically load a Fluid object on a remote client and is created on parsing a serialized
+ * FluidObjectHandle.
+ * This class is used to generate an IFluidHandle when de-serializing any all handles (including handles to DDSs, custom
+ * objects) that are stored in SharedObjects. The Data Store or SharedObject corresponding to the IFluidHandle can be
+ * retrieved by calling `get` on it.
+ */
+export class RemoteFluidObjectHandle implements IFluidHandle {
+    public get IFluidRouter() { return this; }
+    public get IFluidHandleContext() { return this; }
+    public get IFluidHandle() { return this; }
+
+    public readonly isAttached = true;
+    private objectP: Promise<FluidObject> | undefined;
+
+    /**
+     * Creates a new RemoteFluidObjectHandle when parsing an IFluidHandle.
+     * @param absolutePath - The absolute path to the handle from the container runtime.
+     * @param routeContext - The root IFluidHandleContext that has a route to this handle.
+     */
+    constructor(
+        public readonly absolutePath: string,
+        public readonly routeContext: IFluidHandleContext,
+    ) {
+        assert(absolutePath.startsWith("/"), 0x19d /* "Handles should always have absolute paths" */);
+    }
+
+    public async get(): Promise<any> {
+        if (this.objectP === undefined) {
+            const request = { url: this.absolutePath };
+            this.objectP = this.routeContext.resolveHandle(request)
+                .then<FluidObject>((response) => {
+                    if (response.mimeType === "fluid/object") {
+                        const fluidObject: FluidObject = response.value;
+                        return fluidObject;
+                    }
+                    throw responseToException(response, request);
+                });
+        }
+        return this.objectP;
+    }
+
+    public attachGraph(): void {
+        return;
+    }
+
+    public bind(handle: IFluidHandle): void {
+        handle.attachGraph();
+    }
+
+    public async request(request: IRequest): Promise<IResponse> {
+        try {
+            const object: FluidObject<IFluidRouter> = await this.get();
+            const router = object.IFluidRouter;
+
+            return router !== undefined
+                ? router.request(request)
+                : create404Response(request);
+        } catch (error) {
+            return exceptionToResponse(error);
+        }
+    }
+}

package/src/serializer.ts

@@ -0,0 +1,216 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+// RATIONALE: Many methods consume and return 'any' by necessity.
+/* eslint-disable @typescript-eslint/no-unsafe-return */
+
+import { generateHandleContextPath } from "@fluidframework/runtime-utils";
+import { IFluidHandle, IFluidHandleContext } from "@fluidframework/core-interfaces";
+import { RemoteFluidObjectHandle } from "./remoteObjectHandle";
+
+/**
+ * JSON serialized form of an IFluidHandle
+ */
+ export interface ISerializedHandle {
+    // Marker to indicate to JSON.parse that the object is a Fluid handle
+    type: "__fluid_handle__";
+
+    // URL to the object. Relative URLs are relative to the handle context passed to the stringify.
+    url: string;
+}
+
+export const isSerializedHandle = (value: any): value is ISerializedHandle =>
+    value?.type === "__fluid_handle__";
+
+export interface IFluidSerializer {
+    /**
+     * Given a mostly-plain object that may have handle objects embedded within, will return a fully-plain object
+     * where any embedded IFluidHandles have been replaced with a serializable form.
+     *
+     * The original `input` object is not mutated.  This method will shallowly clones all objects in the path from
+     * the root to any replaced handles.  (If no handles are found, returns the original object.)
+     */
+    encode(value: any, bind: IFluidHandle): any;
+
+    /**
+     * Given a fully-jsonable object tree that may have encoded handle objects embedded within, will return an
+     * equivalent object tree where any encoded IFluidHandles have been replaced with their decoded form.
+     *
+     * The original `input` object is not mutated.  This method will shallowly clone all objects in the path from
+     * the root to any replaced handles.  (If no handles are found, returns the original object.)
+     *
+     * The decoded handles are implicitly bound to the handle context of this serializer.
+     */
+    decode(input: any): any;
+
+    /**
+     * Stringifies a given value. Converts any IFluidHandle to its stringified equivalent.
+     */
+    stringify(value: any, bind: IFluidHandle): string;
+
+    /**
+     * Parses the given JSON input string and returns the JavaScript object defined by it. Any Fluid
+     * handles will be realized as part of the parse
+     */
+    parse(value: string): any;
+}
+
+/**
+ * Data Store serializer implementation
+ */
+export class FluidSerializer implements IFluidSerializer {
+    private readonly root: IFluidHandleContext;
+
+    public constructor(
+        private readonly context: IFluidHandleContext,
+        // To be called whenever a handle is parsed by this serializer.
+        private readonly handleParsedCb: (handle: IFluidHandle) => void,
+    ) {
+        this.root = this.context;
+        while (this.root.routeContext !== undefined) {
+            this.root = this.root.routeContext;
+        }
+    }
+
+    public get IFluidSerializer() { return this; }
+
+    /**
+     * Given a mostly-jsonable object tree that may have handle objects embedded within, will return a
+     * fully-jsonable object tree where any embedded IFluidHandles have been replaced with a serializable form.
+     *
+     * The original `input` object is not mutated.  This method will shallowly clone all objects in the path from
+     * the root to any replaced handles.  (If no handles are found, returns the original object.)
+     *
+     * Any unbound handles encountered are bound to the provided IFluidHandle.
+     */
+     public encode(
+        input: any,
+        bind: IFluidHandle,
+    ) {
+        // If the given 'input' cannot contain handles, return it immediately.  Otherwise,
+        // return the result of 'recursivelyReplace()'.
+        // eslint-disable-next-line @typescript-eslint/strict-boolean-expressions
+        return !!input && typeof input === "object"
+            ? this.recursivelyReplace(input, this.encodeValue, bind)
+            : input;
+    }
+
+    /**
+     * Given a fully-jsonable object tree that may have encoded handle objects embedded within, will return an
+     * equivalent object tree where any encoded IFluidHandles have been replaced with their decoded form.
+     *
+     * The original `input` object is not mutated.  This method will shallowly clone all objects in the path from
+     * the root to any replaced handles.  (If no handles are found, returns the original object.)
+     *
+     * The decoded handles are implicitly bound to the handle context of this serializer.
+     */
+     public decode(input: any) {
+        // If the given 'input' cannot contain handles, return it immediately.  Otherwise,
+        // return the result of 'recursivelyReplace()'.
+        // eslint-disable-next-line @typescript-eslint/strict-boolean-expressions
+        return !!input && typeof input === "object"
+            ? this.recursivelyReplace(input, this.decodeValue)
+            : input;
+    }
+
+    public stringify(input: any, bind: IFluidHandle) {
+        return JSON.stringify(input, (key, value) => this.encodeValue(value, bind));
+    }
+
+    // Parses the serialized data - context must match the context with which the JSON was stringified
+    public parse(input: string) {
+        return JSON.parse(input, (key, value) => this.decodeValue(value));
+    }
+
+    // If the given 'value' is an IFluidHandle, returns the encoded IFluidHandle.
+    // Otherwise returns the original 'value'.  Used by 'encode()' and 'stringify()'.
+    private readonly encodeValue = (value: any, bind: IFluidHandle) => {
+        // Detect if 'value' is an IFluidHandle.
+        const handle = value?.IFluidHandle;
+
+        // If 'value' is an IFluidHandle return its encoded form.
+        return handle !== undefined
+            ? this.serializeHandle(handle, bind)
+            : value;
+    };
+
+    // If the given 'value' is an encoded IFluidHandle, returns the decoded IFluidHandle.
+    // Otherwise returns the original 'value'.  Used by 'decode()' and 'parse()'.
+    private readonly decodeValue = (value: any) => {
+        // If 'value' is a serialized IFluidHandle return the deserialized result.
+        if (isSerializedHandle(value)) {
+            // Old documents may have handles with relative path in their summaries. Convert these to absolute
+            // paths. This will ensure that future summaries will have absolute paths for these handles.
+            const absolutePath = value.url.startsWith("/")
+                ? value.url
+                : generateHandleContextPath(value.url, this.context);
+
+            const parsedHandle = new RemoteFluidObjectHandle(absolutePath, this.root);
+            this.handleParsedCb(parsedHandle);
+            return parsedHandle;
+        } else {
+            return value;
+        }
+    };
+
+    // Invoked for non-null objects to recursively replace references to IFluidHandles.
+    // Clones as-needed to avoid mutating the `input` object.  If no IFluidHandes are present,
+    // returns the original `input`.
+    private recursivelyReplace(
+        input: any,
+        replacer: (input: any, context: any) => any,
+        context?: any,
+    ) {
+        // Note: Caller is responsible for ensuring that `input` is defined / non-null.
+        //       (Required for Object.keys() below.)
+
+        // Execute the `replace` on the current input.  Note that Caller is responsible for ensuring that `input`
+        // is a non-null object.
+        const maybeReplaced = replacer(input, context);
+
+        // If the replacer made a substitution there is no need to decscend further. IFluidHandles are always
+        // leaves in the object graph.
+        if (maybeReplaced !== input) {
+            return maybeReplaced;
+        }
+
+        // Otherwise descend into the object graph looking for IFluidHandle instances.
+        // eslint-disable-next-line @typescript-eslint/ban-types
+        let clone: object | undefined;
+        for (const key of Object.keys(input)) {
+            const value = input[key];
+            // eslint-disable-next-line @typescript-eslint/strict-boolean-expressions
+            if (!!value && typeof value === "object") {
+                // Note: Except for IFluidHandle, `input` must not contain circular references (as object must
+                //       be JSON serializable.)  Therefore, guarding against infinite recursion here would only
+                //       lead to a later error when attempting to stringify().
+                const replaced = this.recursivelyReplace(value, replacer, context);
+
+                // If the `replaced` object is different than the original `value` then the subgraph contained one
+                // or more handles.  If this happens, we need to return a clone of the `input` object where the
+                // current property is replaced by the `replaced` value.
+                if (replaced !== value) {
+                    // Lazily create a shallow clone of the `input` object if we haven't done so already.
+                    clone = clone ?? (Array.isArray(input)
+                        ? [...input]
+                        : { ...input });
+
+                    // Overwrite the current property `key` in the clone with the `replaced` value.
+                    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+                    clone![key] = replaced;
+                }
+            }
+        }
+        return clone ?? input;
+    }
+
+    protected serializeHandle(handle: IFluidHandle, bind: IFluidHandle) {
+        bind.bind(handle);
+        return {
+            type: "__fluid_handle__",
+            url: handle.absolutePath,
+        };
+    }
+}