@fluidframework/tree 2.0.0-dev-rc.1.0.0.224419

package/src/shared-tree/sharedTreeChangeTypes.ts

@@ -0,0 +1,24 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { ModularChangeset, SchemaChange } from "../feature-libraries/";
+
+export type SharedTreeInnerChange =
+	| { readonly type: "data"; readonly innerChange: ModularChangeset }
+	| { readonly type: "schema"; readonly innerChange: SchemaChange };
+
+/**
+ * The change format for the SharedTree.
+ * Supports both data and schema changes which can be interleaved as a result of composition.
+ */
+export interface SharedTreeChange {
+	/**
+	 * The changes to apply.
+	 * @remarks while not expressable in TypeScript, these changes should never have two `ModularChangeset`s adjacent in the list.
+	 * This restriction exists because this change type should preserve the composition behavior of `ModularChangeFamily`, which
+	 * always composes runs of `ModularChangeset`s into a single `ModularChangeset`.
+	 */
+	readonly changes: readonly SharedTreeInnerChange[];
+}

package/src/shared-tree/sharedTreeEditBuilder.ts

@@ -0,0 +1,70 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { ChangeFamilyEditor, TreeStoredSchema } from "../core";
+import { DefaultEditBuilder, IDefaultEditBuilder, ModularChangeFamily } from "../feature-libraries";
+import { SharedTreeChange } from "./sharedTreeChangeTypes";
+
+/**
+ * Editor for schema changes.
+ * The only currently supported operation is to replace the stored schema.
+ * @internal
+ */
+export interface ISchemaEditor {
+	/**
+	 * Updates the stored schema.
+	 * @param oldSchema - The schema being overwritten.
+	 * @param newSchema - The new schema to apply.
+	 * @internal
+	 */
+	setStoredSchema(oldSchema: TreeStoredSchema, newSchema: TreeStoredSchema): void;
+}
+
+/**
+ * SharedTree editor for transactional tree data and schema changes.
+ * @internal
+ */
+export interface ISharedTreeEditor extends IDefaultEditBuilder {
+	/**
+	 * Editor for schema changes.
+	 * @internal
+	 */
+	schema: ISchemaEditor;
+}
+
+/**
+ * Implementation of {@link IDefaultEditBuilder} based on the default set of supported field kinds.
+ * @sealed
+ */
+export class SharedTreeEditBuilder
+	extends DefaultEditBuilder
+	implements ChangeFamilyEditor, ISharedTreeEditor
+{
+	public readonly schema: ISchemaEditor;
+
+	public constructor(
+		modularChangeFamily: ModularChangeFamily,
+		private readonly changeReceiver: (change: SharedTreeChange) => void,
+	) {
+		super(modularChangeFamily, (change) =>
+			changeReceiver({
+				changes: [{ type: "data", innerChange: change }],
+			}),
+		);
+
+		this.schema = {
+			setStoredSchema: (oldSchema, newSchema) => {
+				this.changeReceiver({
+					changes: [
+						{
+							type: "schema",
+							innerChange: { schema: { new: newSchema, old: oldSchema } },
+						},
+					],
+				});
+			},
+		};
+	}
+}

package/src/shared-tree/treeCheckout.ts

@@ -0,0 +1,451 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import { assert } from "@fluidframework/core-utils";
+import {
+	AnchorLocator,
+	IForestSubscription,
+	AnchorSetRootEvents,
+	Anchor,
+	AnchorNode,
+	AnchorSet,
+	IEditableForest,
+	TreeStoredSchemaRepository,
+	assertIsRevisionTag,
+	combineVisitors,
+	visitDelta,
+	DetachedFieldIndex,
+	makeDetachedFieldIndex,
+	Revertible,
+	ChangeFamily,
+	tagChange,
+	TreeStoredSchema,
+	TreeStoredSchemaSubscription,
+	JsonableTree,
+} from "../core";
+import { HasListeners, IEmitter, ISubscribable, createEmitter } from "../events";
+import { buildForest, intoDelta, jsonableTreeFromCursor } from "../feature-libraries";
+import { SharedTreeBranch, getChangeReplaceType } from "../shared-tree-core";
+import { TransactionResult, fail } from "../util";
+import { noopValidator } from "../codec";
+import { SharedTreeChange } from "./sharedTreeChangeTypes";
+import { SharedTreeChangeFamily } from "./sharedTreeChangeFamily";
+import { ISharedTreeEditor, SharedTreeEditBuilder } from "./sharedTreeEditBuilder";
+
+/**
+ * Events for {@link ITreeCheckout}.
+ * @beta
+ */
+export interface CheckoutEvents {
+	/**
+	 * A batch of changes has finished processing and the view is in a consistent state.
+	 * It is once again safe to access the EditableTree, Forest and AnchorSet.
+	 *
+	 * @remarks
+	 * This is mainly useful for knowing when to do followup work scheduled during events from Anchors.
+	 */
+	afterBatch(): void;
+
+	/**
+	 * A revertible change has been made to this view.
+	 * Applications which subscribe to this event are expected to revert or discard revertibles they acquire, if they so choose (failure to do so will leak memory).
+	 * The provided revertible is inherently bound to the view that raised the event, calling `revert` won't apply to forked views.
+	 *
+	 * @remarks
+	 * This event provides a {@link Revertible} object that can be used to revert the change.
+	 */
+	revertible(revertible: Revertible): void;
+}
+
+/**
+ * Provides a means for interacting with a SharedTree.
+ * This includes reading data from the tree and running transactions to mutate the tree.
+ * @remarks This interface should not have any implementations other than those provided by the SharedTree package libraries.
+ * @privateRemarks
+ * API for interacting with a {@link SharedTreeBranch}.
+ * Implementations of this interface must implement the {@link branchKey} property.
+ * @internal
+ */
+export interface ITreeCheckout extends AnchorLocator {
+	/**
+	 * Read and Write access for schema stored in the document.
+	 *
+	 * These APIs are temporary and will be replaced with different abstractions (View Schema based) in a different place later.
+	 *
+	 * TODO:
+	 * Editing of this should be moved into transactions with the rest of tree editing to they can be intermixed.
+	 * This will be done after the relations between views, branches and Indexes are figured out.
+	 *
+	 * TODO:
+	 * Public APIs for dealing with schema should be in terms of View Schema, and schema update policies.
+	 * The actual stored schema should be hidden (or ar least not be the most prominent way to interact with schema).
+	 *
+	 * TODO:
+	 * Something should ensure the document contents are always in schema.
+	 */
+	readonly storedSchema: TreeStoredSchemaSubscription;
+	/**
+	 * Current contents.
+	 * Updated by edits (local and remote).
+	 * Use `editor` to create a local edit.
+	 */
+	readonly forest: IForestSubscription;
+
+	/**
+	 * Used to edit the state of the tree. Edits will be immediately applied locally to the tree.
+	 * If there is no transaction currently ongoing, then the edits will be submitted to Fluid immediately as well.
+	 */
+	readonly editor: ISharedTreeEditor;
+
+	/**
+	 * A collection of functions for managing transactions.
+	 */
+	readonly transaction: ITransaction;
+
+	/**
+	 * Spawn a new view which is based off of the current state of this view.
+	 * Any mutations of the new view will not apply to this view until the new view is merged back into this view via `merge()`.
+	 */
+	fork(): ITreeCheckoutFork;
+
+	/**
+	 * Apply all the new changes on the given view to this view.
+	 * @param view - a view which was created by a call to `fork()`.
+	 * It is automatically disposed after the merge completes.
+	 * @remarks All ongoing transactions (if any) in `view` will be committed before the merge.
+	 */
+	merge(view: ITreeCheckoutFork): void;
+
+	/**
+	 * Apply all the new changes on the given view to this view.
+	 * @param view - a view which was created by a call to `fork()`.
+	 * @param disposeView - whether or not to dispose `view` after the merge completes.
+	 * @remarks All ongoing transactions (if any) in `view` will be committed before the merge.
+	 */
+	merge(view: ITreeCheckoutFork, disposeView: boolean): void;
+
+	/**
+	 * Rebase the given view onto this view.
+	 * @param view - a view which was created by a call to `fork()`. It is modified by this operation.
+	 */
+	rebase(view: ITreeCheckoutFork): void;
+
+	/**
+	 * Replaces all schema with the provided schema.
+	 * Can over-write preexisting schema, and removes unmentioned schema.
+	 */
+	updateSchema(newSchema: TreeStoredSchema): void;
+
+	/**
+	 * Events about this view.
+	 */
+	readonly events: ISubscribable<CheckoutEvents>;
+
+	/**
+	 * Events about the root of the tree in this view.
+	 */
+	readonly rootEvents: ISubscribable<AnchorSetRootEvents>;
+
+	/**
+	 * Returns a JsonableTree for each tree that was removed from (and not restored to) the document.
+	 * This list is guaranteed to contain all nodes that are recoverable through undo/redo on this checkout.
+	 * The list may also contain additional nodes.
+	 *
+	 * This is only intended for use in testing and exceptional code paths: it is not performant.
+	 */
+	getRemovedRoots(): [string | number | undefined, number, JsonableTree][];
+}
+
+/**
+ * Creates a {@link TreeCheckout}.
+ * @param args - an object containing optional components that will be used to build the view.
+ * Any components not provided will be created by default.
+ * @remarks This does not create a {@link SharedTree}, but rather a view with the minimal state
+ * and functionality required to implement {@link ITreeCheckout}.
+ */
+export function createTreeCheckout(args?: {
+	branch?: SharedTreeBranch<SharedTreeEditBuilder, SharedTreeChange>;
+	changeFamily?: ChangeFamily<SharedTreeEditBuilder, SharedTreeChange>;
+	schema?: TreeStoredSchemaRepository;
+	forest?: IEditableForest;
+	events?: ISubscribable<CheckoutEvents> &
+		IEmitter<CheckoutEvents> &
+		HasListeners<CheckoutEvents>;
+	removedRoots?: DetachedFieldIndex;
+}): TreeCheckout {
+	const forest = args?.forest ?? buildForest();
+	const changeFamily =
+		args?.changeFamily ?? new SharedTreeChangeFamily({ jsonValidator: noopValidator });
+	const branch =
+		args?.branch ??
+		new SharedTreeBranch(
+			{
+				change: changeFamily.rebaser.compose([]),
+				revision: assertIsRevisionTag("00000000-0000-4000-8000-000000000000"),
+			},
+			changeFamily,
+		);
+	const schema = args?.schema ?? new TreeStoredSchemaRepository();
+	const events = args?.events ?? createEmitter();
+
+	const transaction = new Transaction(branch);
+
+	return new TreeCheckout(
+		transaction,
+		branch,
+		changeFamily,
+		schema,
+		forest,
+		events,
+		args?.removedRoots,
+	);
+}
+
+/**
+ * A collection of functions for managing transactions.
+ * Transactions allow edits to be batched into atomic units.
+ * Edits made during a transaction will update the local state of the tree immediately, but will be squashed into a single edit when the transaction is committed.
+ * If the transaction is aborted, the local state will be reset to what it was before the transaction began.
+ * Transactions may nest, meaning that a transaction may be started while a transaction is already ongoing.
+ *
+ * To avoid updating observers of the view state with intermediate results during a transaction,
+ * use {@link ITreeCheckout#fork} and {@link ISharedTreeFork#merge}.
+ * @internal
+ */
+export interface ITransaction {
+	/**
+	 * Start a new transaction.
+	 * If a transaction is already in progress when this new transaction starts, then this transaction will be "nested" inside of it,
+	 * i.e. the outer transaction will still be in progress after this new transaction is committed or aborted.
+	 *
+	 * @remarks - Asynchronous transactions are not supported on the root checkout,
+	 * since it is always kept up-to-date with the latest remote edits and the results of this rebasing (which might invalidate
+	 * the transaction) is not visible to the application author.
+	 * Instead,
+	 *
+	 * 1. fork the root checkout
+	 * 2. run the transaction on the fork
+	 * 3. merge the fork back into the root checkout
+	 *
+	 * @privateRemarks - There is currently no enforcement that asynchronous transactions don't happen on the root checkout.
+	 * AB#6488 tracks adding some enforcement to make it more clear to application authors that this is not supported.
+	 */
+	start(): void;
+	/**
+	 * Close this transaction by squashing its edits and committing them as a single edit.
+	 * If this is the root checkout and there are no ongoing transactions remaining, the squashed edit will be submitted to Fluid.
+	 */
+	commit(): TransactionResult.Commit;
+	/**
+	 * Close this transaction and revert the state of the tree to what it was before this transaction began.
+	 */
+	abort(): TransactionResult.Abort;
+	/**
+	 * True if there is at least one transaction currently in progress on this view, otherwise false.
+	 */
+	inProgress(): boolean;
+}
+
+class Transaction implements ITransaction {
+	public constructor(
+		private readonly branch: SharedTreeBranch<SharedTreeEditBuilder, SharedTreeChange>,
+	) {}
+
+	public start(): void {
+		this.branch.startTransaction();
+		this.branch.editor.enterTransaction();
+	}
+	public commit(): TransactionResult.Commit {
+		this.branch.commitTransaction();
+		this.branch.editor.exitTransaction();
+		return TransactionResult.Commit;
+	}
+	public abort(): TransactionResult.Abort {
+		this.branch.abortTransaction();
+		this.branch.editor.exitTransaction();
+		return TransactionResult.Abort;
+	}
+	public inProgress(): boolean {
+		return this.branch.isTransacting();
+	}
+}
+
+/**
+ * Branch (like in a version control system) of SharedTree.
+ *
+ * {@link ITreeCheckout} that has forked off of the main trunk/branch.
+ * @internal
+ */
+export interface ITreeCheckoutFork extends ITreeCheckout {
+	/**
+	 * Rebase the changes that have been applied to this view over all the new changes in the given view.
+	 * @param view - Either the root view or a view that was created by a call to `fork()`. It is not modified by this operation.
+	 */
+	rebaseOnto(view: ITreeCheckout): void;
+}
+
+/**
+ * An implementation of {@link ITreeCheckoutFork}.
+ */
+export class TreeCheckout implements ITreeCheckoutFork {
+	public constructor(
+		public readonly transaction: ITransaction,
+		private readonly branch: SharedTreeBranch<SharedTreeEditBuilder, SharedTreeChange>,
+		private readonly changeFamily: ChangeFamily<SharedTreeEditBuilder, SharedTreeChange>,
+		public readonly storedSchema: TreeStoredSchemaRepository,
+		public readonly forest: IEditableForest,
+		public readonly events: ISubscribable<CheckoutEvents> &
+			IEmitter<CheckoutEvents> &
+			HasListeners<CheckoutEvents>,
+		private readonly removedRoots: DetachedFieldIndex = makeDetachedFieldIndex("repair"),
+	) {
+		// We subscribe to `beforeChange` rather than `afterChange` here because it's possible that the change is invalid WRT our forest.
+		// For example, a bug in the editor might produce a malformed change object and thus applying the change to the forest will throw an error.
+		// In such a case we will crash here, preventing the change from being added to the commit graph, and preventing `afterChange` from firing.
+		// One important consequence of this is that we will not submit the op containing the invalid change, since op submissions happens in response to `afterChange`.
+		branch.on("beforeChange", (event) => {
+			if (event.change !== undefined) {
+				// Conflicts due to schema will be empty and thus are not applied.
+				for (const change of event.change.change.changes) {
+					if (change.type === "data") {
+						const delta = intoDelta(
+							tagChange(change.innerChange, event.change.revision),
+						);
+						const anchorVisitor = this.forest.anchors.acquireVisitor();
+						const combinedVisitor = combineVisitors(
+							[this.forest.acquireVisitor(), anchorVisitor],
+							[anchorVisitor],
+						);
+						visitDelta(delta, combinedVisitor, this.removedRoots);
+						combinedVisitor.free();
+					} else if (change.type === "schema") {
+						if (change.innerChange.schema !== undefined) {
+							storedSchema.apply(change.innerChange.schema.new);
+						}
+					} else {
+						fail("Unknown Shared Tree change type.");
+					}
+				}
+				this.events.emit("afterBatch");
+			}
+			if (event.type === "replace" && getChangeReplaceType(event) === "transactionCommit") {
+				const transactionRevision = event.newCommits[0].revision;
+				for (const transactionStep of event.removedCommits) {
+					this.removedRoots.updateMajor(transactionStep.revision, transactionRevision);
+				}
+			}
+		});
+		branch.on("revertible", (revertible) => {
+			// if there are no listeners, discard the revertible to avoid memory leaks
+			if (!this.events.hasListeners("revertible")) {
+				revertible.discard();
+			} else {
+				this.events.emit("revertible", revertible);
+			}
+		});
+	}
+
+	public get rootEvents(): ISubscribable<AnchorSetRootEvents> {
+		return this.forest.anchors;
+	}
+
+	public get editor(): ISharedTreeEditor {
+		return this.branch.editor;
+	}
+
+	public locate(anchor: Anchor): AnchorNode | undefined {
+		return this.forest.anchors.locate(anchor);
+	}
+
+	public fork(): TreeCheckout {
+		const anchors = new AnchorSet();
+		const branch = this.branch.fork();
+		const storedSchema = this.storedSchema.clone();
+		const forest = this.forest.clone(storedSchema, anchors);
+		const transaction = new Transaction(branch);
+		return new TreeCheckout(
+			transaction,
+			branch,
+			this.changeFamily,
+			storedSchema,
+			forest,
+			createEmitter(),
+			this.removedRoots.clone(),
+		);
+	}
+
+	public rebase(view: TreeCheckout): void {
+		view.branch.rebaseOnto(this.branch);
+	}
+
+	public rebaseOnto(view: ITreeCheckout): void {
+		view.rebase(this);
+	}
+
+	public merge(view: TreeCheckout): void;
+	public merge(view: TreeCheckout, disposeView: boolean): void;
+	public merge(view: TreeCheckout, disposeView = true): void {
+		assert(
+			!this.transaction.inProgress() || disposeView,
+			0x710 /* A view that is merged into an in-progress transaction must be disposed */,
+		);
+		while (view.transaction.inProgress()) {
+			view.transaction.commit();
+		}
+		this.branch.merge(view.branch);
+		if (disposeView) {
+			view.dispose();
+		}
+	}
+
+	public updateSchema(newSchema: TreeStoredSchema): void {
+		this.editor.schema.setStoredSchema(this.storedSchema.clone(), newSchema);
+	}
+
+	/**
+	 * Dispose this view, freezing its state and allowing the SharedTree to release resources required by it.
+	 * Attempts to further mutate or dispose this view will error.
+	 */
+	public dispose(): void {
+		this.branch.dispose();
+	}
+
+	public getRemovedRoots(): [string | number | undefined, number, JsonableTree][] {
+		const trees: [string | number | undefined, number, JsonableTree][] = [];
+		const cursor = this.forest.allocateCursor();
+		for (const { id, root } of this.removedRoots.entries()) {
+			const parentField = this.removedRoots.toFieldKey(root);
+			this.forest.moveCursorToPath(
+				{ parent: undefined, parentField, parentIndex: 0 },
+				cursor,
+			);
+			const tree = jsonableTreeFromCursor(cursor);
+			if (tree !== undefined) {
+				trees.push([id.major, id.minor, tree]);
+			}
+		}
+		cursor.free();
+		return trees;
+	}
+}
+
+/**
+ * Run a synchronous transaction on the given shared tree view.
+ * This is a convenience helper around the {@link SharedTreeFork#transaction} APIs.
+ * @param view - the view on which to run the transaction
+ * @param transaction - the transaction function. This will be executed immediately. It is passed `view` as an argument for convenience.
+ * If this function returns an `Abort` result then the transaction will be aborted. Otherwise, it will be committed.
+ * @returns whether or not the transaction was committed or aborted
+ * @internal
+ */
+export function runSynchronous(
+	view: ITreeCheckout,
+	transaction: (view: ITreeCheckout) => TransactionResult | void,
+): TransactionResult {
+	view.transaction.start();
+	const result = transaction(view);
+	return result === TransactionResult.Abort
+		? view.transaction.abort()
+		: view.transaction.commit();
+}

package/src/shared-tree/treeView.ts

@@ -0,0 +1,107 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { FieldKey } from "../core";
+import {
+	TreeFieldSchema,
+	FlexTreeSchema,
+	FlexTreeTypedField,
+	FlexTreeContext,
+	NodeKeyManager,
+	getTreeContext,
+	Context,
+} from "../feature-libraries";
+import { IDisposable, disposeSymbol } from "../util";
+import { ITreeCheckoutFork, ITreeCheckout } from "./treeCheckout";
+
+/**
+ * An editable view of a (version control style) branch of a shared tree.
+ * @privateRemarks
+ * TODO:
+ * 1. Once ISharedTreeView is renamed this can become ISharedTreeView.
+ * 2. This object should be combined with or accessible from the TreeContext to allow easy access to thinks like branching.
+ * @internal
+ */
+export interface FlexTreeView<in out TRoot extends TreeFieldSchema> extends IDisposable {
+	/**
+	 * Context for controlling the EditableTree nodes produced from {@link FlexTreeView.editableTree}.
+	 *
+	 * @remarks
+	 * This is an owning reference: disposing of this view disposes its context.
+	 */
+	readonly context: FlexTreeContext;
+
+	/**
+	 * Access non-view schema specific aspects of of this branch.
+	 *
+	 * @remarks
+	 * This is a non-owning reference: disposing of this view does not impact the branch.
+	 */
+	readonly checkout: ITreeCheckout;
+
+	/**
+	 * Get a typed view of the tree content using the editable-tree-2 API.
+	 */
+	readonly editableTree: FlexTreeTypedField<TRoot>;
+
+	/**
+	 * Spawn a new view which is based off of the current state of this view.
+	 * Any mutations of the new view will not apply to this view until the new view is merged back into this view via `merge()`.
+	 */
+	fork(): ITreeViewFork<TRoot>;
+}
+
+/**
+ * Branch (like in a version control system) of SharedTree.
+ *
+ * {@link FlexTreeView} that has forked off of the main trunk/branch.
+ * @internal
+ */
+export interface ITreeViewFork<in out TRoot extends TreeFieldSchema> extends FlexTreeView<TRoot> {
+	readonly checkout: ITreeCheckoutFork;
+}
+
+/**
+ * Implementation of FlexTreeView wrapping a ITreeCheckout.
+ */
+export class CheckoutFlexTreeView<
+	in out TRoot extends TreeFieldSchema,
+	out TCheckout extends ITreeCheckout = ITreeCheckout,
+> implements FlexTreeView<TRoot>
+{
+	public readonly context: Context;
+	public readonly editableTree: FlexTreeTypedField<TRoot>;
+	public constructor(
+		public readonly checkout: TCheckout,
+		public readonly schema: FlexTreeSchema<TRoot>,
+		public readonly nodeKeyManager: NodeKeyManager,
+		public readonly nodeKeyFieldKey: FieldKey,
+		private readonly onDispose?: () => void,
+	) {
+		this.context = getTreeContext(
+			schema,
+			this.checkout.forest,
+			this.checkout.editor,
+			nodeKeyManager,
+			nodeKeyFieldKey,
+		);
+		this.editableTree = this.context.root as FlexTreeTypedField<TRoot>;
+	}
+
+	public [disposeSymbol](): void {
+		this.context[disposeSymbol]();
+		this.onDispose?.();
+	}
+
+	public fork(): CheckoutFlexTreeView<TRoot, ITreeCheckoutFork> {
+		const branch = this.checkout.fork();
+		return new CheckoutFlexTreeView(
+			branch,
+			this.schema,
+			this.nodeKeyManager,
+			this.nodeKeyFieldKey,
+		);
+	}
+}

package/src/shared-tree-core/README.md

@@ -0,0 +1,19 @@
+# shared-tree-core
+
+Provides a SharedObject for a tree which handles the collaboration window, and keeping indexes up to date.
+
+Can be parameterized over:
+
+-   a set of field kinds (includes operations for for these kinds)
+-   history handling policy (keep none, keep main, keep timeline, keep branches)
+-   indexes
+-   Rebaser
+
+When summarizing, indexes are given a chance to record their state.
+Storing the current tree state (ex: using a forest to accumulate changes) is treated like any other index,
+and this this module does not have to depend on forest,
+it just provides an index contract / interface which can be used for that purpose.
+
+# Status
+
+Implementation is working, but how indexes relate to branches needs more thought. More detail on this in the [package readme](../../README.md).