Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Deprecate types in tree #23313

Merged
merged 10 commits into from
Jan 13, 2025
Merged

Deprecate types in tree #23313

Show file tree
Hide file tree
Changes from 7 commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
cbb3ba5
feedback
sonalideshpandemsft Dec 12, 2024
ba4ebed
feedback
sonalideshpandemsft Dec 12, 2024
530a6fa
feedback
sonalideshpandemsft Dec 16, 2024
27ec0d6
Merge remote-tracking branch 'origin' into deprecate-events-types
sonalideshpandemsft Dec 16, 2024
c6455be
Add tests
sonalideshpandemsft Dec 16, 2024
8dcfc0d
feedback
sonalideshpandemsft Jan 3, 2025
817046b
Merge remote-tracking branch 'origin' into deprecate-events-types
sonalideshpandemsft Jan 3, 2025
9552b7e
Merge remote-tracking branch 'origin' into deprecate-events-types
sonalideshpandemsft Jan 9, 2025
46e8ac8
move tests to import-testing
sonalideshpandemsft Jan 9, 2025
2738e00
add inheritdoc
sonalideshpandemsft Jan 9, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 17 additions & 0 deletions .changeset/ready-seas-ask.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
---
"@fluidframework/tree": minor
---
---
"section": deprecation
---

Deprecation Notice: Events Interfaces Migrated to `@fluidframework/core-interfaces`

The following interfaces and types are now deprecated in `@fluidframework/tree`. It is recommended to import them from either `@fluidframework/core-interfaces` or `fluid-framework`.

- Listeners
- IsListener
- Listenable
- Off

These deprecated interfaces are planned for removal from `@fluidframework/tree` package in Fluid Framework 3.0 release.
1 change: 1 addition & 0 deletions examples/apps/presence-tracker/package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -48,6 +48,7 @@
"@fluidframework/driver-definitions": "workspace:~",
"@fluidframework/fluid-static": "workspace:~",
"@fluidframework/runtime-utils": "workspace:~",
"@fluidframework/tree": "workspace:~",
"fluid-framework": "workspace:~",
"process": "^0.11.10"
},
Expand Down
135 changes: 135 additions & 0 deletions examples/apps/presence-tracker/tests/events.test.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,135 @@
/*!
* Copyright (c) Microsoft Corporation and contributors. All rights reserved.
* Licensed under the MIT License.
*/

/**
* The test cases below ensure that type can be successfully imported from all three packages — tree, core-interfaces, and fluid-framework and validate that the imports work as expected.
* The plan is to remove types {@link @fluidframework/tree#Listenable}, {@link @fluidframework/tree#IsListener}, {@link @fluidframework/tree#Listeners} and {@link @fluidframework/tree#Off}
* from `@fluidframework/tree` in Fluid Framework 3.0 and instead import them from `fluid-framework` or `@fluidframework/core-interfaces`,
*/

import { strict as assert } from "node:assert";

import { createEmitter } from "@fluid-internal/client-utils";
import type { Listenable as Listenable_Interfaces } from "@fluidframework/core-interfaces";
import type { Listenable as Listenable_Tree } from "@fluidframework/tree";
sonalideshpandemsft marked this conversation as resolved.
Show resolved Hide resolved
import type { Listenable as Listenable_Framework } from "fluid-framework";

describe("Test events type imports", () => {
it("Trigger loaded event using core-interfaces import", async () => {
const emitter = new MyCompositionClassInterfaces();
let count = 0;
emitter.on("loaded", () => {
count += 1;
});

emitter.triggerLoad();
assert.strictEqual(count, 1);
});

it("Trigger loaded event using tree import", async () => {
const emitter = new MyCompositionClassTree();
let count = 1;
emitter.on("loaded", () => {
count += 1;
});

emitter.triggerLoad();
assert.strictEqual(count, 2);
});

it("Trigger loaded event using fluid-framework import", async () => {
const emitter = new MyCompositionClassFramework();
let count = 2;
emitter.on("loaded", () => {
count += 1;
});

emitter.triggerLoad();
assert.strictEqual(count, 3);
});
});

/**
* A set of events with their handlers.
*/
interface MyEvents {
loaded: () => void;
computed: () => number;
}

/**
* Example of composing over {@link CustomEventEmitter}.
*/
export class MyCompositionClassTree implements Listenable_Tree<MyEvents> {
private readonly events = createEmitter<MyEvents>();

private load(): number[] {
this.events.emit("loaded");
const results: number[] = this.events.emitAndCollect("computed");
return results;
}

public triggerLoad(): void {
this.load();
}

public on<K extends keyof MyEvents>(eventName: K, listener: MyEvents[K]): () => void {
return this.events.on(eventName, listener);
}

public off<K extends keyof MyEvents>(eventName: K, listener: MyEvents[K]): void {
return this.events.off(eventName, listener);
}
}

/**
* Example of composing over {@link CustomEventEmitter}.
*/
export class MyCompositionClassFramework implements Listenable_Framework<MyEvents> {
private readonly events = createEmitter<MyEvents>();

private load(): number[] {
this.events.emit("loaded");
const results: number[] = this.events.emitAndCollect("computed");
return results;
}

public triggerLoad(): void {
this.load();
}

public on<K extends keyof MyEvents>(eventName: K, listener: MyEvents[K]): () => void {
return this.events.on(eventName, listener);
}

public off<K extends keyof MyEvents>(eventName: K, listener: MyEvents[K]): void {
return this.events.off(eventName, listener);
}
}

/**
* Example of composing over {@link CustomEventEmitter}.
*/
export class MyCompositionClassInterfaces implements Listenable_Interfaces<MyEvents> {
private readonly events = createEmitter<MyEvents>();

private load(): number[] {
this.events.emit("loaded");
const results: number[] = this.events.emitAndCollect("computed");
return results;
}

public triggerLoad(): void {
this.load();
}

public on<K extends keyof MyEvents>(eventName: K, listener: MyEvents[K]): () => void {
return this.events.on(eventName, listener);
}

public off<K extends keyof MyEvents>(eventName: K, listener: MyEvents[K]): void {
return this.events.off(eventName, listener);
}
}
18 changes: 11 additions & 7 deletions packages/dds/tree/api-report/tree.alpha.api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -329,7 +329,8 @@ declare namespace InternalTypes {
}
export { InternalTypes }

export { IsListener }
// @public @deprecated (undocumented)
export type IsListener<T> = IsListener_2<T>;

// @alpha
export type IsUnion<T, T2 = T> = T extends unknown ? [T2] extends [T] ? false : true : "error";
Expand Down Expand Up @@ -433,9 +434,11 @@ export interface JsonValidator {
// @public
export type LazyItem<Item = unknown> = Item | (() => Item);

export { Listenable }
// @public @deprecated (undocumented)
export type Listenable<T extends object> = Listenable_2<T>;

export { Listeners }
// @public @deprecated (undocumented)
export type Listeners<T extends object> = Listeners_2<T>;

// @public @sealed
export interface MakeNominal {
Expand Down Expand Up @@ -501,7 +504,8 @@ type ObjectFromSchemaRecordUnsafe<T extends Unenforced<RestrictiveStringRecord<I
-readonly [Property in keyof T]: TreeFieldFromImplicitFieldUnsafe<T[Property]>;
};

export { Off }
// @public @deprecated (undocumented)
export type Off = Off_2;

// @alpha
export interface ParseOptions<TCustom> {
Expand Down Expand Up @@ -802,7 +806,7 @@ export const TreeBeta: {
// @alpha @sealed
export interface TreeBranch extends IDisposable {
dispose(error?: Error): void;
readonly events: Listenable<TreeBranchEvents>;
readonly events: Listenable_2<TreeBranchEvents>;
fork(): TreeBranch;
hasRootSchema<TSchema extends ImplicitFieldSchema>(schema: TSchema): this is TreeViewAlpha<TSchema>;
merge(branch: TreeBranch, disposeMerged?: boolean): void;
Expand Down Expand Up @@ -963,7 +967,7 @@ export enum TreeStatus {
// @public @sealed
export interface TreeView<in out TSchema extends ImplicitFieldSchema> extends IDisposable {
readonly compatibility: SchemaCompatibilityStatus;
readonly events: Listenable<TreeViewEvents>;
readonly events: Listenable_2<TreeViewEvents>;
initialize(content: InsertableTreeFieldFromImplicitField<TSchema>): void;
get root(): TreeFieldFromImplicitField<TSchema>;
set root(newRoot: InsertableTreeFieldFromImplicitField<TSchema>);
Expand All @@ -974,7 +978,7 @@ export interface TreeView<in out TSchema extends ImplicitFieldSchema> extends ID
// @alpha @sealed
export interface TreeViewAlpha<in out TSchema extends ImplicitFieldSchema | UnsafeUnknownSchema> extends Omit<TreeView<ReadSchema<TSchema>>, "root" | "initialize">, TreeBranch {
// (undocumented)
readonly events: Listenable<TreeViewEvents & TreeBranchEvents>;
readonly events: Listenable_2<TreeViewEvents & TreeBranchEvents>;
// (undocumented)
fork(): ReturnType<TreeBranch["fork"]> & TreeViewAlpha<TSchema>;
// (undocumented)
Expand Down
14 changes: 9 additions & 5 deletions packages/dds/tree/api-report/tree.beta.api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -197,7 +197,8 @@ declare namespace InternalTypes {
}
export { InternalTypes }

export { IsListener }
// @public @deprecated (undocumented)
export type IsListener<T> = IsListener_2<T>;

// @public @sealed
export class IterableTreeArrayContent<T> implements Iterable<T> {
Expand All @@ -222,9 +223,11 @@ export interface ITreeViewConfiguration<TSchema extends ImplicitFieldSchema = Im
// @public
export type LazyItem<Item = unknown> = Item | (() => Item);

export { Listenable }
// @public @deprecated (undocumented)
export type Listenable<T extends object> = Listenable_2<T>;

export { Listeners }
// @public @deprecated (undocumented)
export type Listeners<T extends object> = Listeners_2<T>;

// @public @sealed
export interface MakeNominal {
Expand Down Expand Up @@ -287,7 +290,8 @@ type ObjectFromSchemaRecordUnsafe<T extends Unenforced<RestrictiveStringRecord<I
-readonly [Property in keyof T]: TreeFieldFromImplicitFieldUnsafe<T[Property]>;
};

export { Off }
// @public @deprecated (undocumented)
export type Off = Off_2;

// @public @sealed
export interface ReadonlyArrayNode<out T = TreeNode | TreeLeafValue> extends ReadonlyArray<T>, Awaited<TreeNode & WithType<string, NodeKind.Array>> {
Expand Down Expand Up @@ -577,7 +581,7 @@ export enum TreeStatus {
// @public @sealed
export interface TreeView<in out TSchema extends ImplicitFieldSchema> extends IDisposable {
readonly compatibility: SchemaCompatibilityStatus;
readonly events: Listenable<TreeViewEvents>;
readonly events: Listenable_2<TreeViewEvents>;
initialize(content: InsertableTreeFieldFromImplicitField<TSchema>): void;
get root(): TreeFieldFromImplicitField<TSchema>;
set root(newRoot: InsertableTreeFieldFromImplicitField<TSchema>);
Expand Down
14 changes: 9 additions & 5 deletions packages/dds/tree/api-report/tree.legacy.alpha.api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -197,7 +197,8 @@ declare namespace InternalTypes {
}
export { InternalTypes }

export { IsListener }
// @public @deprecated (undocumented)
export type IsListener<T> = IsListener_2<T>;

// @public @sealed
export class IterableTreeArrayContent<T> implements Iterable<T> {
Expand All @@ -222,9 +223,11 @@ export interface ITreeViewConfiguration<TSchema extends ImplicitFieldSchema = Im
// @public
export type LazyItem<Item = unknown> = Item | (() => Item);

export { Listenable }
// @public @deprecated (undocumented)
export type Listenable<T extends object> = Listenable_2<T>;

export { Listeners }
// @public @deprecated (undocumented)
export type Listeners<T extends object> = Listeners_2<T>;

// @public @sealed
export interface MakeNominal {
Expand Down Expand Up @@ -282,7 +285,8 @@ type ObjectFromSchemaRecordUnsafe<T extends Unenforced<RestrictiveStringRecord<I
-readonly [Property in keyof T]: TreeFieldFromImplicitFieldUnsafe<T[Property]>;
};

export { Off }
// @public @deprecated (undocumented)
export type Off = Off_2;

// @public @sealed
export interface ReadonlyArrayNode<out T = TreeNode | TreeLeafValue> extends ReadonlyArray<T>, Awaited<TreeNode & WithType<string, NodeKind.Array>> {
Expand Down Expand Up @@ -564,7 +568,7 @@ export enum TreeStatus {
// @public @sealed
export interface TreeView<in out TSchema extends ImplicitFieldSchema> extends IDisposable {
readonly compatibility: SchemaCompatibilityStatus;
readonly events: Listenable<TreeViewEvents>;
readonly events: Listenable_2<TreeViewEvents>;
initialize(content: InsertableTreeFieldFromImplicitField<TSchema>): void;
get root(): TreeFieldFromImplicitField<TSchema>;
set root(newRoot: InsertableTreeFieldFromImplicitField<TSchema>);
Expand Down
14 changes: 9 additions & 5 deletions packages/dds/tree/api-report/tree.legacy.public.api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -197,7 +197,8 @@ declare namespace InternalTypes {
}
export { InternalTypes }

export { IsListener }
// @public @deprecated (undocumented)
export type IsListener<T> = IsListener_2<T>;

// @public @sealed
export class IterableTreeArrayContent<T> implements Iterable<T> {
Expand All @@ -222,9 +223,11 @@ export interface ITreeViewConfiguration<TSchema extends ImplicitFieldSchema = Im
// @public
export type LazyItem<Item = unknown> = Item | (() => Item);

export { Listenable }
// @public @deprecated (undocumented)
export type Listenable<T extends object> = Listenable_2<T>;

export { Listeners }
// @public @deprecated (undocumented)
export type Listeners<T extends object> = Listeners_2<T>;

// @public @sealed
export interface MakeNominal {
Expand Down Expand Up @@ -282,7 +285,8 @@ type ObjectFromSchemaRecordUnsafe<T extends Unenforced<RestrictiveStringRecord<I
-readonly [Property in keyof T]: TreeFieldFromImplicitFieldUnsafe<T[Property]>;
};

export { Off }
// @public @deprecated (undocumented)
export type Off = Off_2;

// @public @sealed
export interface ReadonlyArrayNode<out T = TreeNode | TreeLeafValue> extends ReadonlyArray<T>, Awaited<TreeNode & WithType<string, NodeKind.Array>> {
Expand Down Expand Up @@ -561,7 +565,7 @@ export enum TreeStatus {
// @public @sealed
export interface TreeView<in out TSchema extends ImplicitFieldSchema> extends IDisposable {
readonly compatibility: SchemaCompatibilityStatus;
readonly events: Listenable<TreeViewEvents>;
readonly events: Listenable_2<TreeViewEvents>;
initialize(content: InsertableTreeFieldFromImplicitField<TSchema>): void;
get root(): TreeFieldFromImplicitField<TSchema>;
set root(newRoot: InsertableTreeFieldFromImplicitField<TSchema>);
Expand Down
14 changes: 9 additions & 5 deletions packages/dds/tree/api-report/tree.public.api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -197,7 +197,8 @@ declare namespace InternalTypes {
}
export { InternalTypes }

export { IsListener }
// @public @deprecated (undocumented)
export type IsListener<T> = IsListener_2<T>;

// @public @sealed
export class IterableTreeArrayContent<T> implements Iterable<T> {
Expand All @@ -222,9 +223,11 @@ export interface ITreeViewConfiguration<TSchema extends ImplicitFieldSchema = Im
// @public
export type LazyItem<Item = unknown> = Item | (() => Item);

export { Listenable }
// @public @deprecated (undocumented)
export type Listenable<T extends object> = Listenable_2<T>;

export { Listeners }
// @public @deprecated (undocumented)
export type Listeners<T extends object> = Listeners_2<T>;

// @public @sealed
export interface MakeNominal {
Expand Down Expand Up @@ -282,7 +285,8 @@ type ObjectFromSchemaRecordUnsafe<T extends Unenforced<RestrictiveStringRecord<I
-readonly [Property in keyof T]: TreeFieldFromImplicitFieldUnsafe<T[Property]>;
};

export { Off }
// @public @deprecated (undocumented)
export type Off = Off_2;

// @public @sealed
export interface ReadonlyArrayNode<out T = TreeNode | TreeLeafValue> extends ReadonlyArray<T>, Awaited<TreeNode & WithType<string, NodeKind.Array>> {
Expand Down Expand Up @@ -561,7 +565,7 @@ export enum TreeStatus {
// @public @sealed
export interface TreeView<in out TSchema extends ImplicitFieldSchema> extends IDisposable {
readonly compatibility: SchemaCompatibilityStatus;
readonly events: Listenable<TreeViewEvents>;
readonly events: Listenable_2<TreeViewEvents>;
initialize(content: InsertableTreeFieldFromImplicitField<TSchema>): void;
get root(): TreeFieldFromImplicitField<TSchema>;
set root(newRoot: InsertableTreeFieldFromImplicitField<TSchema>);
Expand Down
Loading
Loading