@fluidframework/tree 2.0.0-dev-rc.1.0.0.224419

package/dist/codec/codec.d.ts

@@ -0,0 +1,214 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import { IsoBuffer } from "@fluid-internal/client-utils";
+import type { Static, TAnySchema, TSchema } from "@sinclair/typebox";
+import { JsonCompatibleReadOnly } from "../util";
+/**
+ * Translates decoded data to encoded data.
+ * @remarks Typically paired with an {@link IEncoder}.
+ */
+export interface IEncoder<TDecoded, TEncoded> {
+    /**
+     * Encodes `obj` into some encoded format.
+     */
+    encode(obj: TDecoded): TEncoded;
+}
+/**
+ * Translates encoded data to decoded data.
+ * @remarks Typically paired with an {@link IEncoder}.
+ */
+export interface IDecoder<TDecoded, TEncoded> {
+    /**
+     * Decodes `obj` from some encoded format.
+     */
+    decode(obj: TEncoded): TDecoded;
+}
+/**
+ * Validates data complies with some particular schema.
+ * Implementations are typically created by a {@link JsonValidator}.
+ * @internal
+ */
+export interface SchemaValidationFunction<Schema extends TSchema> {
+    /**
+     * @returns Whether the data matches a schema.
+     */
+    check(data: unknown): data is Static<Schema>;
+}
+/**
+ * JSON schema validator compliant with draft 6 schema. See https://json-schema.org.
+ * @internal
+ */
+export interface JsonValidator {
+    /**
+     * Compiles the provided JSON schema into a validator for that schema.
+     * @param schema - A valid draft 6 JSON schema
+     * @remarks IFluidHandles--which have circular property references--are used in various places in SharedTree's persisted
+     * format. Handles should only be contained in sections of data which are validated against the empty schema `{}`
+     * (see https://datatracker.ietf.org/doc/html/draft-wright-json-schema-01#section-4.4).
+     *
+     * Implementations of `JsonValidator` must therefore tolerate these values, despite the input not being valid JSON.
+     */
+    compile<Schema extends TSchema>(schema: Schema): SchemaValidationFunction<Schema>;
+}
+/**
+ * Options relating to handling of persisted data.
+ * @internal
+ */
+export interface ICodecOptions {
+    /**
+     * {@link JsonValidator} which SharedTree uses to validate persisted data it reads & writes
+     * matches the expected encoded format (i.e. the wire format for ops and summaries).
+     *
+     * See {@link noopValidator} and {@link typeboxValidator} for out-of-the-box implementations.
+     *
+     * This option is not "on-by-default" because JSON schema validation comes with a small but noticeable
+     * runtime performance cost, and popular schema validation libraries have relatively large bundle size.
+     *
+     * SharedTree users are still encouraged to use a non-trivial validator (i.e. not `noopValidator`)
+     * whenever reasonable: it gives better fail-fast behavior when unexpected encoded data is found,
+     * which reduces the risk of unrecoverable data corruption.
+     */
+    readonly jsonValidator: JsonValidator;
+}
+/**
+ * @remarks `TEncoded` should always be valid Json (i.e. not contain functions), but due to TypeScript's handling
+ * of index signatures and `JsonCompatibleReadOnly`'s index signature in the Json object case, specifying this as a
+ * type-system level constraint makes code that uses this interface more difficult to write.
+ *
+ * If provided, `TValidate` allows the input type passed to `decode` to be different than `TEncoded`.
+ * This is useful when, for example, the type being decoded is `unknown` and must be validated to be a `TEncoded` before being decoded to a `TDecoded`.
+ */
+export interface IJsonCodec<TDecoded, TEncoded = JsonCompatibleReadOnly, TValidate = TEncoded> extends IEncoder<TDecoded, TEncoded>, IDecoder<TDecoded, TValidate> {
+    encodedSchema?: TAnySchema;
+}
+/**
+ * TODO: properly integrate context
+ */
+export type IJsonCodecWithContext<TDecoded, TEncoded, TValidate, TContext> = (context: TContext) => IJsonCodec<TDecoded, TEncoded, TValidate>;
+/**
+ * @remarks TODO: We might consider using DataView or some kind of writer instead of IsoBuffer.
+ */
+export interface IBinaryCodec<TDecoded> extends IEncoder<TDecoded, IsoBuffer>, IDecoder<TDecoded, IsoBuffer> {
+}
+/**
+ * Contains knowledge of how to encode some in-memory type into JSON and binary formats,
+ * as well as how to decode those representations.
+ *
+ * @remarks Codecs are typically used in shared-tree to convert data into some persisted format.
+ * For this common use case, any format for encoding that was ever actually used needs to
+ * be supported for decoding in all future code versions.
+ *
+ * Using an {@link ICodecFamily} is the recommended strategy for managing this support, keeping in
+ * mind evolution of encodings over time.
+ */
+export interface IMultiFormatCodec<TDecoded, TJsonEncoded extends JsonCompatibleReadOnly = JsonCompatibleReadOnly, TJsonValidate = TJsonEncoded> {
+    json: IJsonCodec<TDecoded, TJsonEncoded, TJsonValidate>;
+    binary: IBinaryCodec<TDecoded>;
+    /** Ensures multi-format codecs cannot also be single-format codecs. */
+    encode?: never;
+    /** Ensures multi-format codecs cannot also be single-format codecs. */
+    decode?: never;
+}
+/**
+ * Represents a family of codecs that can be used to encode and decode data in different formats.
+ * The family is identified by a format version, which is typically used to select the codec to use.
+ *
+ * Separating codecs into families rather than having a single codec support multiple versions (i.e. currying
+ * the `formatVersion` parameter)
+ * allows avoiding some duplicate work at encode/decode time, since the vast majority of document usage will not
+ * involve mixed format versions.
+ */
+export interface ICodecFamily<TDecoded> {
+    /**
+     * @returns a codec that can be used to encode and decode data in the specified format.
+     * @throws - if the format version is not supported by this family.
+     * @remarks Implementations should typically emit telemetry (either indirectly by throwing a well-known error with
+     * logged properties or directly using some logger) when a format version is requested that is not supported.
+     * This ensures that applications can diagnose compatibility issues.
+     */
+    resolve(formatVersion: number): IMultiFormatCodec<TDecoded>;
+    /**
+     * @returns an iterable of all format versions supported by this family.
+     */
+    getSupportedFormats(): Iterable<number>;
+}
+/**
+ * Creates a codec family from a registry of codecs.
+ * Any codec that is not a {@link IMultiFormatCodec} will be wrapped with a default binary encoding.
+ */
+export declare function makeCodecFamily<TDecoded>(registry: Iterable<[
+    formatVersion: number,
+    codec: IMultiFormatCodec<TDecoded> | IJsonCodec<TDecoded>
+]>): ICodecFamily<TDecoded>;
+/**
+ * Constructs a {@link IMultiFormatCodec} from a `IJsonCodec` using a generic binary encoding that simply writes
+ * the json representation of the object to a buffer.
+ */
+export declare function withDefaultBinaryEncoding<TDecoded>(jsonCodec: IJsonCodec<TDecoded>): IMultiFormatCodec<TDecoded>;
+/**
+ * Ensures that the provided single or multi-format codec has a binary encoding.
+ * Adapts the json encoding using {@link withDefaultBinaryEncoding} if necessary.
+ */
+export declare function ensureBinaryEncoding<TDecoded>(codec: IMultiFormatCodec<TDecoded> | IJsonCodec<TDecoded>): IMultiFormatCodec<TDecoded>;
+/**
+ * Codec for objects which carry no information.
+ */
+export declare const unitCodec: IMultiFormatCodec<0>;
+/**
+ * Creates a json codec for objects which are just a json compatible value
+ * and can be serialized as-is.
+ *
+ * This type of encoding is only appropriate if the persisted type (which should be defined in a persisted format file)
+ * happens to be convenient for in-memory usage as well.
+ *
+ * @remarks Beware that this API can cause accidental extraneous data in the persisted format.
+ * Consider the following example:
+ * ```typescript
+ * interface MyPersistedType {
+ *     foo: string;
+ *     id: number;
+ * }
+ * const MyPersistedType = Type.Object({
+ *     foo: Type.String(),
+ *     id: Type.Number()
+ * });
+ *
+ * const codec = makeValueCodec<MyPersistedType>();
+ *
+ * // Later, in some other file...
+ * interface SomeInMemoryType extends MyPersistedType {
+ *     someOtherProperty: string;
+ * }
+ *
+ * const someInMemoryObject: SomeInMemoryType = {
+ *     foo:	"bar",
+ *     id: 0,
+ *     someOtherProperty: "this shouldn't be here and ends up in the persisted format"
+ * }
+ *
+ * const encoded = codec.encode(someInMemoryObject);
+ * ```
+ * This all typechecks and passes at runtime, but the persisted format will contain the extraneous
+ * `someOtherProperty` field.
+ * It's unlikely a real-life example would be this simple, but the principle is the same.
+ *
+ * This issue can be avoided by using JSON schema that doesn't accept additional properties:
+ *
+ * ```typescript
+ * const MyPersistedType = Type.Object({
+ *     foo: Type.String(),
+ *     id: Type.Number()
+ * }, {
+ *     additionalProperties: false
+ * });
+ * ```
+ */
+export declare function makeValueCodec<Schema extends TSchema>(schema: Schema, validator?: JsonValidator): IJsonCodec<Static<Schema>>;
+/**
+ * Wraps a codec with JSON schema validation for its encoded type.
+ * @returns An {@link IJsonCodec} which validates the data it encodes and decodes matches the provided schema.
+ */
+export declare function withSchemaValidation<TInMemoryFormat, EncodedSchema extends TSchema, TEncodedFormat = JsonCompatibleReadOnly, TValidate = TEncodedFormat>(schema: EncodedSchema, codec: IJsonCodec<TInMemoryFormat, TEncodedFormat, TValidate>, validator?: JsonValidator): IJsonCodec<TInMemoryFormat, TEncodedFormat, TValidate>;
+//# sourceMappingURL=codec.d.ts.map

package/dist/codec/codec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codec.d.ts","sourceRoot":"","sources":["../../src/codec/codec.ts"],"names":[],"mappings":"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"}

package/dist/codec/codec.js

@@ -0,0 +1,168 @@
+"use strict";
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withSchemaValidation = exports.makeValueCodec = exports.unitCodec = exports.ensureBinaryEncoding = exports.withDefaultBinaryEncoding = exports.makeCodecFamily = void 0;
+const client_utils_1 = require("@fluid-internal/client-utils");
+const core_utils_1 = require("@fluidframework/core-utils");
+const util_1 = require("../util");
+/**
+ * Creates a codec family from a registry of codecs.
+ * Any codec that is not a {@link IMultiFormatCodec} will be wrapped with a default binary encoding.
+ */
+function makeCodecFamily(registry) {
+    const codecs = new Map();
+    for (const [formatVersion, codec] of registry) {
+        if (codecs.has(formatVersion)) {
+            (0, util_1.fail)("Duplicate codecs specified.");
+        }
+        codecs.set(formatVersion, ensureBinaryEncoding(codec));
+    }
+    return {
+        resolve(formatVersion) {
+            const codec = codecs.get(formatVersion);
+            (0, core_utils_1.assert)(codec !== undefined, 0x5e6 /* Requested coded for unsupported format. */);
+            return codec;
+        },
+        getSupportedFormats() {
+            return codecs.keys();
+        },
+    };
+}
+exports.makeCodecFamily = makeCodecFamily;
+class DefaultBinaryCodec {
+    constructor(jsonCodec) {
+        this.jsonCodec = jsonCodec;
+    }
+    encode(change) {
+        const jsonable = this.jsonCodec.encode(change);
+        const json = JSON.stringify(jsonable);
+        return client_utils_1.IsoBuffer.from(json);
+    }
+    decode(change) {
+        const json = (0, client_utils_1.bufferToString)(change, "utf8");
+        const jsonable = JSON.parse(json);
+        return this.jsonCodec.decode(jsonable);
+    }
+}
+function isJsonCodec(codec) {
+    return typeof codec.encode === "function" && typeof codec.decode === "function";
+}
+/**
+ * Constructs a {@link IMultiFormatCodec} from a `IJsonCodec` using a generic binary encoding that simply writes
+ * the json representation of the object to a buffer.
+ */
+function withDefaultBinaryEncoding(jsonCodec) {
+    return {
+        json: jsonCodec,
+        binary: new DefaultBinaryCodec(jsonCodec),
+    };
+}
+exports.withDefaultBinaryEncoding = withDefaultBinaryEncoding;
+/**
+ * Ensures that the provided single or multi-format codec has a binary encoding.
+ * Adapts the json encoding using {@link withDefaultBinaryEncoding} if necessary.
+ */
+function ensureBinaryEncoding(codec) {
+    return isJsonCodec(codec) ? withDefaultBinaryEncoding(codec) : codec;
+}
+exports.ensureBinaryEncoding = ensureBinaryEncoding;
+/**
+ * Codec for objects which carry no information.
+ */
+exports.unitCodec = {
+    json: {
+        encode: () => 0,
+        decode: () => 0,
+    },
+    binary: {
+        encode: () => client_utils_1.IsoBuffer.from(""),
+        decode: () => 0,
+    },
+};
+/**
+ * Creates a json codec for objects which are just a json compatible value
+ * and can be serialized as-is.
+ *
+ * This type of encoding is only appropriate if the persisted type (which should be defined in a persisted format file)
+ * happens to be convenient for in-memory usage as well.
+ *
+ * @remarks Beware that this API can cause accidental extraneous data in the persisted format.
+ * Consider the following example:
+ * ```typescript
+ * interface MyPersistedType {
+ *     foo: string;
+ *     id: number;
+ * }
+ * const MyPersistedType = Type.Object({
+ *     foo: Type.String(),
+ *     id: Type.Number()
+ * });
+ *
+ * const codec = makeValueCodec<MyPersistedType>();
+ *
+ * // Later, in some other file...
+ * interface SomeInMemoryType extends MyPersistedType {
+ *     someOtherProperty: string;
+ * }
+ *
+ * const someInMemoryObject: SomeInMemoryType = {
+ *     foo:	"bar",
+ *     id: 0,
+ *     someOtherProperty: "this shouldn't be here and ends up in the persisted format"
+ * }
+ *
+ * const encoded = codec.encode(someInMemoryObject);
+ * ```
+ * This all typechecks and passes at runtime, but the persisted format will contain the extraneous
+ * `someOtherProperty` field.
+ * It's unlikely a real-life example would be this simple, but the principle is the same.
+ *
+ * This issue can be avoided by using JSON schema that doesn't accept additional properties:
+ *
+ * ```typescript
+ * const MyPersistedType = Type.Object({
+ *     foo: Type.String(),
+ *     id: Type.Number()
+ * }, {
+ *     additionalProperties: false
+ * });
+ * ```
+ */
+function makeValueCodec(schema, validator) {
+    return withSchemaValidation(schema, {
+        encode: (x) => x,
+        decode: (x) => x,
+    }, validator);
+}
+exports.makeValueCodec = makeValueCodec;
+/**
+ * Wraps a codec with JSON schema validation for its encoded type.
+ * @returns An {@link IJsonCodec} which validates the data it encodes and decodes matches the provided schema.
+ */
+function withSchemaValidation(schema, codec, validator) {
+    if (!validator) {
+        return codec;
+    }
+    const compiledFormat = validator.compile(schema);
+    return {
+        encode: (obj) => {
+            const encoded = codec.encode(obj);
+            if (!compiledFormat.check(encoded)) {
+                (0, util_1.fail)("Encoded schema should validate");
+            }
+            return encoded;
+        },
+        decode: (encoded) => {
+            if (!compiledFormat.check(encoded)) {
+                (0, util_1.fail)("Encoded schema should validate");
+            }
+            // TODO: would be nice to provide a more specific validate type to the inner codec than the outer one gets.
+            return codec.decode(encoded);
+        },
+    };
+}
+exports.withSchemaValidation = withSchemaValidation;
+//# sourceMappingURL=codec.js.map

package/dist/codec/codec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"codec.js","sourceRoot":"","sources":["../../src/codec/codec.ts"],"names":[],"mappings":"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","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport { bufferToString, IsoBuffer } from \"@fluid-internal/client-utils\";\nimport { assert } from \"@fluidframework/core-utils\";\nimport type { Static, TAnySchema, TSchema } from \"@sinclair/typebox\";\nimport { fail, JsonCompatibleReadOnly } from \"../util\";\n\n/**\n * Translates decoded data to encoded data.\n * @remarks Typically paired with an {@link IEncoder}.\n */\nexport interface IEncoder<TDecoded, TEncoded> {\n\t/**\n\t * Encodes `obj` into some encoded format.\n\t */\n\tencode(obj: TDecoded): TEncoded;\n}\n\n/**\n * Translates encoded data to decoded data.\n * @remarks Typically paired with an {@link IEncoder}.\n */\nexport interface IDecoder<TDecoded, TEncoded> {\n\t/**\n\t * Decodes `obj` from some encoded format.\n\t */\n\tdecode(obj: TEncoded): TDecoded;\n}\n\n/**\n * Validates data complies with some particular schema.\n * Implementations are typically created by a {@link JsonValidator}.\n * @internal\n */\nexport interface SchemaValidationFunction<Schema extends TSchema> {\n\t/**\n\t * @returns Whether the data matches a schema.\n\t */\n\tcheck(data: unknown): data is Static<Schema>;\n}\n\n/**\n * JSON schema validator compliant with draft 6 schema. See https://json-schema.org.\n * @internal\n */\nexport interface JsonValidator {\n\t/**\n\t * Compiles the provided JSON schema into a validator for that schema.\n\t * @param schema - A valid draft 6 JSON schema\n\t * @remarks IFluidHandles--which have circular property references--are used in various places in SharedTree's persisted\n\t * format. Handles should only be contained in sections of data which are validated against the empty schema `{}`\n\t * (see https://datatracker.ietf.org/doc/html/draft-wright-json-schema-01#section-4.4).\n\t *\n\t * Implementations of `JsonValidator` must therefore tolerate these values, despite the input not being valid JSON.\n\t */\n\tcompile<Schema extends TSchema>(schema: Schema): SchemaValidationFunction<Schema>;\n}\n\n/**\n * Options relating to handling of persisted data.\n * @internal\n */\nexport interface ICodecOptions {\n\t/**\n\t * {@link JsonValidator} which SharedTree uses to validate persisted data it reads & writes\n\t * matches the expected encoded format (i.e. the wire format for ops and summaries).\n\t *\n\t * See {@link noopValidator} and {@link typeboxValidator} for out-of-the-box implementations.\n\t *\n\t * This option is not \"on-by-default\" because JSON schema validation comes with a small but noticeable\n\t * runtime performance cost, and popular schema validation libraries have relatively large bundle size.\n\t *\n\t * SharedTree users are still encouraged to use a non-trivial validator (i.e. not `noopValidator`)\n\t * whenever reasonable: it gives better fail-fast behavior when unexpected encoded data is found,\n\t * which reduces the risk of unrecoverable data corruption.\n\t */\n\treadonly jsonValidator: JsonValidator;\n}\n\n/**\n * @remarks `TEncoded` should always be valid Json (i.e. not contain functions), but due to TypeScript's handling\n * of index signatures and `JsonCompatibleReadOnly`'s index signature in the Json object case, specifying this as a\n * type-system level constraint makes code that uses this interface more difficult to write.\n *\n * If provided, `TValidate` allows the input type passed to `decode` to be different than `TEncoded`.\n * This is useful when, for example, the type being decoded is `unknown` and must be validated to be a `TEncoded` before being decoded to a `TDecoded`.\n */\nexport interface IJsonCodec<TDecoded, TEncoded = JsonCompatibleReadOnly, TValidate = TEncoded>\n\textends IEncoder<TDecoded, TEncoded>,\n\t\tIDecoder<TDecoded, TValidate> {\n\tencodedSchema?: TAnySchema;\n}\n\n/**\n * TODO: properly integrate context\n */\nexport type IJsonCodecWithContext<TDecoded, TEncoded, TValidate, TContext> = (\n\tcontext: TContext,\n) => IJsonCodec<TDecoded, TEncoded, TValidate>;\n\n/**\n * @remarks TODO: We might consider using DataView or some kind of writer instead of IsoBuffer.\n */\nexport interface IBinaryCodec<TDecoded>\n\textends IEncoder<TDecoded, IsoBuffer>,\n\t\tIDecoder<TDecoded, IsoBuffer> {}\n\n/**\n * Contains knowledge of how to encode some in-memory type into JSON and binary formats,\n * as well as how to decode those representations.\n *\n * @remarks Codecs are typically used in shared-tree to convert data into some persisted format.\n * For this common use case, any format for encoding that was ever actually used needs to\n * be supported for decoding in all future code versions.\n *\n * Using an {@link ICodecFamily} is the recommended strategy for managing this support, keeping in\n * mind evolution of encodings over time.\n */\nexport interface IMultiFormatCodec<\n\tTDecoded,\n\tTJsonEncoded extends JsonCompatibleReadOnly = JsonCompatibleReadOnly,\n\tTJsonValidate = TJsonEncoded,\n> {\n\tjson: IJsonCodec<TDecoded, TJsonEncoded, TJsonValidate>;\n\tbinary: IBinaryCodec<TDecoded>;\n\n\t/** Ensures multi-format codecs cannot also be single-format codecs. */\n\tencode?: never;\n\t/** Ensures multi-format codecs cannot also be single-format codecs. */\n\tdecode?: never;\n}\n\n/**\n * Represents a family of codecs that can be used to encode and decode data in different formats.\n * The family is identified by a format version, which is typically used to select the codec to use.\n *\n * Separating codecs into families rather than having a single codec support multiple versions (i.e. currying\n * the `formatVersion` parameter)\n * allows avoiding some duplicate work at encode/decode time, since the vast majority of document usage will not\n * involve mixed format versions.\n */\nexport interface ICodecFamily<TDecoded> {\n\t/**\n\t * @returns a codec that can be used to encode and decode data in the specified format.\n\t * @throws - if the format version is not supported by this family.\n\t * @remarks Implementations should typically emit telemetry (either indirectly by throwing a well-known error with\n\t * logged properties or directly using some logger) when a format version is requested that is not supported.\n\t * This ensures that applications can diagnose compatibility issues.\n\t */\n\tresolve(formatVersion: number): IMultiFormatCodec<TDecoded>;\n\n\t/**\n\t * @returns an iterable of all format versions supported by this family.\n\t */\n\tgetSupportedFormats(): Iterable<number>;\n}\n\n/**\n * Creates a codec family from a registry of codecs.\n * Any codec that is not a {@link IMultiFormatCodec} will be wrapped with a default binary encoding.\n */\nexport function makeCodecFamily<TDecoded>(\n\tregistry: Iterable<\n\t\t[formatVersion: number, codec: IMultiFormatCodec<TDecoded> | IJsonCodec<TDecoded>]\n\t>,\n): ICodecFamily<TDecoded> {\n\tconst codecs: Map<number, IMultiFormatCodec<TDecoded>> = new Map();\n\tfor (const [formatVersion, codec] of registry) {\n\t\tif (codecs.has(formatVersion)) {\n\t\t\tfail(\"Duplicate codecs specified.\");\n\t\t}\n\t\tcodecs.set(formatVersion, ensureBinaryEncoding(codec));\n\t}\n\n\treturn {\n\t\tresolve(formatVersion: number) {\n\t\t\tconst codec = codecs.get(formatVersion);\n\t\t\tassert(codec !== undefined, 0x5e6 /* Requested coded for unsupported format. */);\n\t\t\treturn codec;\n\t\t},\n\t\tgetSupportedFormats() {\n\t\t\treturn codecs.keys();\n\t\t},\n\t};\n}\n\nclass DefaultBinaryCodec<TDecoded> implements IBinaryCodec<TDecoded> {\n\tpublic constructor(private readonly jsonCodec: IJsonCodec<TDecoded>) {}\n\n\tpublic encode(change: TDecoded): IsoBuffer {\n\t\tconst jsonable = this.jsonCodec.encode(change);\n\t\tconst json = JSON.stringify(jsonable);\n\t\treturn IsoBuffer.from(json);\n\t}\n\n\tpublic decode(change: IsoBuffer): TDecoded {\n\t\tconst json = bufferToString(change, \"utf8\");\n\t\tconst jsonable = JSON.parse(json);\n\t\treturn this.jsonCodec.decode(jsonable);\n\t}\n}\n\nfunction isJsonCodec<TDecoded>(\n\tcodec: IMultiFormatCodec<TDecoded> | IJsonCodec<TDecoded>,\n): codec is IJsonCodec<TDecoded> {\n\treturn typeof codec.encode === \"function\" && typeof codec.decode === \"function\";\n}\n\n/**\n * Constructs a {@link IMultiFormatCodec} from a `IJsonCodec` using a generic binary encoding that simply writes\n * the json representation of the object to a buffer.\n */\nexport function withDefaultBinaryEncoding<TDecoded>(\n\tjsonCodec: IJsonCodec<TDecoded>,\n): IMultiFormatCodec<TDecoded> {\n\treturn {\n\t\tjson: jsonCodec,\n\t\tbinary: new DefaultBinaryCodec(jsonCodec),\n\t};\n}\n\n/**\n * Ensures that the provided single or multi-format codec has a binary encoding.\n * Adapts the json encoding using {@link withDefaultBinaryEncoding} if necessary.\n */\nexport function ensureBinaryEncoding<TDecoded>(\n\tcodec: IMultiFormatCodec<TDecoded> | IJsonCodec<TDecoded>,\n): IMultiFormatCodec<TDecoded> {\n\treturn isJsonCodec(codec) ? withDefaultBinaryEncoding(codec) : codec;\n}\n\n/**\n * Codec for objects which carry no information.\n */\nexport const unitCodec: IMultiFormatCodec<0> = {\n\tjson: {\n\t\tencode: () => 0,\n\t\tdecode: () => 0,\n\t},\n\tbinary: {\n\t\tencode: () => IsoBuffer.from(\"\"),\n\t\tdecode: () => 0,\n\t},\n};\n\n/**\n * Creates a json codec for objects which are just a json compatible value\n * and can be serialized as-is.\n *\n * This type of encoding is only appropriate if the persisted type (which should be defined in a persisted format file)\n * happens to be convenient for in-memory usage as well.\n *\n * @remarks Beware that this API can cause accidental extraneous data in the persisted format.\n * Consider the following example:\n * ```typescript\n * interface MyPersistedType {\n *     foo: string;\n *     id: number;\n * }\n * const MyPersistedType = Type.Object({\n *     foo: Type.String(),\n *     id: Type.Number()\n * });\n *\n * const codec = makeValueCodec<MyPersistedType>();\n *\n * // Later, in some other file...\n * interface SomeInMemoryType extends MyPersistedType {\n *     someOtherProperty: string;\n * }\n *\n * const someInMemoryObject: SomeInMemoryType = {\n *     foo:\t\"bar\",\n *     id: 0,\n *     someOtherProperty: \"this shouldn't be here and ends up in the persisted format\"\n * }\n *\n * const encoded = codec.encode(someInMemoryObject);\n * ```\n * This all typechecks and passes at runtime, but the persisted format will contain the extraneous\n * `someOtherProperty` field.\n * It's unlikely a real-life example would be this simple, but the principle is the same.\n *\n * This issue can be avoided by using JSON schema that doesn't accept additional properties:\n *\n * ```typescript\n * const MyPersistedType = Type.Object({\n *     foo: Type.String(),\n *     id: Type.Number()\n * }, {\n *     additionalProperties: false\n * });\n * ```\n */\nexport function makeValueCodec<Schema extends TSchema>(\n\tschema: Schema,\n\tvalidator?: JsonValidator,\n): IJsonCodec<Static<Schema>> {\n\treturn withSchemaValidation(\n\t\tschema,\n\t\t{\n\t\t\tencode: (x: Static<Schema>) => x as unknown as JsonCompatibleReadOnly,\n\t\t\tdecode: (x: JsonCompatibleReadOnly) => x as unknown as Static<Schema>,\n\t\t},\n\t\tvalidator,\n\t);\n}\n\n/**\n * Wraps a codec with JSON schema validation for its encoded type.\n * @returns An {@link IJsonCodec} which validates the data it encodes and decodes matches the provided schema.\n */\nexport function withSchemaValidation<\n\tTInMemoryFormat,\n\tEncodedSchema extends TSchema,\n\tTEncodedFormat = JsonCompatibleReadOnly,\n\tTValidate = TEncodedFormat,\n>(\n\tschema: EncodedSchema,\n\tcodec: IJsonCodec<TInMemoryFormat, TEncodedFormat, TValidate>,\n\tvalidator?: JsonValidator,\n): IJsonCodec<TInMemoryFormat, TEncodedFormat, TValidate> {\n\tif (!validator) {\n\t\treturn codec;\n\t}\n\tconst compiledFormat = validator.compile(schema);\n\treturn {\n\t\tencode: (obj: TInMemoryFormat) => {\n\t\t\tconst encoded = codec.encode(obj);\n\t\t\tif (!compiledFormat.check(encoded)) {\n\t\t\t\tfail(\"Encoded schema should validate\");\n\t\t\t}\n\t\t\treturn encoded;\n\t\t},\n\t\tdecode: (encoded: TValidate) => {\n\t\t\tif (!compiledFormat.check(encoded)) {\n\t\t\t\tfail(\"Encoded schema should validate\");\n\t\t\t}\n\t\t\t// TODO: would be nice to provide a more specific validate type to the inner codec than the outer one gets.\n\t\t\treturn codec.decode(encoded);\n\t\t},\n\t};\n}\n"]}

package/dist/codec/discriminatedUnions.d.ts

@@ -0,0 +1,82 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import { ObjectOptions } from "@sinclair/typebox";
+import { _InlineTrick } from "../util";
+/**
+ * This module contains utilities for an encoding of a discriminated union that is efficient to validate using
+ * a JSON schema validator.
+ * See {@link DiscriminatedUnionDispatcher} for more information on this pattern.
+ */
+/**
+ * Options to configure a TypeBox schema as a discriminated union that is simple to validate data against.
+ *
+ * See {@link DiscriminatedUnionDispatcher} for more information on this pattern.
+ */
+export declare const unionOptions: ObjectOptions;
+/**
+ * Applies a function to the content of a [discriminated union](https://en.wikipedia.org/wiki/Tagged_union)
+ * where the function to apply depends on which value from the union it holds.
+ *
+ * This uses a rather non-standard encoding of the union where it is an object with many differently named optional fields,
+ * and which of the fields is populated determines the content type.
+ * This union encoding has the advantage that schema validation (such as that implemented by TypeBox) can validate the data efficiently.
+ * Other encodings--such as using an untagged union, then tagging the content types with a marker enum--require the schema validator to disambiguate the union members.
+ * Most JSON validator implementations fail to recognize the marker enum determines which component of the discriminated union the data must be,
+ * and end up checking against all candidate members of the union.
+ *
+ * @example
+ *
+ * The following union:
+ * ```typescript
+ * type Operation = Add | Subtract | Multiply | Divide;
+ *
+ * interface BinaryOperation {
+ *     readonly left: number;
+ *     readonly right: number;
+ * }
+ *
+ * interface Add extends BinaryOperation {
+ *     readonly type: "add";
+ * }
+ *
+ * interface Subtract extends BinaryOperation {
+ *     readonly type: "subtract";
+ * }
+ *
+ * interface Multiply extends BinaryOperation {
+ *     readonly type: "multiply";
+ * }
+ *
+ * interface Divide extends BinaryOperation {
+ *     readonly type: "divide";
+ * }
+ *
+ * ```
+ * Would be encoded using this strategy as:
+ * ```typescript
+ * interface EncodedBinaryOperation {
+ *     readonly left: number;
+ *     readonly right: number;
+ * }
+ *
+ * interface EncodedOperation {
+ *     add?: EncodedBinaryOperation;
+ *     subtract?: EncodedBinaryOperation;
+ *     multiply?: EncodedBinaryOperation;
+ *     divide?: EncodedBinaryOperation;
+ * }
+ * ```
+ * where only a single property of `EncodedOperation` is populated for a given encoded value.
+ */
+export declare class DiscriminatedUnionDispatcher<TUnion extends object, TArgs extends any[], TResult> {
+    private readonly library;
+    constructor(library: [
+        {
+            readonly [Property in keyof TUnion]-?: (value: Required<TUnion>[Property], ...args: TArgs) => TResult;
+        }
+    ][_InlineTrick]);
+    dispatch(union: TUnion, ...args: TArgs): TResult;
+}
+//# sourceMappingURL=discriminatedUnions.d.ts.map

package/dist/codec/discriminatedUnions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"discriminatedUnions.d.ts","sourceRoot":"","sources":["../../src/codec/discriminatedUnions.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAElD,OAAO,EAAE,YAAY,EAAqB,MAAM,SAAS,CAAC;AAE1D;;;;GAIG;AAEH;;;;GAIG;AACH,eAAO,MAAM,YAAY,EAAE,aAI1B,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AACH,qBAAa,4BAA4B,CAAC,MAAM,SAAS,MAAM,EAAE,KAAK,SAAS,GAAG,EAAE,EAAE,OAAO;IAC5F,OAAO,CAAC,QAAQ,CAAC,OAAO,CAGtB;gBAGD,OAAO,EAAE;QACR;YACC,QAAQ,EAAE,QAAQ,IAAI,MAAM,MAAM,CAAC,CAAC,GAAG,CACtC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC,QAAQ,CAAC,EACjC,GAAG,IAAI,EAAE,KAAK,KACV,OAAO;SACZ;KACD,CAAC,YAAY,CAAC;IAOT,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,KAAK,GAAG,OAAO;CAYvD"}

package/dist/codec/discriminatedUnions.js

@@ -0,0 +1,91 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DiscriminatedUnionDispatcher = exports.unionOptions = void 0;
+const core_utils_1 = require("@fluidframework/core-utils");
+const util_1 = require("../util");
+/**
+ * This module contains utilities for an encoding of a discriminated union that is efficient to validate using
+ * a JSON schema validator.
+ * See {@link DiscriminatedUnionDispatcher} for more information on this pattern.
+ */
+/**
+ * Options to configure a TypeBox schema as a discriminated union that is simple to validate data against.
+ *
+ * See {@link DiscriminatedUnionDispatcher} for more information on this pattern.
+ */
+exports.unionOptions = {
+    additionalProperties: false,
+    minProperties: 1,
+    maxProperties: 1,
+};
+/**
+ * Applies a function to the content of a [discriminated union](https://en.wikipedia.org/wiki/Tagged_union)
+ * where the function to apply depends on which value from the union it holds.
+ *
+ * This uses a rather non-standard encoding of the union where it is an object with many differently named optional fields,
+ * and which of the fields is populated determines the content type.
+ * This union encoding has the advantage that schema validation (such as that implemented by TypeBox) can validate the data efficiently.
+ * Other encodings--such as using an untagged union, then tagging the content types with a marker enum--require the schema validator to disambiguate the union members.
+ * Most JSON validator implementations fail to recognize the marker enum determines which component of the discriminated union the data must be,
+ * and end up checking against all candidate members of the union.
+ *
+ * @example
+ *
+ * The following union:
+ * ```typescript
+ * type Operation = Add | Subtract | Multiply | Divide;
+ *
+ * interface BinaryOperation {
+ *     readonly left: number;
+ *     readonly right: number;
+ * }
+ *
+ * interface Add extends BinaryOperation {
+ *     readonly type: "add";
+ * }
+ *
+ * interface Subtract extends BinaryOperation {
+ *     readonly type: "subtract";
+ * }
+ *
+ * interface Multiply extends BinaryOperation {
+ *     readonly type: "multiply";
+ * }
+ *
+ * interface Divide extends BinaryOperation {
+ *     readonly type: "divide";
+ * }
+ *
+ * ```
+ * Would be encoded using this strategy as:
+ * ```typescript
+ * interface EncodedBinaryOperation {
+ *     readonly left: number;
+ *     readonly right: number;
+ * }
+ *
+ * interface EncodedOperation {
+ *     add?: EncodedBinaryOperation;
+ *     subtract?: EncodedBinaryOperation;
+ *     multiply?: EncodedBinaryOperation;
+ *     divide?: EncodedBinaryOperation;
+ * }
+ * ```
+ * where only a single property of `EncodedOperation` is populated for a given encoded value.
+ */
+class DiscriminatedUnionDispatcher {
+    constructor(library) {
+        this.library = (0, util_1.objectToMap)(library);
+    }
+    dispatch(union, ...args) {
+        const keys = Reflect.ownKeys(union);
+        (0, core_utils_1.assert)(keys.length === 1, 0x733 /* discriminated union type should have exactly one member */);
+        const key = keys[0];
+        const value = union[key];
+        const factory = this.library.get(key) ?? (0, util_1.fail)("missing function for union member");
+        const result = factory(value, ...args);
+        return result;
+    }
+}
+exports.DiscriminatedUnionDispatcher = DiscriminatedUnionDispatcher;
+//# sourceMappingURL=discriminatedUnions.js.map

package/dist/codec/discriminatedUnions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"discriminatedUnions.js","sourceRoot":"","sources":["../../src/codec/discriminatedUnions.ts"],"names":[],"mappings":";;;AAKA,2DAAoD;AACpD,kCAA0D;AAE1D;;;;GAIG;AAEH;;;;GAIG;AACU,QAAA,YAAY,GAAkB;IAC1C,oBAAoB,EAAE,KAAK;IAC3B,aAAa,EAAE,CAAC;IAChB,aAAa,EAAE,CAAC;CAChB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AACH,MAAa,4BAA4B;IAMxC,YACC,OAOe;QAEf,IAAI,CAAC,OAAO,GAAG,IAAA,kBAAW,EACzB,OAA4E,CAC5E,CAAC;IACH,CAAC;IAEM,QAAQ,CAAC,KAAa,EAAE,GAAG,IAAW;QAC5C,MAAM,IAAI,GAAG,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;QACpC,IAAA,mBAAM,EACL,IAAI,CAAC,MAAM,KAAK,CAAC,EACjB,KAAK,CAAC,6DAA6D,CACnE,CAAC;QACF,MAAM,GAAG,GAAiB,IAAI,CAAC,CAAC,CAAiB,CAAC;QAClD,MAAM,KAAK,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC;QACzB,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,IAAA,WAAI,EAAC,mCAAmC,CAAC,CAAC;QACnF,MAAM,MAAM,GAAG,OAAO,CAAC,KAAK,EAAE,GAAG,IAAI,CAAC,CAAC;QACvC,OAAO,MAAM,CAAC;IACf,CAAC;CACD;AAjCD,oEAiCC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\nimport { ObjectOptions } from \"@sinclair/typebox\";\nimport { assert } from \"@fluidframework/core-utils\";\nimport { _InlineTrick, fail, objectToMap } from \"../util\";\n\n/**\n * This module contains utilities for an encoding of a discriminated union that is efficient to validate using\n * a JSON schema validator.\n * See {@link DiscriminatedUnionDispatcher} for more information on this pattern.\n */\n\n/**\n * Options to configure a TypeBox schema as a discriminated union that is simple to validate data against.\n *\n * See {@link DiscriminatedUnionDispatcher} for more information on this pattern.\n */\nexport const unionOptions: ObjectOptions = {\n\tadditionalProperties: false,\n\tminProperties: 1,\n\tmaxProperties: 1,\n};\n\n/**\n * Applies a function to the content of a [discriminated union](https://en.wikipedia.org/wiki/Tagged_union)\n * where the function to apply depends on which value from the union it holds.\n *\n * This uses a rather non-standard encoding of the union where it is an object with many differently named optional fields,\n * and which of the fields is populated determines the content type.\n * This union encoding has the advantage that schema validation (such as that implemented by TypeBox) can validate the data efficiently.\n * Other encodings--such as using an untagged union, then tagging the content types with a marker enum--require the schema validator to disambiguate the union members.\n * Most JSON validator implementations fail to recognize the marker enum determines which component of the discriminated union the data must be,\n * and end up checking against all candidate members of the union.\n *\n * @example\n *\n * The following union:\n * ```typescript\n * type Operation = Add | Subtract | Multiply | Divide;\n *\n * interface BinaryOperation {\n *     readonly left: number;\n *     readonly right: number;\n * }\n *\n * interface Add extends BinaryOperation {\n *     readonly type: \"add\";\n * }\n *\n * interface Subtract extends BinaryOperation {\n *     readonly type: \"subtract\";\n * }\n *\n * interface Multiply extends BinaryOperation {\n *     readonly type: \"multiply\";\n * }\n *\n * interface Divide extends BinaryOperation {\n *     readonly type: \"divide\";\n * }\n *\n * ```\n * Would be encoded using this strategy as:\n * ```typescript\n * interface EncodedBinaryOperation {\n *     readonly left: number;\n *     readonly right: number;\n * }\n *\n * interface EncodedOperation {\n *     add?: EncodedBinaryOperation;\n *     subtract?: EncodedBinaryOperation;\n *     multiply?: EncodedBinaryOperation;\n *     divide?: EncodedBinaryOperation;\n * }\n * ```\n * where only a single property of `EncodedOperation` is populated for a given encoded value.\n */\nexport class DiscriminatedUnionDispatcher<TUnion extends object, TArgs extends any[], TResult> {\n\tprivate readonly library: ReadonlyMap<\n\t\tkeyof TUnion,\n\t\t(value: unknown, ...args: TArgs) => TResult\n\t>;\n\n\tpublic constructor(\n\t\tlibrary: [\n\t\t\t{\n\t\t\t\treadonly [Property in keyof TUnion]-?: (\n\t\t\t\t\tvalue: Required<TUnion>[Property],\n\t\t\t\t\t...args: TArgs\n\t\t\t\t) => TResult;\n\t\t\t},\n\t\t][_InlineTrick],\n\t) {\n\t\tthis.library = objectToMap(\n\t\t\tlibrary as Record<keyof TUnion, (value: unknown, ...args: TArgs) => TResult>,\n\t\t);\n\t}\n\n\tpublic dispatch(union: TUnion, ...args: TArgs): TResult {\n\t\tconst keys = Reflect.ownKeys(union);\n\t\tassert(\n\t\t\tkeys.length === 1,\n\t\t\t0x733 /* discriminated union type should have exactly one member */,\n\t\t);\n\t\tconst key: keyof TUnion = keys[0] as keyof TUnion;\n\t\tconst value = union[key];\n\t\tconst factory = this.library.get(key) ?? fail(\"missing function for union member\");\n\t\tconst result = factory(value, ...args);\n\t\treturn result;\n\t}\n}\n"]}

package/dist/codec/index.d.ts

@@ -0,0 +1,8 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+export { IBinaryCodec, ICodecFamily, ICodecOptions, IDecoder, IEncoder, IJsonCodec, IMultiFormatCodec, JsonValidator, makeCodecFamily, makeValueCodec, SchemaValidationFunction, unitCodec, withDefaultBinaryEncoding, withSchemaValidation, IJsonCodecWithContext, } from "./codec";
+export { DiscriminatedUnionDispatcher, unionOptions } from "./discriminatedUnions";
+export { noopValidator } from "./noopValidator";
+//# sourceMappingURL=index.d.ts.map

package/dist/codec/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/codec/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EACN,YAAY,EACZ,YAAY,EACZ,aAAa,EACb,QAAQ,EACR,QAAQ,EACR,UAAU,EACV,iBAAiB,EACjB,aAAa,EACb,eAAe,EACf,cAAc,EACd,wBAAwB,EACxB,SAAS,EACT,yBAAyB,EACzB,oBAAoB,EACpB,qBAAqB,GACrB,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,4BAA4B,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AACnF,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/codec/index.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.noopValidator = exports.unionOptions = exports.DiscriminatedUnionDispatcher = exports.withSchemaValidation = exports.withDefaultBinaryEncoding = exports.unitCodec = exports.makeValueCodec = exports.makeCodecFamily = void 0;
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+var codec_1 = require("./codec");
+Object.defineProperty(exports, "makeCodecFamily", { enumerable: true, get: function () { return codec_1.makeCodecFamily; } });
+Object.defineProperty(exports, "makeValueCodec", { enumerable: true, get: function () { return codec_1.makeValueCodec; } });
+Object.defineProperty(exports, "unitCodec", { enumerable: true, get: function () { return codec_1.unitCodec; } });
+Object.defineProperty(exports, "withDefaultBinaryEncoding", { enumerable: true, get: function () { return codec_1.withDefaultBinaryEncoding; } });
+Object.defineProperty(exports, "withSchemaValidation", { enumerable: true, get: function () { return codec_1.withSchemaValidation; } });
+var discriminatedUnions_1 = require("./discriminatedUnions");
+Object.defineProperty(exports, "DiscriminatedUnionDispatcher", { enumerable: true, get: function () { return discriminatedUnions_1.DiscriminatedUnionDispatcher; } });
+Object.defineProperty(exports, "unionOptions", { enumerable: true, get: function () { return discriminatedUnions_1.unionOptions; } });
+var noopValidator_1 = require("./noopValidator");
+Object.defineProperty(exports, "noopValidator", { enumerable: true, get: function () { return noopValidator_1.noopValidator; } });
+//# sourceMappingURL=index.js.map

package/dist/codec/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/codec/index.ts"],"names":[],"mappings":";;;AAAA;;;GAGG;AACH,iCAgBiB;AAPhB,wGAAA,eAAe,OAAA;AACf,uGAAA,cAAc,OAAA;AAEd,kGAAA,SAAS,OAAA;AACT,kHAAA,yBAAyB,OAAA;AACzB,6GAAA,oBAAoB,OAAA;AAGrB,6DAAmF;AAA1E,mIAAA,4BAA4B,OAAA;AAAE,mHAAA,YAAY,OAAA;AACnD,iDAAgD;AAAvC,8GAAA,aAAa,OAAA","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\nexport {\n\tIBinaryCodec,\n\tICodecFamily,\n\tICodecOptions,\n\tIDecoder,\n\tIEncoder,\n\tIJsonCodec,\n\tIMultiFormatCodec,\n\tJsonValidator,\n\tmakeCodecFamily,\n\tmakeValueCodec,\n\tSchemaValidationFunction,\n\tunitCodec,\n\twithDefaultBinaryEncoding,\n\twithSchemaValidation,\n\tIJsonCodecWithContext,\n} from \"./codec\";\nexport { DiscriminatedUnionDispatcher, unionOptions } from \"./discriminatedUnions\";\nexport { noopValidator } from \"./noopValidator\";\n"]}