@fluidframework/tree 2.32.0 → 2.33.0

package/src/shared-tree/sharedTree.ts

@@ -9,29 +9,16 @@ import type {
 	IFluidHandle,
 	IFluidLoadable,
 } from "@fluidframework/core-interfaces/internal";
+import type { IChannelStorageService } from "@fluidframework/datastore-definitions/internal";
 import type {
-	IChannelAttributes,
-	IFluidDataStoreRuntime,
-	IChannelStorageService,
-} from "@fluidframework/datastore-definitions/internal";
-import {
-	SharedObject,
-	type IChannelView,
-	type IFluidSerializer,
-	type ISharedObject,
+	IChannelView,
+	IFluidSerializer,
 } from "@fluidframework/shared-object-base/internal";
 import {
 	UsageError,
 	type ITelemetryLoggerExt,
 } from "@fluidframework/telemetry-utils/internal";
 import type { IIdCompressor } from "@fluidframework/id-compressor";
-import type {
-	ITelemetryContext,
-	IExperimentalIncrementalSummaryContext,
-	ISummaryTreeWithStats,
-	IRuntimeMessageCollection,
-} from "@fluidframework/runtime-definitions/internal";
-import type { ISequencedDocumentMessage } from "@fluidframework/driver-definitions/internal";
 
 import { type ICodecOptions, noopValidator } from "../codec/index.js";
 import {
@@ -103,7 +90,7 @@ import { SharedTreeChangeFamily } from "./sharedTreeChangeFamily.js";
 import type { SharedTreeChange } from "./sharedTreeChangeTypes.js";
 import type { SharedTreeEditBuilder } from "./sharedTreeEditBuilder.js";
 import { type TreeCheckout, type BranchableTree, createTreeCheckout } from "./treeCheckout.js";
-import { Breakable, breakingClass, throwIfBroken } from "../util/index.js";
+import { type Breakable, breakingClass, throwIfBroken } from "../util/index.js";
 
 /**
  * Copy of data from an {@link ITreePrivate} at some point in time.
@@ -157,13 +144,6 @@ export interface ITreePrivate extends ITreeInternal {
 	readonly kernel: SharedTreeKernel;
 }
 
-/**
- * {@link ITreePrivate} extended with ISharedObject.
- * @remarks
- * This is used when integration testing this package with the Fluid runtime as it exposes the APIs the runtime consumes to manipulate the tree.
- */
-export interface ISharedTree extends ISharedObject, ITreePrivate {}
-
 /**
  * Has an entry for each codec which writes an explicit version into its data.
  *
@@ -206,121 +186,13 @@ function getCodecVersions(formatVersion: number): ExplicitCodecVersions {
 	return versions;
 }
 
-/**
- * Shared object wrapping {@link SharedTreeKernel}.
- */
-export class SharedTree extends SharedObject implements ISharedTree {
-	private readonly breaker: Breakable = new Breakable("Shared Tree");
-
-	public readonly kernel: SharedTreeKernel;
-
-	public constructor(
-		id: string,
-		runtime: IFluidDataStoreRuntime,
-		attributes: IChannelAttributes,
-		optionsParam: SharedTreeOptionsInternal,
-		telemetryContextPrefix: string = "fluid_sharedTree_",
-	) {
-		super(id, runtime, attributes, telemetryContextPrefix);
-		if (runtime.idCompressor === undefined) {
-			throw new UsageError("IdCompressor must be enabled to use SharedTree");
-		}
-		this.kernel = new SharedTreeKernel(
-			this.breaker,
-			this,
-			this.serializer,
-			(content, localOpMetadata) => this.submitLocalMessage(content, localOpMetadata),
-			() => this.deltaManager.lastSequenceNumber,
-			this.logger,
-			runtime.idCompressor,
-			optionsParam,
-		);
-	}
-
-	public summarizeCore(
-		serializer: IFluidSerializer,
-		telemetryContext?: ITelemetryContext,
-		incrementalSummaryContext?: IExperimentalIncrementalSummaryContext,
-	): ISummaryTreeWithStats {
-		return this.kernel.summarizeCore(serializer, telemetryContext, incrementalSummaryContext);
-	}
-
-	protected processCore(
-		message: ISequencedDocumentMessage,
-		local: boolean,
-		localOpMetadata: unknown,
-	): void {
-		fail(0xb75 /* processCore should not be called on SharedTree */);
-	}
-
-	protected override processMessagesCore(messagesCollection: IRuntimeMessageCollection): void {
-		this.kernel.processMessagesCore(messagesCollection);
-	}
-
-	protected onDisconnect(): void {
-		this.kernel.onDisconnect();
-	}
-
-	public exportVerbose(): VerboseTree | undefined {
-		return this.kernel.exportVerbose();
-	}
-
-	public exportSimpleSchema(): SimpleTreeSchema {
-		return this.kernel.exportSimpleSchema();
-	}
-
-	public contentSnapshot(): SharedTreeContentSnapshot {
-		return this.kernel.contentSnapshot();
-	}
-
-	// For the new TreeViewAlpha API
-	public viewWith<TRoot extends ImplicitFieldSchema | UnsafeUnknownSchema>(
-		config: TreeViewConfiguration<ReadSchema<TRoot>>,
-	): SchematizingSimpleTreeView<TRoot> & TreeView<ReadSchema<TRoot>>;
-
-	// For the old TreeView API
-	public viewWith<TRoot extends ImplicitFieldSchema>(
-		config: TreeViewConfiguration<TRoot>,
-	): SchematizingSimpleTreeView<TRoot> & TreeView<TRoot>;
-
-	public viewWith<TRoot extends ImplicitFieldSchema | UnsafeUnknownSchema>(
-		config: TreeViewConfiguration<ReadSchema<TRoot>>,
-	): SchematizingSimpleTreeView<TRoot> & TreeView<ReadSchema<TRoot>> {
-		return this.kernel.viewWith(config);
-	}
-
-	protected override async loadCore(services: IChannelStorageService): Promise<void> {
-		await this.kernel.loadCore(services);
-	}
-
-	protected override didAttach(): void {
-		this.kernel.didAttach();
-	}
-
-	protected override applyStashedOp(
-		...args: Parameters<
-			SharedTreeCore<SharedTreeEditBuilder, SharedTreeChange>["applyStashedOp"]
-		>
-	): void {
-		this.kernel.applyStashedOp(...args);
-	}
-
-	protected override reSubmitCore(
-		...args: Parameters<
-			SharedTreeCore<SharedTreeEditBuilder, SharedTreeChange>["reSubmitCore"]
-		>
-	): void {
-		this.kernel.reSubmitCore(...args);
-	}
-}
-
 /**
  * SharedTreeCore, configured with a good set of indexes and field kinds which will maintain compatibility over time.
  *
  * TODO: detail compatibility requirements.
  */
 @breakingClass
-class SharedTreeKernel extends SharedTreeCore<SharedTreeEditBuilder, SharedTreeChange> {
+export class SharedTreeKernel extends SharedTreeCore<SharedTreeEditBuilder, SharedTreeChange> {
 	public readonly checkout: TreeCheckout;
 	public get storedSchema(): TreeStoredSchemaRepository {
 		return this.checkout.storedSchema;

package/src/simple-tree/api/index.ts

@@ -31,6 +31,7 @@ export type {
 	ValidateRecursiveSchema,
 	FixRecursiveArraySchema,
 } from "./schemaFactoryRecursive.js";
+export { allowUnused } from "./schemaFactoryRecursive.js";
 export {
 	adaptEnum,
 	enumFromStrings,
@@ -59,31 +60,10 @@ export { getSimpleSchema } from "./getSimpleSchema.js";
 export { ViewSchema } from "./view.js";
 export type {
 	Unenforced,
-	FieldHasDefaultUnsafe,
-	ObjectFromSchemaRecordUnsafe,
-	TreeObjectNodeUnsafe,
-	TreeFieldFromImplicitFieldUnsafe,
-	TreeNodeFromImplicitAllowedTypesUnsafe,
-	FieldSchemaUnsafe,
-	InsertableTreeNodeFromImplicitAllowedTypesUnsafe,
-	TreeArrayNodeUnsafe,
-	TreeMapNodeUnsafe,
-	InsertableObjectFromSchemaRecordUnsafe,
-	InsertableTreeFieldFromImplicitFieldUnsafe,
-	InsertableTypedNodeUnsafe,
-	NodeBuilderDataUnsafe,
-	NodeFromSchemaUnsafe,
-	ReadonlyMapInlined,
-	TreeNodeSchemaClassUnsafe,
-	TreeNodeSchemaUnsafe,
-	AllowedTypesUnsafe,
-	ImplicitAllowedTypesUnsafe,
-	ImplicitFieldSchemaUnsafe,
-	TreeNodeSchemaNonClassUnsafe,
-	InsertableTreeNodeFromAllowedTypesUnsafe,
 	FieldSchemaAlphaUnsafe,
 	ArrayNodeCustomizableSchemaUnsafe,
 	MapNodeCustomizableSchemaUnsafe,
+	System_Unsafe,
 } from "./typesUnsafe.js";
 
 export {

package/src/simple-tree/api/schemaFactory.ts

@@ -55,25 +55,7 @@ import {
 	objectSchema,
 } from "../objectNode.js";
 import { type MapNodeInsertableData, type TreeMapNode, mapSchema } from "../mapNode.js";
-import type {
-	FieldSchemaUnsafe,
-	// Adding these unused imports makes the generated d.ts file produced by TypeScript stop breaking API-Extractor's rollup generation.
-	// Without this import, TypeScript generates inline `import("../..")` statements in the d.ts file,
-	// which API-Extractor leaves as is when generating the rollup, leaving them pointing at the wrong directory.
-	// API-Extractor issue: https://github.com/microsoft/rushstack/issues/4507
-	// eslint-disable-next-line unused-imports/no-unused-imports, @typescript-eslint/no-unused-vars
-	FieldHasDefaultUnsafe,
-	// eslint-disable-next-line unused-imports/no-unused-imports, @typescript-eslint/no-unused-vars
-	InsertableTreeFieldFromImplicitFieldUnsafe,
-	InsertableObjectFromSchemaRecordUnsafe,
-	InsertableTreeNodeFromImplicitAllowedTypesUnsafe,
-	TreeArrayNodeUnsafe,
-	TreeMapNodeUnsafe,
-	TreeObjectNodeUnsafe,
-	ImplicitAllowedTypesUnsafe,
-	ImplicitFieldSchemaUnsafe,
-	FieldSchemaAlphaUnsafe,
-} from "./typesUnsafe.js";
+import type { System_Unsafe, FieldSchemaAlphaUnsafe } from "./typesUnsafe.js";
 import { createFieldSchemaUnsafe } from "./schemaFactoryRecursive.js";
 import { isLazy } from "../flexList.js";
 
@@ -280,12 +262,12 @@ export interface SchemaStatics {
 	 * See {@link ValidateRecursiveSchema} for additional information about using recursive schema.
 	 */
 	readonly optionalRecursive: <
-		const T extends ImplicitAllowedTypesUnsafe,
+		const T extends System_Unsafe.ImplicitAllowedTypesUnsafe,
 		const TCustomMetadata = unknown,
 	>(
 		t: T,
 		props?: Omit<FieldProps<TCustomMetadata>, "defaultProvider">,
-	) => FieldSchemaUnsafe<FieldKind.Optional, T, TCustomMetadata>;
+	) => System_Unsafe.FieldSchemaUnsafe<FieldKind.Optional, T, TCustomMetadata>;
 
 	/**
 	 * {@link SchemaStatics.required} except tweaked to work better for recursive types.
@@ -295,12 +277,12 @@ export interface SchemaStatics {
 	 * See {@link ValidateRecursiveSchema} for additional information about using recursive schema.
 	 */
 	readonly requiredRecursive: <
-		const T extends ImplicitAllowedTypesUnsafe,
+		const T extends System_Unsafe.ImplicitAllowedTypesUnsafe,
 		const TCustomMetadata = unknown,
 	>(
 		t: T,
 		props?: Omit<FieldProps<TCustomMetadata>, "defaultProvider">,
-	) => FieldSchemaUnsafe<FieldKind.Required, T, TCustomMetadata>;
+	) => System_Unsafe.FieldSchemaUnsafe<FieldKind.Required, T, TCustomMetadata>;
 }
 
 const defaultOptionalProvider: DefaultProvider = getDefaultProvider(() => {
@@ -339,7 +321,7 @@ export const schemaStaticsBase = {
 	},
 
 	optionalRecursive: <
-		const T extends ImplicitAllowedTypesUnsafe,
+		const T extends System_Unsafe.ImplicitAllowedTypesUnsafe,
 		const TCustomMetadata = unknown,
 	>(
 		t: T,
@@ -352,7 +334,7 @@ export const schemaStaticsBase = {
 	},
 
 	requiredRecursive: <
-		const T extends ImplicitAllowedTypesUnsafe,
+		const T extends System_Unsafe.ImplicitAllowedTypesUnsafe,
 		const TCustomMetadata = unknown,
 	>(
 		t: T,
@@ -963,24 +945,24 @@ export class SchemaFactory<
 	public static readonly requiredRecursive = schemaStaticsPublic.requiredRecursive;
 
 	/**
-	 * A special field which holds a unique identifier for an object node.
+	 * A special readonly field which holds an identifier string for an object node.
 	 * @remarks
-	 * The value of this field, a "node identifier", uniquely identifies a node among all other nodes in the tree.
+	 * The value of this field, a "node identifier", is a string which identifies a node (or nodes) among all nodes in the tree.
 	 * Node identifiers are strings, and can therefore be used as lookup keys in maps or written to a database.
-	 * When the node is constructed, the identifier field does not need to be populated.
-	 * The SharedTree will provide an identifier for the node automatically.
-	 * An identifier provided automatically by the SharedTree has the following properties:
-	 * - It is a UUID.
+	 * When the node is constructed, the identifier field does not need to be specified.
+	 * When an identifier is not provided, the SharedTree will generate an identifier for the node automatically.
+	 * The identifier generated by the SharedTree has the following properties:
+	 *
+	 * - It is a UUID which will not collide with other generated UUIDs.
 	 * - It is compressed to a space-efficient representation when stored in the document.
-	 * - A compressed form of the identifier can be accessed at runtime via the `Tree.shortId()` API.
-	 * - It will error if read (and will not be present in the object's iterable properties) before the node has been inserted into the tree.
+	 * - A compressed form of the identifier can be accessed at runtime via the {@link TreeNodeApi.shortId|Tree.shortId()} API.
+	 * - It will error if read (and will not be present in the object's iterable properties) before the node has been inserted into a tree.
 	 *
 	 * However, a user may alternatively supply their own string as the identifier if desired (for example, if importing identifiers from another system).
-	 * In that case, it is up to the user to ensure that the identifier is unique within the current tree - no other node should have the same identifier at the same time.
-	 * If the identifier is not unique, it may be read, but may cause libraries or features which operate over node identifiers to misbehave.
+	 * In that case, if the user requires it to be unique, it is up to them to ensure uniqueness.
 	 * User-supplied identifiers may be read immediately, even before insertion into the tree.
 	 *
-	 * A node may have more than one identifier field (though note that this precludes the use of the `Tree.shortId()` API).
+	 * A node may have more than one identifier field (though note that this precludes the use of the {@link TreeNodeApi.shortId|Tree.shortId()} API).
 	 */
 	public get identifier(): FieldSchema<FieldKind.Identifier, typeof this.string> {
 		const defaultIdentifierProvider: DefaultProvider = getDefaultProvider(
@@ -1008,15 +990,15 @@ export class SchemaFactory<
 	 */
 	public objectRecursive<
 		const Name extends TName,
-		const T extends RestrictiveStringRecord<ImplicitFieldSchemaUnsafe>,
+		const T extends RestrictiveStringRecord<System_Unsafe.ImplicitFieldSchemaUnsafe>,
 	>(
 		name: Name,
 		t: T,
 	): TreeNodeSchemaClass<
 		ScopedSchemaName<TScope, Name>,
 		NodeKind.Object,
-		TreeObjectNodeUnsafe<T, ScopedSchemaName<TScope, Name>>,
-		object & InsertableObjectFromSchemaRecordUnsafe<T>,
+		System_Unsafe.TreeObjectNodeUnsafe<T, ScopedSchemaName<TScope, Name>>,
+		object & System_Unsafe.InsertableObjectFromSchemaRecordUnsafe<T>,
 		false,
 		T
 	> {
@@ -1027,8 +1009,8 @@ export class SchemaFactory<
 		) as unknown as TreeNodeSchemaClass<
 			TScopedName,
 			NodeKind.Object,
-			TreeObjectNodeUnsafe<T, TScopedName>,
-			object & InsertableObjectFromSchemaRecordUnsafe<T>,
+			System_Unsafe.TreeObjectNodeUnsafe<T, TScopedName>,
+			object & System_Unsafe.InsertableObjectFromSchemaRecordUnsafe<T>,
 			false,
 			T
 		>;
@@ -1042,10 +1024,10 @@ export class SchemaFactory<
 	 * See {@link ValidateRecursiveSchema} for additional information about using recursive schema.
 	 */
 	// eslint-disable-next-line @typescript-eslint/explicit-function-return-type
-	public arrayRecursive<const Name extends TName, const T extends ImplicitAllowedTypesUnsafe>(
-		name: Name,
-		allowedTypes: T,
-	) {
+	public arrayRecursive<
+		const Name extends TName,
+		const T extends System_Unsafe.ImplicitAllowedTypesUnsafe,
+	>(name: Name, allowedTypes: T) {
 		const RecursiveArray = this.namedArray(
 			name,
 			allowedTypes as T & ImplicitAllowedTypes,
@@ -1056,7 +1038,8 @@ export class SchemaFactory<
 		return RecursiveArray as TreeNodeSchemaClass<
 			ScopedSchemaName<TScope, Name>,
 			NodeKind.Array,
-			TreeArrayNodeUnsafe<T> & WithType<ScopedSchemaName<TScope, Name>, NodeKind.Array>,
+			System_Unsafe.TreeArrayNodeUnsafe<T> &
+				WithType<ScopedSchemaName<TScope, Name>, NodeKind.Array>,
 			{
 				/**
 				 * Iterator for the iterable of content for this node.
@@ -1069,7 +1052,9 @@ export class SchemaFactory<
 				 * If this workaround is kept, ideally this comment would be deduplicated with the other instance of it.
 				 * Unfortunately attempts to do this failed to avoid the compile error this was introduced to solve.
 				 */
-				[Symbol.iterator](): Iterator<InsertableTreeNodeFromImplicitAllowedTypesUnsafe<T>>;
+				[Symbol.iterator](): Iterator<
+					System_Unsafe.InsertableTreeNodeFromImplicitAllowedTypesUnsafe<T>
+				>;
 			},
 			false,
 			T,
@@ -1085,10 +1070,10 @@ export class SchemaFactory<
 	 * See {@link ValidateRecursiveSchema} for additional information about using recursive schema.
 	 */
 	// eslint-disable-next-line @typescript-eslint/explicit-function-return-type
-	public mapRecursive<Name extends TName, const T extends ImplicitAllowedTypesUnsafe>(
-		name: Name,
-		allowedTypes: T,
-	) {
+	public mapRecursive<
+		Name extends TName,
+		const T extends System_Unsafe.ImplicitAllowedTypesUnsafe,
+	>(name: Name, allowedTypes: T) {
 		const MapSchema = this.namedMap(
 			name,
 			allowedTypes as T & ImplicitAllowedTypes,
@@ -1101,7 +1086,8 @@ export class SchemaFactory<
 		return MapSchema as TreeNodeSchemaClass<
 			ScopedSchemaName<TScope, Name>,
 			NodeKind.Map,
-			TreeMapNodeUnsafe<T> & WithType<ScopedSchemaName<TScope, Name>, NodeKind.Map>,
+			System_Unsafe.TreeMapNodeUnsafe<T> &
+				WithType<ScopedSchemaName<TScope, Name>, NodeKind.Map>,
 			| {
 					/**
 					 * Iterator for the iterable of content for this node.
@@ -1115,7 +1101,7 @@ export class SchemaFactory<
 					 * Unfortunately attempts to do this failed to avoid the compile error this was introduced to solve.
 					 */
 					[Symbol.iterator](): Iterator<
-						[string, InsertableTreeNodeFromImplicitAllowedTypesUnsafe<T>]
+						[string, System_Unsafe.InsertableTreeNodeFromImplicitAllowedTypesUnsafe<T>]
 					>;
 			  }
 			// Ideally this would be
@@ -1123,7 +1109,7 @@ export class SchemaFactory<
 			// but doing so breaks recursive types.
 			// Instead we do a less nice version:
 			| {
-					readonly [P in string]: InsertableTreeNodeFromImplicitAllowedTypesUnsafe<T>;
+					readonly [P in string]: System_Unsafe.InsertableTreeNodeFromImplicitAllowedTypesUnsafe<T>;
 			  },
 			false,
 			T,

package/src/simple-tree/api/schemaFactoryAlpha.ts

@@ -3,16 +3,12 @@
  * Licensed under the MIT License.
  */
 
-import type {
-	ScopedSchemaName,
-	TreeObjectNodeUnsafe,
-	InsertableObjectFromSchemaRecordUnsafe,
-} from "../../internalTypes.js";
 import {
 	defaultSchemaFactoryObjectOptions,
 	SchemaFactory,
 	schemaStatics,
 	type SchemaFactoryObjectOptions,
+	type ScopedSchemaName,
 } from "./schemaFactory.js";
 import type {
 	ImplicitAllowedTypes,
@@ -23,10 +19,9 @@ import { objectSchema } from "../objectNode.js";
 import type { RestrictiveStringRecord } from "../../util/index.js";
 import type { NodeKind, TreeNodeSchemaClass } from "../core/index.js";
 import type {
-	ImplicitAllowedTypesUnsafe,
-	ImplicitFieldSchemaUnsafe,
 	ArrayNodeCustomizableSchemaUnsafe,
 	MapNodeCustomizableSchemaUnsafe,
+	System_Unsafe,
 } from "./typesUnsafe.js";
 import { mapSchema } from "../mapNode.js";
 import { arraySchema } from "../arrayNode.js";
@@ -97,7 +92,7 @@ export class SchemaFactoryAlpha<
 	 */
 	public override objectRecursive<
 		const Name extends TName,
-		const T extends RestrictiveStringRecord<ImplicitFieldSchemaUnsafe>,
+		const T extends RestrictiveStringRecord<System_Unsafe.ImplicitFieldSchemaUnsafe>,
 		const TCustomMetadata = unknown,
 	>(
 		name: Name,
@@ -106,8 +101,8 @@ export class SchemaFactoryAlpha<
 	): TreeNodeSchemaClass<
 		ScopedSchemaName<TScope, Name>,
 		NodeKind.Object,
-		TreeObjectNodeUnsafe<T, ScopedSchemaName<TScope, Name>>,
-		object & InsertableObjectFromSchemaRecordUnsafe<T>,
+		System_Unsafe.TreeObjectNodeUnsafe<T, ScopedSchemaName<TScope, Name>>,
+		object & System_Unsafe.InsertableObjectFromSchemaRecordUnsafe<T>,
 		false,
 		T,
 		never,
@@ -133,8 +128,8 @@ export class SchemaFactoryAlpha<
 		) as unknown as TreeNodeSchemaClass<
 			TScopedName,
 			NodeKind.Object,
-			TreeObjectNodeUnsafe<T, TScopedName>,
-			object & InsertableObjectFromSchemaRecordUnsafe<T>,
+			System_Unsafe.TreeObjectNodeUnsafe<T, TScopedName>,
+			object & System_Unsafe.InsertableObjectFromSchemaRecordUnsafe<T>,
 			false,
 			T,
 			never,
@@ -205,7 +200,7 @@ export class SchemaFactoryAlpha<
 	// eslint-disable-next-line @typescript-eslint/explicit-function-return-type
 	public override mapRecursive<
 		Name extends TName,
-		const T extends ImplicitAllowedTypesUnsafe,
+		const T extends System_Unsafe.ImplicitAllowedTypesUnsafe,
 		const TCustomMetadata = unknown,
 	>(name: Name, allowedTypes: T, options?: NodeSchemaOptions<TCustomMetadata>) {
 		return this.mapAlpha(
@@ -249,7 +244,7 @@ export class SchemaFactoryAlpha<
 	// eslint-disable-next-line @typescript-eslint/explicit-function-return-type
 	public override arrayRecursive<
 		const Name extends TName,
-		const T extends ImplicitAllowedTypesUnsafe,
+		const T extends System_Unsafe.ImplicitAllowedTypesUnsafe,
 		const TCustomMetadata = unknown,
 	>(name: Name, allowedTypes: T, options?: NodeSchemaOptions<TCustomMetadata>) {
 		return this.arrayAlpha(

package/src/simple-tree/api/schemaFactoryRecursive.ts

@@ -21,11 +21,11 @@ import type {
 	WithType,
 	TreeNode,
 } from "../core/index.js";
-import type { FieldSchemaAlphaUnsafe, ImplicitAllowedTypesUnsafe } from "./typesUnsafe.js";
+import type { FieldSchemaAlphaUnsafe, System_Unsafe } from "./typesUnsafe.js";
 
 export function createFieldSchemaUnsafe<
 	Kind extends FieldKind,
-	Types extends ImplicitAllowedTypesUnsafe,
+	Types extends System_Unsafe.ImplicitAllowedTypesUnsafe,
 	TCustomMetadata = unknown,
 >(
 	kind: Kind,
@@ -117,21 +117,28 @@ export function createFieldSchemaUnsafe<
  * Be very careful when declaring recursive schema.
  * Due to the removed extends clauses, subtle mistakes will compile just fine but cause strange errors when the schema is used.
  *
- * For example if the square brackets around the allowed types are forgotten:
+ * For example if a reference to a schema is malformed (in this case boxed inside an object):
  *
  * ```typescript
- * class Test extends sf.arrayRecursive("Test", () => Test) {} // Bad
+ * class Test extends sf.arrayRecursive("Test", [() => ({ Test })]) {} // Bad
  * ```
  * This schema will still compile, and some (but not all) usages of it may look like they work correctly while other usages will produce generally unintelligible compile errors.
  * This issue can be partially mitigated using {@link ValidateRecursiveSchema}:
  *
  * ```typescript
- * class Test extends sf.arrayRecursive("Test", () => Test) {} // Bad
+ * class Test extends sf.arrayRecursive("Test", [() => ({ Test })]) {} // Bad
  * {
  *     type _check = ValidateRecursiveSchema<typeof Test>; // Reports compile error due to invalid schema above.
  * }
  * ```
  *
+ * If your TypeScript configuration objects to this patten due to the unused local, you can use {@link allowUnused} to suppress the error:
+ *
+ * ```typescript
+ * class Test extends sf.arrayRecursive("Test", [() => ({ Test })]) {} // Bad
+ * allowUnused<ValidateRecursiveSchema<typeof Test>>(); // Reports compile error due to invalid schema above.
+ * ```
+ *
  * ## Object Schema
  *
  * When defining fields, if the fields is part of the recursive cycle, use the `*Recursive` {@link SchemaFactory} methods for defining the {@link FieldSchema}.
@@ -183,6 +190,19 @@ export type ValidateRecursiveSchema<
 	>,
 > = true;
 
+/**
+ * Does nothing with the provided value, but appears to use it to make unused locals warnings and errors go away.
+ *
+ * @remarks
+ * When TypeScript is configured with "noUnusedLocals", it will produce an error if a local variable is declared but never used.
+ * When you want to have this check enabled, but not follow it for a specific variable, you can pass the type or value to this function.
+ *
+ * Instead of using this, consider disabling "noUnusedLocals" in your tsconfig.json file, and enabling a similar check via a linter.
+ * This will allow you to still have the check, but have more control over it, for example being able to suppress it, or enable patterns like allowing unused locals with an "_" prefix.
+ * @alpha
+ */
+export function allowUnused<T>(t?: T): void {}
+
 /**
  * Workaround for fixing errors resulting from an issue with recursive ArrayNode schema exports.
  * @remarks

package/src/simple-tree/api/tree.ts

@@ -77,21 +77,8 @@ export interface ViewableTree {
 	 * Only one schematized view may exist for a given ITree at a time.
 	 * If creating a second, the first must be disposed before calling `viewWith` again.
 	 *
-	 *
-	 * TODO: Provide a way to make a generic view schema for any document.
+	 * @privateRemarks
 	 * TODO: Support adapters for handling out-of-schema data.
-	 *
-	 * Doing initialization here allows a small API that is hard to use incorrectly.
-	 * Other approaches tend to have easy-to-make mistakes.
-	 * For example, having a separate initialization function means apps can forget to call it, making an app that can only open existing documents,
-	 * or call it unconditionally leaving an app that can only create new documents.
-	 * It also would require the schema to be passed into separate places and could cause issues if they didn't match.
-	 * Since the initialization function couldn't return a typed tree, the type checking wouldn't help catch that.
-	 * Also, if an app manages to create a document, but the initialization fails to get persisted, an app that only calls the initialization function
-	 * on the create code-path (for example how a schematized factory might do it),
-	 * would leave the document in an unusable state which could not be repaired when it is reopened (by the same or other clients).
-	 * Additionally, once out of schema content adapters are properly supported (with lazy document updates),
-	 * this initialization could become just another out of schema content adapter and this initialization is no longer a special case.
 	 */
 	viewWith<TRoot extends ImplicitFieldSchema>(
 		config: TreeViewConfiguration<TRoot>,