jens/flipper
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Split flipper-plugin package

Browse Source 
Summary:
flipper-server-companion depends on flipper-plugin. flipper-plugin includes dependencies that run only in a browser. Splitting flipper-plugin into core and browser packages helps to avoid including browser-only dependencies into flipper-server bundle.
As a result, bundle size could be cut in half. Subsequently, RSS usage drops as there is twice as less code to process for V8.

Note: it currently breaks external flipper-data-source package. It will be restored in subsequent diffs

Reviewed By: lblasa

Differential Revision: D38658285

fbshipit-source-id: 751b11fa9f3a2d938ce166687b8310ba8b059dee
This commit is contained in:
Andrey Goncharov
2022-09-15 10:02:19 -07:00
committed by Facebook GitHub Bot
parent 2090120cda
commit 97b8b8a1c4
86 changed files with 813 additions and 645 deletions
Download Patch File Download Diff File Expand all files Collapse all files

936
desktop/flipper-plugin-core/src/data-source/DataSource.tsx Normal file
View File

@@ -0,0 +1,936 @@
/**
* Copyright (c) Meta Platforms, Inc. and affiliates.
*
* This source code is licensed under the MIT license found in the
* LICENSE file in the root directory of this source tree.
*
* @format
*/
import sortedIndexBy from 'lodash/sortedIndexBy';
import sortedLastIndexBy from 'lodash/sortedLastIndexBy';
import property from 'lodash/property';
import lodashSort from 'lodash/sortBy';
// If the dataSource becomes to large, after how many records will we start to drop items?
const dropFactor = 0.1;
// what is the default maximum amount of records before we start shifting the data set?
const defaultLimit = 100 * 1000;
// if a shift on a sorted dataset exceeds this tresholds, we assume it is faster to re-sort the entire set,
// rather than search and remove the affected individual items
const shiftRebuildTreshold = 0.05;
const DEFAULT_VIEW_ID = '0';
type AppendEvent<T> = {
type: 'append';
entry: Entry<T>;
};
type UpdateEvent<T> = {
type: 'update';
entry: Entry<T>;
oldValue: T;
oldVisible: {
[viewId: string]: boolean;
};
index: number;
};
type RemoveEvent<T> = {
type: 'remove';
entry: Entry<T>;
index: number;
};
type ShiftEvent<T> = {
type: 'shift';
entries: Entry<T>[];
amount: number;
};
type DataEvent<T> =
| AppendEvent<T>
| UpdateEvent<T>
| RemoveEvent<T>
| ShiftEvent<T>;
type Entry<T> = {
value: T;
id: number; // insertion based
visible: {
[viewId: string]: boolean;
}; // matches current filter?
approxIndex: {
[viewId: string]: number;
}; // we could possible live at this index in the output. No guarantees.
};
type Primitive = number | string | boolean | null | undefined;
type OutputChange =
| {
type: 'shift';
index: number;
location: 'before' | 'in' | 'after'; // relative to current window
delta: number;
newCount: number;
}
| {
// an item, inside the current window, was changed
type: 'update';
index: number;
}
| {
// something big and awesome happened. Drop earlier updates to the floor and start again
// like: clear, filter or sorting change, etc
type: 'reset';
newCount: number;
};
export type DataSourceOptionKey<K extends PropertyKey> = {
/**
* If a key is set, the given field of the records is assumed to be unique,
* and it's value can be used to perform lookups and upserts.
*/
key?: K;
};
export type DataSourceOptions = {
/**
* The maximum amount of records that this DataSource will store.
* If the limit is exceeded, the oldest records will automatically be dropped to make place for the new ones
*/
limit?: number;
};
export function createDataSource<T, Key extends keyof T>(
initialSet: readonly T[],
options: DataSourceOptions & DataSourceOptionKey<Key>,
): DataSource<T, T[Key] extends string | number ? T[Key] : never>;
export function createDataSource<T>(
initialSet?: readonly T[],
options?: DataSourceOptions,
): DataSource<T, never>;
export function createDataSource<T, Key extends keyof T>(
initialSet: readonly T[] = [],
options?: DataSourceOptions & DataSourceOptionKey<Key>,
): DataSource<T, Key> {
const ds = new DataSource<T, Key>(options?.key);
if (options?.limit !== undefined) {
ds.limit = options.limit;
}
initialSet.forEach((value) => ds.append(value));
return ds as any;
}
export class DataSource<T extends any, KeyType = never> {
private nextId = 0;
private _records: Entry<T>[] = [];
private _recordsById: Map<KeyType, T> = new Map();
/**
* @readonly
*/
public keyAttribute: keyof T | undefined;
private idToIndex: Map<KeyType, number> = new Map();
// if we shift the window, we increase shiftOffset to correct idToIndex results, rather than remapping all values
private shiftOffset = 0;
/**
* The maximum amount of records this DataSource can have
*/
public limit = defaultLimit;
/**
* The default view on this data source. A view applies
* sorting, filtering and windowing to get more constrained output.
*
* Additional views can created through the fork method.
*/
public readonly view: DataSourceView<T, KeyType>;
public readonly additionalViews: {
[viewId: string]: DataSourceView<T, KeyType>;
};
constructor(keyAttribute: keyof T | undefined) {
this.keyAttribute = keyAttribute;
this.view = new DataSourceView<T, KeyType>(this, DEFAULT_VIEW_ID);
this.additionalViews = {};
}
public get size() {
return this._records.length;
}
/**
* Returns a defensive copy of the stored records.
* This is a O(n) operation! Prefer using .size and .get instead if only a subset is needed.
*/
public records(): readonly T[] {
return this._records.map(unwrap);
}
public get(index: number) {
return unwrap(this._records[index]);
}
public has(key: KeyType) {
this.assertKeySet();
return this._recordsById.has(key);
}
public getById(key: KeyType): T | undefined {
this.assertKeySet();
return this._recordsById.get(key);
}
public keys(): IterableIterator<KeyType> {
this.assertKeySet();
return this._recordsById.keys();
}
public entries(): IterableIterator<[KeyType, T]> {
this.assertKeySet();
return this._recordsById.entries();
}
public [Symbol.iterator](): IterableIterator<T> {
const self = this;
let offset = 0;
return {
next() {
offset++;
if (offset > self.size) {
return {done: true, value: undefined};
} else {
return {
value: self._records[offset - 1].value,
};
}
},
[Symbol.iterator]() {
return this;
},
};
}
/**
* Returns the index of a specific key in the *records* set.
* Returns -1 if the record wansn't found
*/
public getIndexOfKey(key: KeyType): number {
this.assertKeySet();
const stored = this.idToIndex.get(key);
return stored === undefined ? -1 : stored + this.shiftOffset;
}
public append(value: T) {
if (this._records.length >= this.limit) {
// we're full! let's free up some space
this.shift(Math.ceil(this.limit * dropFactor));
}
if (this.keyAttribute) {
const key = this.getKey(value);
if (this._recordsById.has(key)) {
const existingValue = this._recordsById.get(key);
console.warn(
`Tried to append value with duplicate key: ${key} (key attribute is ${this.keyAttribute}). Old/new values:`,
existingValue,
value,
);
throw new Error(`Duplicate key`);
}
this._recordsById.set(key, value);
this.storeIndexOfKey(key, this._records.length);
}
const visibleMap: {[viewId: string]: boolean} = {[DEFAULT_VIEW_ID]: false};
const approxIndexMap: {[viewId: string]: number} = {[DEFAULT_VIEW_ID]: -1};
Object.keys(this.additionalViews).forEach((viewId) => {
visibleMap[viewId] = false;
approxIndexMap[viewId] = -1;
});
const entry = {
value,
id: ++this.nextId,
visible: visibleMap,
approxIndex: approxIndexMap,
};
this._records.push(entry);
this.emitDataEvent({
type: 'append',
entry,
});
}
/**
* Updates or adds a record. Returns `true` if the record already existed.
* Can only be used if a key is used.
*/
public upsert(value: T): boolean {
this.assertKeySet();
const key = this.getKey(value);
if (this.idToIndex.has(key)) {
this.update(this.getIndexOfKey(key), value);
return true;
} else {
this.append(value);
return false;
}
}
/**
* Replaces an item in the base data collection.
* Note that the index is based on the insertion order, and not based on the current view
*/
public update(index: number, value: T) {
const entry = this._records[index];
const oldValue = entry.value;
if (value === oldValue) {
return;
}
const oldVisible = {...entry.visible};
entry.value = value;
if (this.keyAttribute) {
const key = this.getKey(value);
const currentKey = this.getKey(oldValue);
if (currentKey !== key) {
const existingIndex = this.getIndexOfKey(key);
if (existingIndex !== -1 && existingIndex !== index) {
throw new Error(
`Trying to insert duplicate key '${key}', which already exist in the collection`,
);
}
this._recordsById.delete(currentKey);
this.idToIndex.delete(currentKey);
}
this._recordsById.set(key, value);
this.storeIndexOfKey(key, index);
}
this.emitDataEvent({
type: 'update',
entry,
oldValue,
oldVisible,
index,
});
}
/**
* @param index
*
* Warning: this operation can be O(n) if a key is set
*/
public delete(index: number) {
if (index < 0 || index >= this._records.length) {
throw new Error('Out of bounds: ' + index);
}
const entry = this._records.splice(index, 1)[0];
if (this.keyAttribute) {
const key = this.getKey(entry.value);
this._recordsById.delete(key);
this.idToIndex.delete(key);
if (index === 0) {
// lucky happy case, this is more efficient
this.shiftOffset -= 1;
} else {
// Optimization: this is O(n)! Should be done as an async job
this.idToIndex.forEach((keyIndex, key) => {
if (keyIndex + this.shiftOffset > index)
this.storeIndexOfKey(key, keyIndex - 1);
});
}
}
this.emitDataEvent({
type: 'remove',
index,
entry,
});
}
/**
* Removes the item with the given key from this dataSource.
* Returns false if no record with the given key was found
*
* Warning: this operation can be O(n) if a key is set
*/
public deleteByKey(keyValue: KeyType): boolean {
this.assertKeySet();
const index = this.getIndexOfKey(keyValue);
if (index === -1) {
return false;
}
this.delete(index);
return true;
}
/**
* Removes the first N entries.
* @param amount
*/
public shift(amount: number) {
amount = Math.min(amount, this._records.length);
if (amount === this._records.length) {
this.clear();
return;
}
// increase an offset variable with amount, and correct idToIndex reads / writes with that
this.shiftOffset -= amount;
// removes the affected records for _records, _recordsById and idToIndex
const removed = this._records.splice(0, amount);
if (this.keyAttribute) {
removed.forEach((entry) => {
const key = this.getKey(entry.value);
this._recordsById.delete(key);
this.idToIndex.delete(key);
});
}
if (
this.view.isSorted &&
removed.length > 10 &&
removed.length > shiftRebuildTreshold * this._records.length
) {
// removing a large amount of items is expensive when doing it sorted,
// let's fallback to the async processing of all data instead
// MWE: there is a risk here that rebuilding is too blocking, as this might happen
// in background when new data arrives, and not explicitly on a user interaction
this.rebuild();
} else {
this.emitDataEvent({
type: 'shift',
entries: removed,
amount,
});
}
}
/**
* The clear operation removes any records stored, but will keep the current view preferences such as sorting and filtering
*/
public clear() {
this._records = [];
this._recordsById = new Map();
this.shiftOffset = 0;
this.idToIndex = new Map();
this.rebuild();
}
/**
* The rebuild function that would support rebuilding multiple views all at once
*/
public rebuild() {
this.view.rebuild();
Object.entries(this.additionalViews).forEach(([, dataView]) => {
dataView.rebuild();
});
}
/**
* Returns a fork of this dataSource, that shares the source data with this dataSource,
* but has it's own FSRW pipeline, to allow multiple views on the same data
*/
private fork(viewId: string): DataSourceView<T, KeyType> {
this._records.forEach((entry) => {
entry.visible[viewId] = entry.visible[DEFAULT_VIEW_ID];
entry.approxIndex[viewId] = entry.approxIndex[DEFAULT_VIEW_ID];
});
const newView = new DataSourceView<T, KeyType>(this, viewId);
// Refresh the new view so that it has all the existing records.
newView.rebuild();
return newView;
}
/**
* Returns a new view of the `DataSource` if there doesn't exist a `DataSourceView` with the `viewId` passed in.
* The view will allow different filters and sortings on the `DataSource` which can be helpful in cases
* where multiple tables/views are needed.
* @param viewId id for the `DataSourceView`
* @returns `DataSourceView` that corresponds to the `viewId`
*/
public getAdditionalView(viewId: string): DataSourceView<T, KeyType> {
if (viewId in this.additionalViews) {
return this.additionalViews[viewId];
}
this.additionalViews[viewId] = this.fork(viewId);
return this.additionalViews[viewId];
}
public deleteView(viewId: string): void {
if (viewId in this.additionalViews) {
delete this.additionalViews[viewId];
// TODO: Ideally remove the viewId in the visible and approxIndex of DataView outputs
this._records.forEach((entry) => {
delete entry.visible[viewId];
delete entry.approxIndex[viewId];
});
}
}
private assertKeySet() {
if (!this.keyAttribute) {
throw new Error(
'No key has been set. Records cannot be looked up by key',
);
}
}
private getKey(value: T): KeyType;
private getKey(value: any): any {
this.assertKeySet();
const key = value[this.keyAttribute!];
if ((typeof key === 'string' || typeof key === 'number') && key !== '') {
return key;
}
throw new Error(`Invalid key value: '${key}'`);
}
private storeIndexOfKey(key: KeyType, index: number) {
// de-normalize the index, so that on later look ups its corrected again
this.idToIndex.set(key, index - this.shiftOffset);
}
private emitDataEvent(event: DataEvent<T>) {
// Optimization: potentially we could schedule this to happen async,
// using a queue,
// or only if there is an active view (although that could leak memory)
this.view.processEvent(event);
Object.entries(this.additionalViews).forEach(([, dataView]) => {
dataView.processEvent(event);
});
}
/**
* @private
*/
serialize(): readonly T[] {
return this.records();
}
/**
* @private
*/
deserialize(value: any[]) {
this.clear();
value.forEach((record) => {
this.append(record);
});
}
}
function unwrap<T>(entry: Entry<T>): T {
return entry?.value;
}
export class DataSourceView<T, KeyType> {
public readonly datasource: DataSource<T, KeyType>;
private sortBy: undefined | ((a: T) => Primitive) = undefined;
private reverse: boolean = false;
private filter?: (value: T) => boolean = undefined;
/**
* @readonly
*/
public windowStart = 0;
/**
* @readonly
*/
public windowEnd = 0;
private viewId;
private outputChangeListeners = new Set<(change: OutputChange) => void>();
/**
* This is the base view data, that is filtered and sorted, but not reversed or windowed
*/
private _output: Entry<T>[] = [];
constructor(datasource: DataSource<T, KeyType>, viewId: string) {
this.datasource = datasource;
this.viewId = viewId;
}
public get size() {
return this._output.length;
}
public get isSorted() {
return !!this.sortBy;
}
public get isFiltered() {
return !!this.filter;
}
public get isReversed() {
return this.reverse;
}
/**
* Returns a defensive copy of the current output.
* Sort, filter, reverse and are applied.
* Start and end behave like slice, and default to the currently active window.
*/
public output(start = this.windowStart, end = this.windowEnd): readonly T[] {
if (this.reverse) {
return this._output
.slice(this._output.length - end, this._output.length - start)
.reverse()
.map((e) => e.value);
} else {
return this._output.slice(start, end).map((e) => e.value);
}
}
public setWindow(start: number, end: number) {
this.windowStart = start;
this.windowEnd = end;
}
public addListener(listener: (change: OutputChange) => void) {
this.outputChangeListeners.add(listener);
return () => {
this.outputChangeListeners.delete(listener);
};
}
public setSortBy(sortBy: undefined | keyof T | ((a: T) => Primitive)) {
if (this.sortBy === sortBy) {
return;
}
if (
typeof sortBy === 'string' &&
(!this.sortBy || (this.sortBy as any).sortByKey !== sortBy)
) {
sortBy = property(sortBy);
Object.assign(sortBy, {
sortByKey: sortBy,
});
}
this.sortBy = sortBy as any;
this.rebuild();
}
public setFilter(filter: undefined | ((value: T) => boolean)) {
if (this.filter !== filter) {
this.filter = filter;
this.rebuild();
}
}
public toggleReversed() {
this.setReversed(!this.reverse);
}
public setReversed(reverse: boolean) {
if (this.reverse !== reverse) {
this.reverse = reverse;
this.notifyReset(this._output.length);
}
}
/**
* The reset operation resets any view preferences such as sorting and filtering, but keeps the current set of records.
*/
reset() {
this.sortBy = undefined;
this.reverse = false;
this.filter = undefined;
this.windowStart = 0;
this.windowEnd = 0;
this.rebuild();
}
private normalizeIndex(viewIndex: number): number {
return this.reverse ? this._output.length - 1 - viewIndex : viewIndex;
}
public get(viewIndex: number): T {
return this._output[this.normalizeIndex(viewIndex)]?.value;
}
public getEntry(viewIndex: number): Entry<T> {
return this._output[this.normalizeIndex(viewIndex)];
}
public getViewIndexOfEntry(entry: Entry<T>) {
// Note: this function leverages the fact that entry is an internal structure that is mutable,
// so any changes in the entry being moved around etc will be reflected in the original `entry` object,
// and we just want to verify that this entry is indeed still the same element, visible, and still present in
// the output data set.
if (
entry.visible[this.viewId] &&
entry.id === this._output[entry.approxIndex[this.viewId]]?.id
) {
return this.normalizeIndex(entry.approxIndex[this.viewId]);
}
return -1;
}
public [Symbol.iterator](): IterableIterator<T> {
const self = this;
let offset = this.windowStart;
return {
next() {
offset++;
if (offset > self.windowEnd || offset > self.size) {
return {done: true, value: undefined};
} else {
return {
value: self.get(offset - 1),
};
}
},
[Symbol.iterator]() {
return this;
},
};
}
private notifyAllListeners(change: OutputChange) {
this.outputChangeListeners.forEach((listener) => listener(change));
}
private notifyItemUpdated(viewIndex: number) {
viewIndex = this.normalizeIndex(viewIndex);
if (
!this.outputChangeListeners.size ||
viewIndex < this.windowStart ||
viewIndex >= this.windowEnd
) {
return;
}
this.notifyAllListeners({
type: 'update',
index: viewIndex,
});
}
private notifyItemShift(index: number, delta: number) {
if (!this.outputChangeListeners.size) {
return;
}
let viewIndex = this.normalizeIndex(index);
if (this.reverse && delta < 0) {
viewIndex -= delta; // we need to correct for normalize already using the new length after applying this change
}
// Idea: we could add an option to automatically shift the window for before events.
this.notifyAllListeners({
type: 'shift',
delta,
index: viewIndex,
newCount: this._output.length,
location:
viewIndex < this.windowStart
? 'before'
: viewIndex >= this.windowEnd
? 'after'
: 'in',
});
}
private notifyReset(count: number) {
this.notifyAllListeners({
type: 'reset',
newCount: count,
});
}
/**
* @private
*/
processEvent(event: DataEvent<T>) {
const {_output: output, sortBy, filter} = this;
switch (event.type) {
case 'append': {
const {entry} = event;
entry.visible[this.viewId] = filter ? filter(entry.value) : true;
if (!entry.visible[this.viewId]) {
// not in filter? skip this entry
return;
}
if (!sortBy) {
// no sorting? insert at the end, or beginning
entry.approxIndex[this.viewId] = output.length;
output.push(entry);
this.notifyItemShift(entry.approxIndex[this.viewId], 1);
} else {
this.insertSorted(entry);
}
break;
}
case 'update': {
const {entry} = event;
entry.visible[this.viewId] = filter ? filter(entry.value) : true;
// short circuit; no view active so update straight away
if (!filter && !sortBy) {
output[event.index].approxIndex[this.viewId] = event.index;
this.notifyItemUpdated(event.index);
} else if (!event.oldVisible[this.viewId]) {
if (!entry.visible[this.viewId]) {
// Done!
} else {
// insertion, not visible before
this.insertSorted(entry);
}
} else {
// Entry was visible previously
const existingIndex = this.getSortedIndex(entry, event.oldValue);
if (!entry.visible[this.viewId]) {
// Remove from output
output.splice(existingIndex, 1);
this.notifyItemShift(existingIndex, -1);
} else {
// Entry was and still is visible
if (
!this.sortBy ||
this.sortBy(event.oldValue) === this.sortBy(entry.value)
) {
// Still at same position, so done!
this.notifyItemUpdated(existingIndex);
} else {
// item needs to be moved cause of sorting
// possible optimization: if we discover that old and new index would be the same,
// despite different sort values, we could still emit only an update instead of two shifts
output.splice(existingIndex, 1);
this.notifyItemShift(existingIndex, -1);
// find new sort index
this.insertSorted(entry);
}
}
}
break;
}
case 'remove': {
this.processRemoveEvent(event.index, event.entry);
break;
}
case 'shift': {
// no sorting? then all items are removed from the start so optimize for that
if (!sortBy) {
let amount = 0;
if (!filter) {
amount = event.amount;
} else {
// if there is a filter, count the visibles and shift those
for (let i = 0; i < event.entries.length; i++)
if (event.entries[i].visible[this.viewId]) amount++;
}
output.splice(0, amount);
this.notifyItemShift(0, -amount);
} else {
// we have sorting, so we need to remove item by item
// we do this backward, so that approxIndex is more likely to be correct
for (let i = event.entries.length - 1; i >= 0; i--) {
this.processRemoveEvent(i, event.entries[i]);
}
}
break;
}
default:
throw new Error('unknown event type');
}
}
private processRemoveEvent(index: number, entry: Entry<T>) {
const {_output: output, sortBy, filter} = this;
// filter active, and not visible? short circuilt
if (!entry.visible[this.viewId]) {
return;
}
// no sorting, no filter?
if (!sortBy && !filter) {
output.splice(index, 1);
this.notifyItemShift(index, -1);
} else {
// sorting or filter is active, find the actual location
const existingIndex = this.getSortedIndex(entry, entry.value);
output.splice(existingIndex, 1);
this.notifyItemShift(existingIndex, -1);
}
}
/**
* Rebuilds the entire view. Typically there should be no need to call this manually
* @private
*/
rebuild() {
// Pending on the size, should we batch this in smaller non-blocking steps,
// which we update in a double-buffering mechanism, report progress, and swap out when done?
//
// MWE: 9-3-2020 postponed for now, one massive sort seems fine. It might shortly block,
// but that happens only (exception: limit caused shifts) on user interaction at very roughly 1ms per 1000 records.
// See also comment below
const {sortBy, filter, sortHelper} = this;
// copy base array or run filter (with side effecty update of visible)
// @ts-ignore prevent making _record public
const records: Entry<T>[] = this.datasource._records;
let output = filter
? records.filter((entry) => {
entry.visible[this.viewId] = filter(entry.value);
return entry.visible[this.viewId];
})
: records.slice();
if (sortBy) {
// Pending on the size, should we batch this in smaller steps?
// The following sorthing method can be taskified, however,
// the implementation is 20x slower than a native sort. So for now we stick to a
// blocking sort, until we have some more numbers that this is hanging for anyone
// const filtered = output;
// output = [];
// filtered.forEach((entry) => {
// const insertionIndex = sortedLastIndexBy(output, entry, sortHelper);
// output.splice(insertionIndex, 0, entry);
// });
output = lodashSort(output, sortHelper); // uses array.sort under the hood
}
// write approx indexes for faster lookup of entries in visible output
for (let i = 0; i < output.length; i++) {
output[i].approxIndex[this.viewId] = i;
}
this._output = output;
this.notifyReset(output.length);
}
private sortHelper = (a: Entry<T>) =>
this.sortBy ? this.sortBy(a.value) : a.id;
private getSortedIndex(entry: Entry<T>, oldValue: T) {
const {_output: output} = this;
if (output[entry.approxIndex[this.viewId]] === entry) {
// yay!
return entry.approxIndex[this.viewId];
}
let index = sortedIndexBy(
output,
{
value: oldValue,
id: -1,
visible: entry.visible,
approxIndex: entry.approxIndex,
},
this.sortHelper,
);
index--;
// the item we are looking for is not necessarily the first one at the insertion index
while (output[index] !== entry) {
index++;
if (index >= output.length) {
throw new Error('illegal state: sortedIndex not found'); // sanity check to avoid browser freeze if people mess up with internals
}
}
return index;
}
private insertSorted(entry: Entry<T>) {
// apply sorting
const insertionIndex = sortedLastIndexBy(
this._output,
entry,
this.sortHelper,
);
entry.approxIndex[this.viewId] = insertionIndex;
this._output.splice(insertionIndex, 0, entry);
this.notifyItemShift(insertionIndex, 1);
}
}

849
desktop/flipper-plugin-core/src/data-source/__tests__/datasource-basics.node.tsx Normal file
View File

@@ -0,0 +1,849 @@
/**
* Copyright (c) Meta Platforms, Inc. and affiliates.
*
* This source code is licensed under the MIT license found in the
* LICENSE file in the root directory of this source tree.
*
* @format
*/
import {DataSource, createDataSource} from '../DataSource';
type Todo = {
id: string;
title: string;
done?: boolean;
};
const drinkCoffee: Todo = {
id: 'coffee',
title: 'drink coffee',
};
const eatCookie: Todo = {
id: 'cookie',
title: 'eat a cookie',
done: true,
};
const submitBug: Todo = {
id: 'bug',
title: 'submit a bug',
done: false,
};
function unwrap<T>(array: readonly {value: T}[]): readonly T[] {
return array.map((entry) => entry.value);
}
function rawOutput<T>(ds: DataSource<T, T[keyof T]>): readonly T[] {
// @ts-ignore
const output = ds.view._output;
return unwrap(output);
}
test('can create a datasource', () => {
const ds = createDataSource<Todo>([eatCookie]);
expect(ds.records()).toEqual([eatCookie]);
ds.append(drinkCoffee);
expect(ds.records()).toEqual([eatCookie, drinkCoffee]);
// @ts-ignore
expect(() => ds.getById('stuff')).toThrow(
/Records cannot be looked up by key/,
);
ds.update(1, submitBug);
expect(ds.records()[1]).toBe(submitBug);
ds.delete(0);
expect(ds.records()[0]).toBe(submitBug);
});
test('can create a keyed datasource', () => {
const ds = createDataSource<Todo, 'id'>([eatCookie], {key: 'id'});
expect(ds.records()).toEqual([eatCookie]);
ds.append(drinkCoffee);
expect(ds.records()).toEqual([eatCookie, drinkCoffee]);
expect(ds.getById('bug')).toBe(undefined);
expect(ds.getById('cookie')).toBe(eatCookie);
expect(ds.getById('coffee')).toBe(drinkCoffee);
expect(ds.getIndexOfKey('bug')).toBe(-1);
expect(ds.getIndexOfKey('cookie')).toBe(0);
expect(ds.getIndexOfKey('coffee')).toBe(1);
ds.update(1, submitBug);
expect(ds.records()[1]).toBe(submitBug);
expect(ds.getById('coffee')).toBe(undefined);
expect(ds.getById('bug')).toBe(submitBug);
expect(ds.getIndexOfKey('bug')).toBe(1);
expect(ds.getIndexOfKey('cookie')).toBe(0);
expect(ds.getIndexOfKey('coffee')).toBe(-1);
// upsert existing
const newBug = {
id: 'bug',
title: 'file a bug',
done: true,
};
ds.upsert(newBug);
expect(ds.records()[1]).toBe(newBug);
expect(ds.getById('bug')).toBe(newBug);
// upsert new
const trash = {
id: 'trash',
title: 'take trash out',
};
ds.upsert(trash);
expect(ds.records()[2]).toBe(trash);
expect(ds.getById('trash')).toBe(trash);
// delete by key
expect(ds.records()).toEqual([eatCookie, newBug, trash]);
expect(ds.deleteByKey('bug')).toBe(true);
expect(ds.records()).toEqual([eatCookie, trash]);
expect(ds.getIndexOfKey('bug')).toBe(-1);
expect(ds.getIndexOfKey('cookie')).toBe(0);
expect(ds.getIndexOfKey('trash')).toBe(1);
});
test('throws on invalid keys', () => {
const ds = createDataSource<Todo, 'id'>([eatCookie], {key: 'id'});
expect(() => {
ds.append({id: '', title: 'test'});
}).toThrow(`Invalid key value: ''`);
expect(() => {
ds.append({id: 'cookie', title: 'test'});
}).toThrow(`Duplicate key`);
});
test('throws on update causing duplicate key', () => {
const ds = createDataSource<Todo, 'id'>([eatCookie, submitBug], {key: 'id'});
expect(() => {
ds.update(0, {id: 'bug', title: 'oops'});
}).toThrow(
`Trying to insert duplicate key 'bug', which already exist in the collection`,
);
});
test('removing invalid keys', () => {
const ds = createDataSource<Todo, 'id'>([eatCookie], {key: 'id'});
expect(ds.deleteByKey('trash')).toBe(false);
expect(() => {
ds.delete(1);
}).toThrowError('Out of bounds');
});
test('sorting works', () => {
const ds = createDataSource<Todo>([eatCookie, drinkCoffee]);
ds.view.setSortBy((todo) => todo.title);
expect(rawOutput(ds)).toEqual([drinkCoffee, eatCookie]);
ds.view.setSortBy(undefined);
ds.view.setSortBy(undefined);
expect(rawOutput(ds)).toEqual([eatCookie, drinkCoffee]);
ds.view.setSortBy((todo) => todo.title);
expect(rawOutput(ds)).toEqual([drinkCoffee, eatCookie]);
const aleph = {
id: 'd',
title: 'aleph',
};
ds.append(aleph);
expect(ds.records()).toEqual([eatCookie, drinkCoffee, aleph]);
expect(rawOutput(ds)).toEqual([aleph, drinkCoffee, eatCookie]);
});
test('sorting preserves insertion order with equal keys', () => {
type N = {
$: string;
name: string;
};
const a = {$: 'a', name: 'a'};
const b1 = {$: 'b', name: 'b1'};
const b2 = {$: 'b', name: 'b2'};
const b3 = {$: 'b', name: 'b3'};
const c = {$: 'c', name: 'c'};
const ds = createDataSource<N>([]);
ds.view.setSortBy('$');
ds.append(b1);
ds.append(c);
ds.append(b2);
ds.append(a);
ds.append(b3);
expect(ds.records()).toEqual([b1, c, b2, a, b3]);
expect(rawOutput(ds)).toEqual([a, b1, b2, b3, c]);
// if we append a new item with existig item, it should end up in the end
const b4 = {
$: 'b',
name: 'b4',
};
ds.append(b4);
expect(ds.records()).toEqual([b1, c, b2, a, b3, b4]);
expect(rawOutput(ds)).toEqual([a, b1, b2, b3, b4, c]);
// if we replace the middle item, it should end up in the middle
const b2r = {
$: 'b',
name: 'b2replacement',
};
ds.update(2, b2r);
expect(ds.records()).toEqual([b1, c, b2r, a, b3, b4]);
expect(rawOutput(ds)).toEqual([a, b1, b2r, b3, b4, c]);
// if we replace something with a different sort value, it should be sorted properly, and the old should disappear
const b3r = {
$: 'aa',
name: 'b3replacement',
};
ds.update(4, b3r);
expect(ds.records()).toEqual([b1, c, b2r, a, b3r, b4]);
expect(rawOutput(ds)).toEqual([a, b3r, b1, b2r, b4, c]);
ds.delete(3);
expect(ds.records()).toEqual([b1, c, b2r, b3r, b4]);
expect(rawOutput(ds)).toEqual([b3r, b1, b2r, b4, c]);
});
test('filter + sort', () => {
const ds = createDataSource<Todo>([eatCookie, drinkCoffee, submitBug]);
ds.view.setFilter((t) => t.title.indexOf('c') === -1);
ds.view.setSortBy('title');
expect(rawOutput(ds)).toEqual([submitBug]);
// append with and without filter
const a = {id: 'a', title: 'does have that letter: c'};
const b = {id: 'b', title: 'doesnt have that letter'};
ds.append(a);
expect(rawOutput(ds)).toEqual([submitBug]);
ds.append(b);
expect(rawOutput(ds)).toEqual([b, submitBug]);
// filter in
const newCookie = {
id: 'cookie',
title: 'eat a ookie',
};
ds.update(0, newCookie);
expect(rawOutput(ds)).toEqual([b, newCookie, submitBug]);
// update -> filter in
const newCoffee = {
id: 'coffee',
title: 'better drink tea',
};
ds.append(newCoffee);
expect(rawOutput(ds)).toEqual([newCoffee, b, newCookie, submitBug]);
// update -> filter out
ds.update(2, {id: 'bug', title: 'bug has c!'});
expect(rawOutput(ds)).toEqual([newCoffee, b, newCookie]);
ds.update(2, submitBug);
expect(rawOutput(ds)).toEqual([newCoffee, b, newCookie, submitBug]);
ds.delete(3); // a
ds.delete(3); // b
expect(rawOutput(ds)).toEqual([newCoffee, newCookie, submitBug]);
ds.view.setFilter(undefined);
expect(rawOutput(ds)).toEqual([newCoffee, drinkCoffee, newCookie, submitBug]);
ds.view.setSortBy(undefined);
// key insertion order
expect(rawOutput(ds)).toEqual([newCookie, drinkCoffee, submitBug, newCoffee]);
});
test('filter + sort + index', () => {
const ds = createDataSource<Todo, 'id'>([eatCookie, drinkCoffee, submitBug], {
key: 'id',
});
ds.view.setFilter((t) => t.title.indexOf('c') === -1);
ds.view.setSortBy('title');
expect(rawOutput(ds)).toEqual([submitBug]);
// append with and without filter
const a = {id: 'a', title: 'does have that letter: c'};
const b = {id: 'b', title: 'doesnt have that letter'};
ds.append(a);
expect(rawOutput(ds)).toEqual([submitBug]);
ds.append(b);
expect(rawOutput(ds)).toEqual([b, submitBug]);
// filter in
const newCookie = {
id: 'cookie',
title: 'eat a ookie',
};
ds.update(0, newCookie);
expect(rawOutput(ds)).toEqual([b, newCookie, submitBug]);
// update -> filter in
const newCoffee = {
id: 'coffee',
title: 'better drink tea',
};
ds.upsert(newCoffee);
expect(rawOutput(ds)).toEqual([newCoffee, b, newCookie, submitBug]);
// update -> filter out
ds.update(2, {id: 'bug', title: 'bug has c!'});
expect(rawOutput(ds)).toEqual([newCoffee, b, newCookie]);
ds.update(2, submitBug);
expect(rawOutput(ds)).toEqual([newCoffee, b, newCookie, submitBug]);
ds.view.setFilter(undefined);
expect(rawOutput(ds)).toEqual([newCoffee, a, b, newCookie, submitBug]);
ds.view.setSortBy(undefined);
// key insertion order
expect(rawOutput(ds)).toEqual([newCookie, newCoffee, submitBug, a, b]);
// verify getOutput
expect(rawOutput(ds).slice(1, 3)).toEqual([newCoffee, submitBug]);
expect(ds.view.output(1, 3)).toEqual([newCoffee, submitBug]);
});
test('filter', () => {
const ds = createDataSource<Todo, 'id'>([eatCookie, drinkCoffee, submitBug], {
key: 'id',
});
ds.view.setFilter((t) => t.title.indexOf('c') === -1);
expect(rawOutput(ds)).toEqual([submitBug]);
// append with and without filter
const a = {id: 'a', title: 'does have that letter: c'};
const b = {id: 'b', title: 'doesnt have that letter'};
ds.append(a);
expect(rawOutput(ds)).toEqual([submitBug]);
ds.append(b);
expect(rawOutput(ds)).toEqual([submitBug, b]);
// filter in
const newCookie = {
id: 'cookie',
title: 'eat a ookie',
};
ds.update(0, newCookie);
expect(rawOutput(ds)).toEqual([newCookie, submitBug, b]);
// update -> filter in
const newCoffee = {
id: 'coffee',
title: 'better drink tea',
};
ds.upsert(newCoffee);
expect(rawOutput(ds)).toEqual([newCookie, newCoffee, submitBug, b]);
// update -> filter out
ds.update(2, {id: 'bug', title: 'bug has c!'});
expect(rawOutput(ds)).toEqual([newCookie, newCoffee, b]);
ds.update(2, submitBug);
ds.view.setFilter(undefined);
expect(rawOutput(ds)).toEqual([newCookie, newCoffee, submitBug, a, b]);
});
test('reverse without sorting', () => {
const ds = createDataSource<Todo>([eatCookie, drinkCoffee]);
ds.view.setWindow(0, 100);
expect(ds.view.output()).toEqual([eatCookie, drinkCoffee]);
ds.view.toggleReversed();
expect(ds.view.output(1, 2)).toEqual([eatCookie]);
expect(ds.view.output(0, 1)).toEqual([drinkCoffee]);
expect(ds.view.output(0, 2)).toEqual([drinkCoffee, eatCookie]);
expect(ds.view.output()).toEqual([drinkCoffee, eatCookie]);
ds.append(submitBug);
expect(ds.records()).toEqual([eatCookie, drinkCoffee, submitBug]);
expect(ds.view.output()).toEqual([submitBug, drinkCoffee, eatCookie]);
const x = {id: 'x', title: 'x'};
ds.update(0, x);
expect(ds.records()).toEqual([x, drinkCoffee, submitBug]);
expect(ds.view.output()).toEqual([submitBug, drinkCoffee, x]);
const y = {id: 'y', title: 'y'};
const z = {id: 'z', title: 'z'};
ds.update(2, z);
ds.update(1, y);
expect(ds.records()).toEqual([x, y, z]);
expect(ds.view.output()).toEqual([z, y, x]);
ds.view.setReversed(false);
expect(ds.view.output()).toEqual([x, y, z]);
});
test('reverse with sorting', () => {
type N = {
$: string;
name: string;
};
const a = {$: 'a', name: 'a'};
const b1 = {$: 'b', name: 'b1'};
const b2 = {$: 'b', name: 'b2'};
const b3 = {$: 'b', name: 'b3'};
const c = {$: 'c', name: 'c'};
const ds = createDataSource<N>([]);
ds.view.setWindow(0, 100);
ds.view.setReversed(true);
ds.append(b1);
ds.append(c);
expect(ds.view.output()).toEqual([c, b1]);
ds.view.setSortBy('$');
expect(ds.view.output()).toEqual([c, b1]);
ds.append(b2);
expect(ds.view.output()).toEqual([c, b2, b1]);
ds.append(a);
expect(ds.view.output()).toEqual([c, b2, b1, a]);
ds.append(b3);
expect(ds.view.output()).toEqual([c, b3, b2, b1, a]);
// if we append a new item with existig item, it should end up in the end
const b4 = {
$: 'b',
name: 'b4',
};
ds.append(b4);
expect(ds.view.output()).toEqual([c, b4, b3, b2, b1, a]);
// if we replace the middle item, it should end up in the middle
const b2r = {
$: 'b',
name: 'b2replacement',
};
ds.update(2, b2r);
expect(ds.view.output()).toEqual([c, b4, b3, b2r, b1, a]);
// if we replace something with a different sort value, it should be sorted properly, and the old should disappear
const b3r = {
$: 'aa',
name: 'b3replacement',
};
ds.update(4, b3r);
expect(ds.view.output()).toEqual([c, b4, b2r, b1, b3r, a]);
ds.delete(4);
expect(ds.view.output()).toEqual([c, b4, b2r, b1, a]);
});
test('reset', () => {
const ds = createDataSource<Todo, 'id'>([submitBug, drinkCoffee, eatCookie], {
key: 'id',
});
ds.view.setSortBy('title');
ds.view.setFilter((v) => v.id !== 'cookie');
expect(rawOutput(ds)).toEqual([drinkCoffee, submitBug]);
expect([...ds.keys()]).toEqual(['bug', 'coffee', 'cookie']);
ds.view.reset();
expect(rawOutput(ds)).toEqual([submitBug, drinkCoffee, eatCookie]);
expect([...ds.keys()]).toEqual(['bug', 'coffee', 'cookie']);
});
test('clear', () => {
const ds = createDataSource<Todo, 'id'>([submitBug, drinkCoffee, eatCookie], {
key: 'id',
});
ds.view.setSortBy('title');
ds.view.setFilter((v) => v.id !== 'cookie');
expect(rawOutput(ds)).toEqual([drinkCoffee, submitBug]);
expect([...ds.keys()]).toEqual(['bug', 'coffee', 'cookie']);
ds.clear();
expect(rawOutput(ds)).toEqual([]);
expect([...ds.keys()]).toEqual([]);
ds.append(eatCookie);
ds.append(drinkCoffee);
ds.append(submitBug);
expect([...ds.keys()]).toEqual(['cookie', 'coffee', 'bug']);
// resets in the same ordering as view preferences were preserved
expect(rawOutput(ds)).toEqual([drinkCoffee, submitBug]);
});
function testEvents<T>(
initial: T[],
op: (ds: DataSource<T, T[keyof T]>) => void,
key?: keyof T,
): any[] {
const ds = createDataSource<T, keyof T>(initial, {key});
const events: any[] = [];
const unsubscribe = ds.view.addListener((e) => events.push(e));
op(ds);
unsubscribe();
return events;
}
test('it emits the right events - zero window', () => {
expect(
testEvents(['a', 'b'], (ds) => {
ds.append('c');
ds.update(1, 'x');
}),
).toEqual([
{
delta: 1,
index: 2,
location: 'after',
newCount: 3,
type: 'shift',
},
]);
});
test('it emits the right events - small window', () => {
expect(
testEvents(['a', 'b'], (ds) => {
ds.view.setWindow(0, 3);
ds.append('c');
ds.update(1, 'x');
}),
).toEqual([
{delta: 1, location: 'in', newCount: 3, type: 'shift', index: 2},
{index: 1, type: 'update'},
]);
});
test('it emits the right events - view change', () => {
expect(
testEvents(['a', 'b'], (ds) => {
ds.view.setWindow(1, 2);
ds.view.setSortBy((x) => x);
// a, [b]
ds.update(0, 'x');
// b, [x]
expect(ds.view.get(0)).toEqual('b');
expect(ds.view.get(1)).toEqual('x');
ds.append('y');
// b, [x], y
ds.append('c');
// b, [c], x, y
}),
).toEqual([
{newCount: 2, type: 'reset'},
{index: 0, delta: -1, location: 'before', newCount: 1, type: 'shift'}, // remove a
{index: 1, delta: 1, location: 'in', newCount: 2, type: 'shift'}, // pre-insert x
{index: 2, delta: 1, location: 'after', newCount: 3, type: 'shift'}, // y happened after
{index: 1, delta: 1, location: 'in', newCount: 4, type: 'shift'}, // c becomes the 'in' new indow
]);
});
test('it emits the right events - reversed view change', () => {
expect(
testEvents(['a', 'b'], (ds) => {
ds.view.setWindow(1, 2);
ds.view.setSortBy((x) => x);
ds.view.setReversed(true);
// b, [a]
ds.update(0, 'x');
// x, [b]
expect(ds.view.get(0)).toEqual('x');
expect(ds.view.get(1)).toEqual('b');
ds.append('y');
// y, [x], b
ds.append('c');
// y, [x], c, b
ds.append('a');
// y, [x], c, b, a
}),
).toEqual([
{newCount: 2, type: 'reset'},
{newCount: 2, type: 'reset'}, // FIXME: ideally dedupe these, but due to scheduling will do little harm
{index: 1, delta: -1, location: 'in', newCount: 1, type: 'shift'}, // remove a
{index: 0, delta: 1, location: 'before', newCount: 2, type: 'shift'}, // pre-insert x
{index: 0, delta: 1, location: 'before', newCount: 3, type: 'shift'},
{index: 2, delta: 1, location: 'after', newCount: 4, type: 'shift'},
{index: 4, delta: 1, location: 'after', newCount: 5, type: 'shift'},
]);
});
test('it emits the right events - reversed view change with filter', () => {
expect(
testEvents(['a', 'b'], (ds) => {
ds.view.setWindow(0, 2);
ds.view.setSortBy((x) => x);
ds.view.setReversed(true);
ds.view.setFilter((x) => ['a', 'b'].includes(x));
// [b, a]
ds.update(0, 'x'); // x b
// [b, ]
expect(ds.view.get(0)).toEqual('b');
expect(rawOutput(ds).length).toBe(1);
ds.append('y'); // x b y
// [b, ]
ds.append('c'); // x b y c
// [b, ]
ds.append('a'); // x b y c a
// [b, a]
ds.append('a'); // x b y c a a
// [b, a, a] // N.b. the new a is in the *middle*
ds.delete(2); // x b c a a
// no effect
ds.delete(4); // this removes the second a in input, so the first a in the outpat!
// [b, a]
}),
).toEqual([
{newCount: 2, type: 'reset'},
{newCount: 2, type: 'reset'}, // FIXME: ideally dedupe these, but due to scheduling will do little harm
{newCount: 2, type: 'reset'}, // FIXME: ideally dedupe these, but due to scheduling will do little harm
{index: 1, delta: -1, location: 'in', newCount: 1, type: 'shift'}, // remove a
{index: 1, delta: 1, location: 'in', newCount: 2, type: 'shift'},
{index: 1, delta: 1, location: 'in', newCount: 3, type: 'shift'},
{index: 1, delta: -1, location: 'in', newCount: 2, type: 'shift'},
]);
});
test('basic remove', () => {
const completedBug = {id: 'bug', title: 'fixed bug', done: true};
expect(
testEvents(
[drinkCoffee, eatCookie, submitBug],
(ds) => {
ds.view.setWindow(0, 100);
ds.delete(0);
expect(ds.view.output()).toEqual([eatCookie, submitBug]);
expect(ds.getById('bug')).toBe(submitBug);
expect(ds.getById('coffee')).toBeUndefined();
expect(ds.getById('cookie')).toBe(eatCookie);
ds.upsert(completedBug);
ds.deleteByKey('cookie');
expect(ds.view.output()).toEqual([completedBug]);
expect(ds.getById('bug')).toBe(completedBug);
},
'id',
),
).toEqual([
{
type: 'shift',
newCount: 2,
location: 'in',
index: 0,
delta: -1,
},
{
type: 'update',
index: 1,
},
{
type: 'shift',
index: 0,
location: 'in',
newCount: 1,
delta: -1,
},
]);
});
test('basic shift', () => {
const completedBug = {id: 'bug', title: 'fixed bug', done: true};
expect(
testEvents(
[drinkCoffee, eatCookie, submitBug],
(ds) => {
ds.view.setWindow(0, 100);
ds.shift(2);
expect(ds.view.output()).toEqual([submitBug]);
expect(ds.getById('bug')).toBe(submitBug);
expect(ds.getById('coffee')).toBeUndefined();
expect(ds.getIndexOfKey('bug')).toBe(0);
expect(ds.getIndexOfKey('coffee')).toBe(-1);
ds.upsert(completedBug);
expect(ds.view.output()).toEqual([completedBug]);
expect(ds.getById('bug')).toBe(completedBug);
},
'id',
),
).toEqual([
{
type: 'shift',
newCount: 1,
location: 'in',
index: 0,
delta: -2,
},
{
type: 'update',
index: 0,
},
]);
});
test('sorted shift', () => {
expect(
testEvents(['c', 'b', 'a', 'e', 'd'], (ds) => {
ds.view.setWindow(0, 100);
ds.view.setSortBy((v) => v);
expect(ds.view.output()).toEqual(['a', 'b', 'c', 'd', 'e']);
ds.shift(4);
expect(ds.view.output()).toEqual(['d']);
ds.shift(1); // optimizes to reset
}),
).toEqual([
{newCount: 5, type: 'reset'}, // sort
{delta: -1, index: 4, location: 'in', newCount: 4, type: 'shift'}, // e
{delta: -1, index: 0, location: 'in', newCount: 3, type: 'shift'}, // a
{delta: -1, index: 0, location: 'in', newCount: 2, type: 'shift'}, // b
{delta: -1, index: 0, location: 'in', newCount: 1, type: 'shift'}, // c
{newCount: 0, type: 'reset'}, // shift that clears
]);
});
test('filtered shift', () => {
expect(
testEvents(['c', 'b', 'a', 'e', 'd'], (ds) => {
ds.view.setWindow(0, 100);
ds.view.setFilter((v) => v !== 'b' && v !== 'e');
expect(ds.view.output()).toEqual(['c', 'a', 'd']);
ds.shift(4);
expect(ds.view.output()).toEqual(['d']);
}),
).toEqual([
{newCount: 3, type: 'reset'}, // filter
{type: 'shift', location: 'in', newCount: 1, index: 0, delta: -2}, // optimized shift
]);
});
test('remove after shift works correctly', () => {
const a: Todo = {id: 'a', title: 'a', done: false};
const b: Todo = {id: 'b', title: 'b', done: false};
expect(
testEvents(
[eatCookie, drinkCoffee, submitBug, a, b],
(ds) => {
ds.view.setWindow(0, 100);
ds.shift(2);
ds.deleteByKey('b');
ds.deleteByKey('bug');
expect(ds.view.output()).toEqual([a]);
expect(ds.getIndexOfKey('cookie')).toBe(-1);
expect(ds.getIndexOfKey('coffee')).toBe(-1);
expect(ds.getIndexOfKey('bug')).toBe(-1);
expect(ds.getIndexOfKey('a')).toBe(0);
expect(ds.getIndexOfKey('b')).toBe(-1);
},
'id',
),
).toEqual([
{
type: 'shift',
newCount: 3,
location: 'in',
index: 0,
delta: -2,
},
{
type: 'shift',
newCount: 2,
location: 'in',
index: 2,
delta: -1,
},
{
type: 'shift',
newCount: 1,
location: 'in',
index: 0,
delta: -1,
},
]);
});
test('respects limit', () => {
const grab = (): [length: number, first: number, last: number] => {
const output = ds.view.output();
return [output.length, output[0], output[output.length - 1]];
};
const ds = createDataSource(
[1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18],
{limit: 20},
);
ds.view.setWindow(0, 100);
ds.append(19);
ds.append(20);
expect(grab()).toEqual([20, 1, 20]);
ds.append(21);
expect(grab()).toEqual([19, 3, 21]);
ds.append(22);
expect(grab()).toEqual([20, 3, 22]);
ds.delete(0);
expect(grab()).toEqual([19, 4, 22]);
ds.append(23);
expect(grab()).toEqual([20, 4, 23]);
ds.append(24);
expect(grab()).toEqual([19, 6, 24]);
});
test('DataSource can iterate', () => {
const ds = createDataSource([eatCookie, drinkCoffee], {key: 'id'});
expect([...ds]).toEqual([eatCookie, drinkCoffee]);
expect(Array.from(ds.keys())).toEqual(['cookie', 'coffee']);
expect(Array.from(ds.entries())).toEqual([
['cookie', eatCookie],
['coffee', drinkCoffee],
]);
const seen: Todo[] = [];
for (const todo of ds) {
seen.push(todo);
}
expect(seen).toEqual([eatCookie, drinkCoffee]);
ds.append(submitBug);
expect([...ds]).toEqual([eatCookie, drinkCoffee, submitBug]);
ds.clear();
expect([...ds]).toEqual([]);
ds.append(submitBug);
expect([...ds]).toEqual([submitBug]);
});
test('DataSource.view can iterate', () => {
const ds = createDataSource([eatCookie, drinkCoffee, submitBug, eatCookie]);
ds.view.setSortBy('id');
// bug coffee cookie cookie
ds.view.toggleReversed();
// cookie cookie coffee bug
ds.view.setWindow(1, 3);
// cookie coffee
expect(ds.view.output()).toEqual([eatCookie, drinkCoffee]);
expect([...ds.view]).toEqual([eatCookie, drinkCoffee]);
ds.view.reset();
// default window is empty!
expect([...ds.view]).toEqual([]);
ds.view.setWindow(0, 100);
expect([...ds.view]).toEqual([eatCookie, drinkCoffee, submitBug, eatCookie]);
ds.clear();
expect([...ds.view]).toEqual([]);
});

213
desktop/flipper-plugin-core/src/data-source/__tests__/datasource-perf.node.tsx Normal file
View File

@@ -0,0 +1,213 @@
/**
* Copyright (c) Meta Platforms, Inc. and affiliates.
*
* This source code is licensed under the MIT license found in the
* LICENSE file in the root directory of this source tree.
*
* @format
*/
import {DataSource, createDataSource} from '../DataSource';
type Todo = {
id: string;
title: string;
done: boolean;
};
function generateTodos(amount: number): Todo[] {
const res = new Array<Todo>(amount);
for (let i = 0; i < amount; i++) {
res[i] = {
id: 'todo_' + i,
title:
'' +
((i % 20) * 1000000 + (amount - i)) +
GKChesterton.replace(/Chesterton/g, '' + i),
done: i % 3 === 0,
};
}
return res;
}
const defaultFilter = (t: Todo) => !t.done;
type DataSourceish = DataSource<Todo, Todo[keyof Todo]> | FakeDataSource<Todo>;
// NOTE: this run in jest, which is not optimal for perf, but should give some idea
// make sure to use the `yarn watch` script in desktop root, so that the garbage collector is exposed
// By default skipped to not slow down each and every test run
test.skip('run perf test', () => {
if (!global.gc) {
console.warn(
'Warning: garbage collector not available, skipping this test. Make sure to start the test suite using `yarn watch`',
);
return;
}
const measurements: any = {};
const smallSize = 50000;
const largeSize = 100000;
const smallset = generateTodos(smallSize);
const largeset = generateTodos(largeSize);
const opts = {limit: largeSize * 2};
const datasources = {
unkeyed: createDataSource(smallset, opts),
unkeyed_large: createDataSource(largeset, opts),
keyed: createDataSource(smallset, {key: 'id', ...opts}),
keyed_large: createDataSource(largeset, {key: 'id', ...opts}),
unkeyed_sorted: createDataSource(smallset, opts),
unkeyed_sorted_large: createDataSource(largeset, opts),
keyed_sorted: createDataSource(smallset, {key: 'id', ...opts}),
keyed_sorted_large: createDataSource(largeset, {
key: 'id',
...opts,
}),
fake_small: new FakeDataSource(smallset),
fake_large: new FakeDataSource(largeset),
fake_small_sorted: new FakeDataSource(smallset),
fake_large_sorted: new FakeDataSource(largeset),
};
Object.entries(datasources).forEach(([name, ds]) => {
ds.view.setWindow(0, 1000000);
if (name.includes('sorted')) {
ds.view.setFilter(defaultFilter);
ds.view.setSortBy('title');
}
});
function measure(title: string, task: (ds: DataSourceish) => void) {
measurements[title] = {};
Object.entries(datasources).forEach(([name, ds]) => {
global.gc?.();
const start = Date.now();
task(ds as any);
if (ds instanceof FakeDataSource) {
// to 'render' we need to know the end result (this mimics a lazy evaluation of filter / sort)
// note that this skews the test a bit in favor of fake data source,
// as DataSource would *always* keep things sorted/ filtered, but doing that would explode the test for append / update :)
ds.view.buildOutput();
}
// global.gc?.(); // to cleanup our createdmess as part of the measurement
const duration = Date.now() - start;
measurements[title][name] = duration;
});
}
measure('append', (ds) => {
for (let i = 0; i < 1000; i++) {
ds.append({
id: 'test_' + i,
title: i + 'read some more chesterton!',
done: false,
});
}
});
measure('update', (ds) => {
for (let i = 0; i < 1000; i++) {
ds.update(i, {
id: 'test_update_' + i,
title: i + 'read some more chesterton!',
done: true,
});
}
});
measure('remove', (ds) => {
ds.delete(99);
});
measure('shift', (ds) => {
ds.shift(0.1 * smallSize);
});
measure('change sorting', (ds) => {
ds.view.setSortBy('id');
});
measure('change filter', (ds) => {
ds.view.setFilter((t) => t.title.includes('23')); // 23 does not occur in original text
});
const sum: any = {};
Object.entries(measurements).forEach(([_test, entries]: any) => {
Object.entries(entries).forEach(([ds, duration]) => {
if (!sum[ds]) sum[ds] = 0;
sum[ds] += duration;
});
});
measurements.sum = sum;
console.table(measurements);
});
const GKChesterton = `Gilbert Keith Chesterton KC*SG (29 May 1874 – 14 June 1936) was an English writer,[2] philosopher, lay theologian, and literary and art critic. He has been referred to as the "prince of paradox".[3] Time magazine observed of his writing style: "Whenever possible Chesterton made his points with popular sayings, proverbs, allegories—first carefully turning them inside out."[4]
Chesterton created the fictional priest-detective Father Brown,[5] and wrote on apologetics. Even some of those who disagree with him have recognised the wide appeal of such works as Orthodoxy and The Everlasting Man.[4][6] Chesterton routinely referred to himself as an "orthodox" Christian, and came to identify this position more and more with Catholicism, eventually converting to Catholicism from High Church Anglicanism. Biographers have identified him as a successor to such Victorian authors as Matthew Arnold, Thomas Carlyle, John Henry Newman, and John Ruskin.[7] On his contributions, T. S. Eliot wrote:
He was importantly and consistently on the side of the angels. Behind the Johnsonian fancy-dress, so reassuring to the British public, he concealed the most serious and revolutionary designs—concealing them by exposure ... Chesterton's social and economic ideas...were fundamentally Christian and Catholic. He did more, I think, than any man of his time—and was able to do more than anyone else, because of his particular background, development and abilities as a public performer—to maintain the existence of the important minority in the modern world. He leaves behind a permanent claim upon our loyalty, to see that the work that he did in his time is continued in ours.[8]`;
class FakeDataSource<T> {
data: ReadonlyArray<T>;
output!: ReadonlyArray<T>;
filterFn?: (t: T) => boolean;
private sortAttr?: keyof T;
constructor(initial: T[]) {
this.data = initial;
this.view.buildOutput();
}
view = {
setWindow: (_start: number, _end: number) => {
// noop
},
setFilter: (filter: (t: T) => boolean) => {
this.filterFn = filter;
},
setSortBy: (k: keyof T) => {
this.sortAttr = k;
},
buildOutput: () => {
const filtered = this.filterFn
? this.data.filter(this.filterFn)
: this.data;
const sorted = this.sortAttr
? filtered
.slice()
.sort((a: any, b: any) =>
String.prototype.localeCompare.call(
a[this.sortAttr!],
b[this.sortAttr!],
),
)
: filtered;
this.output = sorted;
},
};
append(v: T) {
this.data = [...this.data, v];
}
update(index: number, v: T) {
this.data = this.data.slice();
(this.data as any)[index] = v;
}
delete(index: number) {
this.data = this.data.slice();
(this.data as any).splice(index, 1);
}
shift(amount: number) {
this.data = this.data.slice(amount);
}
}

111
desktop/flipper-plugin-core/src/index.tsx Normal file
View File

@@ -0,0 +1,111 @@
/**
* Copyright (c) Meta Platforms, Inc. and affiliates.
*
* This source code is licensed under the MIT license found in the
* LICENSE file in the root directory of this source tree.
*
* @format
*/
// Dummy exports to support running plugin code in a headless context.
// We do not want to bundle real code that is going to be used in a browser context to decrease the bundle size.
// Yet some parts of the browser-only code is being evaluated at plugin import, not when it is being rendered.
// Expand the list of stubs as needed when we onboard more and more headless plugins
export const theme = {};
export const styled = () => () => ({});
export {produce, Draft} from 'immer';
import * as TestUtilites from './test-utils/test-utils';
export const TestUtils = TestUtilites;
export {StartPluginOptions as _StartPluginOptions} from './test-utils/test-utils';
import './plugin/PluginBase';
export {BasePluginInstance as _BasePluginInstance} from './plugin/PluginBase';
export {
SandyPluginInstance as _SandyPluginInstance,
PluginClient,
PluginFactory as _PluginFactory,
RealFlipperClient as _RealFlipperClient,
} from './plugin/Plugin';
export {
Device,
DeviceLogListener,
DevicePluginClient,
CrashLogListener,
SandyDevicePluginInstance as _SandyDevicePluginInstance,
DevicePluginFactory as _DevicePluginFactory,
} from './plugin/DevicePlugin';
export {
SandyPluginDefinition as _SandyPluginDefinition,
FlipperPluginInstance,
FlipperPluginModule as _FlipperPluginModule,
FlipperDevicePluginModule as _FlipperDevicePluginModule,
} from './plugin/SandyPluginDefinition';
export {
DataSource,
DataSourceView as _DataSourceView,
DataSourceOptionKey as _DataSourceOptionKey,
DataSourceOptions as _DataSourceOptions,
} from './data-source/DataSource';
export {createDataSource} from './state/createDataSource';
export {
createState,
Atom,
isAtom,
ReadOnlyAtom as _ReadOnlyAtom,
AtomValue as _AtomValue,
} from './state/atom';
export {
setBatchedUpdateImplementation as _setBatchedUpdateImplementation,
batch,
} from './state/batch';
export {
FlipperLib,
getFlipperLib,
setFlipperLibImplementation as _setFlipperLibImplementation,
tryGetFlipperLibImplementation as _tryGetFlipperLibImplementation,
FileDescriptor,
FileEncoding,
RemoteServerContext,
DownloadFileResponse,
} from './plugin/FlipperLib';
export {
MenuEntry,
NormalizedMenuEntry,
buildInMenuEntries as _buildInMenuEntries,
DefaultKeyboardAction,
} from './plugin/MenuEntry';
export {Notification} from './plugin/Notification';
export {CreatePasteArgs, CreatePasteResult} from './plugin/Paste';
export {Idler} from './utils/Idler';
export {
makeShallowSerializable as _makeShallowSerializable,
deserializeShallowObject as _deserializeShallowObject,
} from './utils/shallowSerialization';
import * as path from './utils/path';
export {path};
export {safeStringify} from './utils/safeStringify';
export {stubLogger as _stubLogger} from './utils/Logger';
export {
sleep,
timeout,
createControlledPromise,
uuid,
DeviceOS,
DeviceType,
DeviceLogEntry,
DeviceLogLevel,
Logger,
CrashLog,
ServerAddOn,
ServerAddOnPluginConnection,
FlipperServerForServerAddOn,
} from 'flipper-common';

121
desktop/flipper-plugin-core/src/plugin/DevicePlugin.tsx Normal file
View File

@@ -0,0 +1,121 @@
/**
* Copyright (c) Meta Platforms, Inc. and affiliates.
*
* This source code is licensed under the MIT license found in the
* LICENSE file in the root directory of this source tree.
*
* @format
*/
import {SandyPluginDefinition} from './SandyPluginDefinition';
import {BasePluginInstance, BasePluginClient} from './PluginBase';
import {FlipperLib} from './FlipperLib';
import {Atom, ReadOnlyAtom} from '../state/atom';
import {
DeviceOS,
DeviceType,
DeviceLogEntry,
CrashLog,
ServerAddOnControls,
EventsContract,
MethodsContract,
DeviceDescription,
} from 'flipper-common';
export type DeviceLogListener = (entry: DeviceLogEntry) => void;
export type CrashLogListener = (crash: CrashLog) => void;
export interface Device {
readonly isArchived: boolean;
readonly description: DeviceDescription;
readonly isConnected: boolean;
readonly os: DeviceOS;
readonly serial: string;
readonly deviceType: DeviceType;
readonly connected: Atom<boolean>;
executeShell(command: string): Promise<string>;
addLogListener(callback: DeviceLogListener): Symbol;
addCrashListener(callback: CrashLogListener): Symbol;
removeLogListener(id: Symbol): void;
removeCrashListener(id: Symbol): void;
executeShell(command: string): Promise<string>;
forwardPort(local: string, remote: string): Promise<boolean>;
clearLogs(): Promise<void>;
sendMetroCommand(command: string): Promise<void>;
navigateToLocation(location: string): Promise<void>;
screenshot(): Promise<Uint8Array | undefined>;
installApp(appBundlePath: string): Promise<void>;
}
export type DevicePluginPredicate = (device: Device) => boolean;
export type DevicePluginFactory = (client: DevicePluginClient) => object;
export interface DevicePluginClient<
ServerAddOnEvents extends EventsContract = {},
ServerAddOnMethods extends MethodsContract = {},
> extends BasePluginClient<ServerAddOnEvents, ServerAddOnMethods> {
/**
* opens a different plugin by id, optionally providing a deeplink to bring the plugin to a certain state
*/
selectPlugin(pluginId: string, deeplinkPayload?: unknown): void;
readonly isConnected: boolean;
readonly connected: ReadOnlyAtom<boolean>;
}
export class SandyDevicePluginInstance extends BasePluginInstance {
static is(thing: any): thing is SandyDevicePluginInstance {
return thing instanceof SandyDevicePluginInstance;
}
/** client that is bound to this instance */
readonly client: DevicePluginClient<any, any>;
constructor(
serverAddOnControls: ServerAddOnControls,
flipperLib: FlipperLib,
definition: SandyPluginDefinition,
device: Device,
pluginKey: string,
initialStates?: Record<string, any>,
) {
super(
serverAddOnControls,
flipperLib,
definition,
device,
pluginKey,
initialStates,
);
this.client = {
...this.createBasePluginClient(),
selectPlugin(pluginId: string, deeplink?: unknown) {
flipperLib.selectPlugin(device, null, pluginId, deeplink);
},
get isConnected() {
return device.connected.get();
},
connected: device.connected,
};
this.initializePlugin(() =>
definition.asDevicePluginModule().devicePlugin(this.client),
);
// Do not start server add-ons for archived devices
if (this.device.connected.get()) {
this.startServerAddOn();
}
}
toJSON() {
return '[SandyDevicePluginInstance]';
}
destroy() {
this.stopServerAddOn();
super.destroy();
}
protected get serverAddOnOwner() {
return this.device.serial;
}
}

208
desktop/flipper-plugin-core/src/plugin/FlipperLib.tsx Normal file
View File

@@ -0,0 +1,208 @@
/**
* Copyright (c) Meta Platforms, Inc. and affiliates.
*
* This source code is licensed under the MIT license found in the
* LICENSE file in the root directory of this source tree.
*
* @format
*/
import type {ReactElement} from 'react';
import {Logger} from '../utils/Logger';
import {Device} from './DevicePlugin';
import {NormalizedMenuEntry} from './MenuEntry';
import {RealFlipperClient} from './Plugin';
import {Notification} from './Notification';
import {
ExecOptions,
ExecOut,
BufferEncoding,
MkdirOptions,
DownloadFileStartOptions,
DownloadFileStartResponse,
DownloadFileUpdate,
RmOptions,
fsConstants,
EnvironmentInfo,
FSStatsLike,
FlipperServerCommands,
} from 'flipper-common';
import {CreatePasteArgs, CreatePasteResult} from './Paste';
export type FileEncoding = 'utf-8' | 'base64';
export interface FileDescriptor {
data: string;
name: string;
path?: string;
}
export interface DownloadFileResponse extends DownloadFileStartResponse {
/**
* Indicates whether a download is completed. Resolves with the number of downloaded bytes. Rejects if the download has errors.
*/
completed: Promise<number>;
}
export type RemoteServerContext = {
childProcess: {
exec(
command: string,
options?: {encoding?: BufferEncoding} & ExecOptions,
): Promise<ExecOut<string>>;
};
fs: {
constants: typeof fsConstants;
access(path: string, mode?: number): Promise<void>;
pathExists(path: string, mode?: number): Promise<boolean>;
unlink(path: string): Promise<void>;
mkdir(
path: string,
options: {recursive: true} & MkdirOptions,
): Promise<string | undefined>;
mkdir(
path: string,
options?: {recursive?: false} & MkdirOptions,
): Promise<void>;
rm(path: string, options?: RmOptions): Promise<void>;
copyFile(src: string, dest: string, flags?: number): Promise<void>;
stat(path: string): Promise<FSStatsLike>;
readlink(path: string): Promise<string>;
readFile(
path: string,
options?: {encoding?: BufferEncoding},
): Promise<string>;
readFileBinary(path: string): Promise<Uint8Array>; // No Buffer, which is not a browser type
writeFile(
path: string,
contents: string,
options?: {encoding?: BufferEncoding},
): Promise<void>;
writeFileBinary(path: string, contents: Uint8Array): Promise<void>;
};
downloadFile(
url: string,
dest: string,
options?: DownloadFileStartOptions & {
onProgressUpdate?: (progressUpdate: DownloadFileUpdate) => void;
},
): Promise<DownloadFileResponse>;
};
/**
* This interface exposes all global methods for which an implementation will be provided by Flipper itself
*/
export interface FlipperLib {
isFB: boolean;
logger: Logger;
enableMenuEntries(menuEntries: NormalizedMenuEntry[]): void;
createPaste(
args: string | CreatePasteArgs,
): Promise<CreatePasteResult | undefined>;
GK(gatekeeper: string): boolean;
selectPlugin(
device: Device,
client: RealFlipperClient | null,
pluginId: string,
deeplink: unknown,
): void;
writeTextToClipboard(text: string): void;
openLink(url: string): void;
showNotification(pluginKey: string, notification: Notification): void;
DetailsSidebarImplementation?(props: {
children: any;
width?: number;
minWidth?: number;
}): ReactElement | null;
/**
* @returns
* Imported file data.
* If user cancelled a file selection - undefined.
*/
importFile(options?: {
/**
* Default directory to start the file selection from
*/
defaultPath?: string;
/**
* List of allowed file extensions
*/
extensions?: string[];
/**
* Open file dialog title
*/
title?: string;
/**
* File encoding
*/
encoding?: FileEncoding;
/**
* Allow selection of multiple files
*/
multi?: false;
}): Promise<FileDescriptor | undefined>;
importFile(options?: {
defaultPath?: string;
extensions?: string[];
title?: string;
encoding?: FileEncoding;
multi: true;
}): Promise<FileDescriptor[] | undefined>;
/**
* @returns
* An exported file path (if available) or a file name.
* If user cancelled a file selection - undefined.
*/
exportFile(
/**
* New file data
*/
data: string,
options?: {
/**
* A file path suggestion for a new file.
* A dialog to save file will use it as a starting point.
* Either a complete path to the newly created file, a path to a directory containing the file, or the file name.
*/
defaultPath?: string;
/**
* File encoding
*/
encoding?: FileEncoding;
},
): Promise<string | undefined>;
paths: {
appPath: string;
homePath: string;
staticPath: string;
tempPath: string;
};
environmentInfo: {
os: EnvironmentInfo['os'];
};
remoteServerContext: RemoteServerContext;
intern: InternAPI;
}
interface InternAPI {
graphGet: FlipperServerCommands['intern-graph-get'];
graphPost: FlipperServerCommands['intern-graph-post'];
}
export let flipperLibInstance: FlipperLib | undefined;
export function tryGetFlipperLibImplementation(): FlipperLib | undefined {
return flipperLibInstance;
}
export function getFlipperLib(): FlipperLib {
if (!flipperLibInstance) {
throw new Error('Flipper lib not instantiated');
}
return flipperLibInstance;
}
export function setFlipperLibImplementation(impl: FlipperLib | undefined) {
flipperLibInstance = impl;
}

59
desktop/flipper-plugin-core/src/plugin/MenuEntry.tsx Normal file
View File

@@ -0,0 +1,59 @@
/**
* Copyright (c) Meta Platforms, Inc. and affiliates.
*
* This source code is licensed under the MIT license found in the
* LICENSE file in the root directory of this source tree.
*
* @format
*/
export type MenuEntry = BuiltInMenuEntry | CustomMenuEntry;
export type DefaultKeyboardAction = keyof typeof buildInMenuEntries;
export type NormalizedMenuEntry = {
label: string;
accelerator?: string;
handler: () => void;
action: string;
};
export type CustomMenuEntry = {
label: string;
accelerator?: string;
handler: () => void;
};
export type BuiltInMenuEntry = {
action: keyof typeof buildInMenuEntries;
handler: () => void;
};
export const buildInMenuEntries = {
clear: {
label: 'Clear',
accelerator: 'CmdOrCtrl+K',
action: 'clear',
},
goToBottom: {
label: 'Go To Bottom',
accelerator: 'CmdOrCtrl+B',
action: 'goToBottom',
},
createPaste: {
label: 'Create Paste',
action: 'createPaste',
},
} as const;
export function normalizeMenuEntry(entry: MenuEntry): NormalizedMenuEntry;
export function normalizeMenuEntry(entry: any): NormalizedMenuEntry {
const builtInEntry: NormalizedMenuEntry | undefined = (
buildInMenuEntries as any
)[entry.action];
return builtInEntry
? {...builtInEntry, ...entry}
: {
...entry,
action: entry.action || entry.label,
};
}

20
desktop/flipper-plugin-core/src/plugin/Notification.tsx Normal file
View File

@@ -0,0 +1,20 @@
/**
* Copyright (c) Meta Platforms, Inc. and affiliates.
*
* This source code is licensed under the MIT license found in the
* LICENSE file in the root directory of this source tree.
*
* @format
*/
import type {ReactNode} from 'react';
export type Notification = {
id: string;
title: string;
message: string | ReactNode;
severity: 'warning' | 'error';
timestamp?: number;
category?: string;
/** The action will be available as deeplink payload when the notification is clicked. */
action?: string;
};

21
desktop/flipper-plugin-core/src/plugin/Paste.tsx Normal file
View File

@@ -0,0 +1,21 @@
/**
* Copyright (c) Meta Platforms, Inc. and affiliates.
*
* This source code is licensed under the MIT license found in the
* LICENSE file in the root directory of this source tree.
*
* @format
*/
export type CreatePasteArgs = {
content: string;
title?: string;
showSuccessNotification?: boolean;
showErrorNotification?: boolean;
writeToClipboard?: boolean;
};
export type CreatePasteResult = {
number: number;
url: string;
};

318
desktop/flipper-plugin-core/src/plugin/Plugin.tsx Normal file
View File

@@ -0,0 +1,318 @@
/**
* Copyright (c) Meta Platforms, Inc. and affiliates.
*
* This source code is licensed under the MIT license found in the
* LICENSE file in the root directory of this source tree.
*
* @format
*/
import {SandyPluginDefinition} from './SandyPluginDefinition';
import {BasePluginInstance, BasePluginClient} from './PluginBase';
import {FlipperLib} from './FlipperLib';
import {Device} from './DevicePlugin';
import {batched} from '../state/batch';
import {Atom, createState, ReadOnlyAtom} from '../state/atom';
import {
ServerAddOnControls,
EventsContract,
MethodsContract,
} from 'flipper-common';
import type {FC} from 'react';
type PreventIntersectionWith<Contract extends Record<string, any>> = {
[Key in keyof Contract]?: never;
};
type Message = {
method: string;
params?: any;
};
/**
* API available to a plugin factory
*/
export interface PluginClient<
Events extends EventsContract = {},
Methods extends MethodsContract = {},
ServerAddOnEvents extends EventsContract &
PreventIntersectionWith<Events> = {},
ServerAddOnMethods extends MethodsContract &
PreventIntersectionWith<Methods> = {},
> extends BasePluginClient<ServerAddOnEvents, ServerAddOnMethods> {
/**
* Identifier that uniquely identifies the connected application
*/
readonly appId: string;
/**
* Registered name for the connected application
*/
readonly appName: string;
readonly isConnected: boolean;
readonly connected: ReadOnlyAtom<boolean>;
/**
* the onConnect event is fired whenever the plugin is connected to it's counter part on the device.
* For most plugins this event is fired if the user selects the plugin,
* for background plugins when the initial connection is made.
*/
onConnect(cb: () => void): void;
/**
* The counterpart of the `onConnect` handler.
* Will also be fired before the plugin is cleaned up if the connection is currently active:
* - when the client disconnects
* - when the plugin is disabled
*/
onDisconnect(cb: () => void): void;
/**
* Subscribe to a specific event arriving from the device.
*
* Messages can only arrive if the plugin is enabled and connected.
* For background plugins messages will be batched and arrive the next time the plugin is connected.
*/
onMessage<Event extends keyof Events>(
event: Event,
callback: (params: Events[Event]) => void,
): void;
/**
* Subscribe to all messages arriving from the devices not handled by another listener.
*
* This handler is untyped, and onMessage should be favored over using onUnhandledMessage if the event name is known upfront.
*/
onUnhandledMessage(callback: (event: string, params: any) => void): void;
/**
* Send a message to the connected client
*/
send<Method extends keyof Methods>(
method: Method,
params: Parameters<Methods[Method]>[0],
): ReturnType<Methods[Method]>;
/**
* Checks if a method is available on the client implementation
*/
supportsMethod(method: keyof Methods): Promise<boolean>;
/**
* opens a different plugin by id, optionally providing a deeplink to bring the plugin to a certain state
*/
selectPlugin(pluginId: string, deeplinkPayload?: unknown): void;
}
/**
* Internal API exposed by Flipper, and wrapped by FlipperPluginInstance to be passed to the
* Plugin Factory. For internal purposes only
*/
export interface RealFlipperClient {
id: string;
connected: Atom<boolean>;
query: {
app: string;
os: string;
device: string;
device_id: string;
};
device: Device;
plugins: Set<string>;
isBackgroundPlugin(pluginId: string): boolean;
initPlugin(pluginId: string): void;
deinitPlugin(pluginId: string): void;
call(
api: string,
method: string,
fromPlugin: boolean,
params?: Object,
): Promise<Object>;
supportsMethod(api: string, method: string): Promise<boolean>;
}
export type PluginFactory<
Events extends EventsContract,
Methods extends MethodsContract,
ServerAddOnEvents extends EventsContract & PreventIntersectionWith<Events>,
ServerAddOnMethods extends MethodsContract & PreventIntersectionWith<Methods>,
> = (
client: PluginClient<Events, Methods, ServerAddOnEvents, ServerAddOnMethods>,
) => object;
export type FlipperPluginComponent = FC<{}>;
export class SandyPluginInstance extends BasePluginInstance {
static is(thing: any): thing is SandyPluginInstance {
return thing instanceof SandyPluginInstance;
}
/** base client provided by Flipper */
readonly realClient: RealFlipperClient;
/** client that is bound to this instance */
readonly client: PluginClient<any, any, any, any>;
/** connection alive? */
readonly connected = createState(false);
constructor(
serverAddOnControls: ServerAddOnControls,
flipperLib: FlipperLib,
definition: SandyPluginDefinition,
realClient: RealFlipperClient,
pluginKey: string,
initialStates?: Record<string, any>,
) {
super(
serverAddOnControls,
flipperLib,
definition,
realClient.device,
pluginKey,
initialStates,
);
this.realClient = realClient;
this.definition = definition;
const self = this;
this.client = {
...this.createBasePluginClient(),
get appId() {
return realClient.id;
},
get appName() {
return realClient.query.app;
},
connected: self.connected,
get isConnected() {
return self.connected.get();
},
onConnect: (cb) => {
this.events.on('connect', batched(cb));
},
onDisconnect: (cb) => {
this.events.on('disconnect', batched(cb));
},
send: async (method, params) => {
this.assertConnected();
return await realClient.call(
this.definition.id,
method as any,
true,
params as any,
);
},
onMessage: (event, cb) => {
this.events.on('event-' + event, batched(cb));
},
onUnhandledMessage: (cb) => {
this.events.on('unhandled-event', batched(cb));
},
supportsMethod: async (method) => {
return await realClient.supportsMethod(
this.definition.id,
method as any,
);
},
selectPlugin(pluginId: string, deeplink?: unknown) {
flipperLib.selectPlugin(
realClient.device,
realClient,
pluginId,
deeplink,
);
},
};
this.initializePlugin(() =>
definition.asPluginModule().plugin(this.client),
);
}
// the plugin is selected in the UI
activate() {
super.activate();
const pluginId = this.definition.id;
if (
!this.connected.get() &&
!this.realClient.isBackgroundPlugin(pluginId)
) {
this.realClient.initPlugin(pluginId); // will call connect() if needed
}
}
// the plugin is deselected in the UI
deactivate() {
super.deactivate();
const pluginId = this.definition.id;
if (this.connected.get() && !this.realClient.isBackgroundPlugin(pluginId)) {
this.realClient.deinitPlugin(pluginId);
}
}
connect() {
this.assertNotDestroyed();
if (!this.connected.get()) {
this.startServerAddOn();
this.connected.set(true);
this.events.emit('connect');
}
}
disconnect() {
this.assertNotDestroyed();
if (this.connected.get()) {
this.stopServerAddOn();
this.connected.set(false);
this.events.emit('disconnect');
}
}
destroy() {
if (this.connected.get()) {
this.realClient.deinitPlugin(this.definition.id);
}
super.destroy();
}
receiveMessages(messages: Message[]) {
messages.forEach((message) => {
if (this.events.listenerCount('event-' + message.method) > 0) {
this.events.emit('event-' + message.method, message.params);
} else {
this.events.emit('unhandled-event', message.method, message.params);
}
});
}
toJSON() {
return '[SandyPluginInstance]';
}
protected get serverAddOnOwner() {
return this.realClient.id;
}
private assertConnected() {
this.assertNotDestroyed();
// This is a better-safe-than-sorry; just the first condition should suffice
if (!this.connected.get()) {
throw new Error(
'SandyPluginInstance.assertConnected -> plugin is not connected',
);
}
if (!this.realClient.connected.get()) {
throw new Error(
'SandyPluginInstance.assertConnected -> realClient is not connected',
);
}
if (!this.device.isConnected) {
throw new Error(
'SandyPluginInstance.assertConnected -> device is not connected',
);
}
if (this.device.isArchived) {
throw new Error(
'SandyPluginInstance.assertConnected -> device is archived',
);
}
}
}

589
desktop/flipper-plugin-core/src/plugin/PluginBase.tsx Normal file
View File

@@ -0,0 +1,589 @@
/**
* Copyright (c) Meta Platforms, Inc. and affiliates.
*
* This source code is licensed under the MIT license found in the
* LICENSE file in the root directory of this source tree.
*
* @format
*/
import EventEmitter from 'eventemitter3';
import {SandyPluginDefinition} from './SandyPluginDefinition';
import {MenuEntry, NormalizedMenuEntry, normalizeMenuEntry} from './MenuEntry';
import {FlipperLib} from './FlipperLib';
import {CrashLogListener, Device, DeviceLogListener} from './DevicePlugin';
import {batched} from '../state/batch';
import {Idler} from '../utils/Idler';
import {Notification} from './Notification';
import {Logger} from '../utils/Logger';
import {CreatePasteArgs, CreatePasteResult} from './Paste';
import {
EventsContract,
MethodsContract,
ServerAddOnControls,
} from 'flipper-common';
type StateExportHandler<T = any> = (
idler: Idler,
onStatusMessage: (msg: string) => void,
) => Promise<T | undefined | void>;
type StateImportHandler<T = any> = (data: T) => void;
export interface BasePluginClient<
ServerAddOnEvents extends EventsContract = {},
ServerAddOnMethods extends MethodsContract = {},
> {
/**
* A key that uniquely identifies this plugin instance, captures the current device/client/plugin combination.
*/
readonly pluginKey: string;
readonly device: Device;
/**
* the onDestroy event is fired whenever a device is unloaded from Flipper, or a plugin is disabled.
*/
onDestroy(cb: () => void): void;
/**
* the onActivate event is fired whenever the plugin is actived in the UI
*/
onActivate(cb: () => void): void;
/**
* The counterpart of the `onActivate` handler.
*/
onDeactivate(cb: () => void): void;
/**
* Triggered when this plugin is opened through a deeplink
*/
onDeepLink(cb: (deepLink: unknown) => void): void;
/**
* Triggered when the current plugin is being exported and should create a snapshot of the state exported.
* Overrides the default export behavior and ignores any 'persist' flags of state.
*
* If an object is returned from the handler, that will be taken as export.
* Otherwise, if nothing is returned, the handler will be run, and after the handler has finished the `persist` keys of the different states will be used as export basis.
*/
onExport<T extends object>(exporter: StateExportHandler<T>): void;
/**
* Triggered directly after the plugin instance was created, if the plugin is being restored from a snapshot.
* Should be the inverse of the onExport handler
*/
onImport<T = any>(handler: StateImportHandler<T>): void;
/**
* The `onReady` event is triggered immediately after a plugin has been initialized and any pending state was restored.
* This event fires after `onImport` / the interpretation of any `persist` flags and indicates that the initialization process has finished.
* This event does not signal that the plugin is loaded in the UI yet (see `onActivated`) and does fire before deeplinks (see `onDeepLink`) are handled.
*/
onReady(handler: () => void): void;
/**
* Register menu entries in the Flipper toolbar
*/
addMenuEntry(...entry: MenuEntry[]): void;
/**
* Listener that is triggered if the underlying device emits a log message.
* Listeners established with this mechanism will automatically be cleaned up during destroy
*/
onDeviceLogEntry(cb: DeviceLogListener): () => void;
/**
* Listener that is triggered if the underlying device crashes.
* Listeners established with this mechanism will automatically be cleaned up during destroy
*/
onDeviceCrash(cb: CrashLogListener): () => void;
/**
* Creates a Paste (similar to a Github Gist).
* Facebook only function. Resolves to undefined if creating a paste failed.
*/
createPaste(
args: string | CreatePasteArgs,
): Promise<CreatePasteResult | undefined>;
/**
* Returns true if this is an internal Facebook build.
* Always returns `false` in open source
*/
readonly isFB: boolean;
/**
* Returns true if the user is taking part in the given gatekeeper.
* Always returns `false` in open source.
*/
GK(gkName: string): boolean;
/**
* Shows an urgent, system wide notification, that will also be registered in Flipper's notification pane.
* For on-screen notifications, we recommend to use either the `message` or `notification` API from `antd` directly.
*
* Clicking the notification will open this plugin. If the `action` id is set, it will be used as deeplink.
*/
showNotification(notification: Notification): void;
/**
* Writes text to the clipboard of the Operating System
*/
writeTextToClipboard(text: string): void;
/**
* Logger instance that logs information to the console, but also to the internal logging (in FB only builds) and which can be used to track performance.
*/
logger: Logger;
/**
* Triggered when a server add-on starts.
* You should send messages to the server add-on only after it connects.
* Do not forget to stop all communication when the add-on stops.
* See `onServerAddStop`.
*/
onServerAddOnStart(callback: () => void): void;
/**
* Triggered when a server add-on stops.
* You should stop all communication with the server add-on when the add-on stops.
*/
onServerAddOnStop(callback: () => void): void;
/**
* Subscribe to a specific event arriving from the server add-on.
* Messages can only arrive if the plugin is enabled and connected.
*/
onServerAddOnMessage<Event extends keyof ServerAddOnEvents & string>(
event: Event,
callback: (params: ServerAddOnEvents[Event]) => void,
): void;
/**
* Subscribe to all messages arriving from the server add-ons not handled by another listener.
*
* This handler is untyped, and onMessage should be favored over using onUnhandledMessage if the event name is known upfront.
*/
onServerAddOnUnhandledMessage(
callback: (event: string, params: any) => void,
): void;
/**
* Send a message to the server add-on
*/
sendToServerAddOn<Method extends keyof ServerAddOnMethods & string>(
method: Method,
...params: Parameters<ServerAddOnMethods[Method]> extends []
? []
: [Parameters<ServerAddOnMethods[Method]>[0]]
): ReturnType<ServerAddOnMethods[Method]>;
}
let currentPluginInstance: BasePluginInstance | undefined = undefined;
export function setCurrentPluginInstance(
instance: typeof currentPluginInstance,
) {
currentPluginInstance = instance;
}
export function getCurrentPluginInstance(): typeof currentPluginInstance {
return currentPluginInstance;
}
export interface Persistable {
serialize(): any;
deserialize(value: any): void;
}
export function registerStorageAtom(
key: string | undefined,
persistable: Persistable,
) {
if (key && getCurrentPluginInstance()) {
const {rootStates} = getCurrentPluginInstance()!;
if (rootStates[key]) {
throw new Error(
`Some other state is already persisting with key "${key}"`,
);
}
rootStates[key] = persistable;
}
}
let staticInstanceId = 1;
export abstract class BasePluginInstance {
/** generally available Flipper APIs */
readonly flipperLib: FlipperLib;
/** the original plugin definition */
definition: SandyPluginDefinition;
/** the plugin instance api as used inside components and such */
instanceApi: any;
/** the plugin public api exposed over the wire via flipper-server-companion */
companionApi?: any;
/** the device owning this plugin */
readonly device: Device;
/** the unique plugin key for this plugin instance, which is unique for this device/app?/pluginId combo */
readonly pluginKey: string;
activated = false;
destroyed = false;
private serverAddOnStarted = false;
private serverAddOnStopped = false;
readonly events = new EventEmitter();
// temporarily field that is used during deserialization
initialStates?: Record<string, any>;
// all the atoms that should be serialized when making an export / import
readonly rootStates: Record<string, Persistable> = {};
// last seen deeplink
lastDeeplink?: any;
// export handler
exportHandler?: StateExportHandler;
// import handler
importHandler?: StateImportHandler;
menuEntries: NormalizedMenuEntry[] = [];
logListeners: Symbol[] = [];
crashListeners: Symbol[] = [];
readonly instanceId = ++staticInstanceId;
constructor(
private readonly serverAddOnControls: ServerAddOnControls,
flipperLib: FlipperLib,
definition: SandyPluginDefinition,
device: Device,
pluginKey: string,
initialStates?: Record<string, any>,
) {
this.flipperLib = flipperLib;
this.definition = definition;
this.initialStates = initialStates;
this.pluginKey = pluginKey;
if (!device) {
throw new Error('Illegal State: Device has not yet been loaded');
}
this.device = device;
}
protected initializePlugin(factory: () => any) {
// To be called from constructory
setCurrentPluginInstance(this);
try {
this.instanceApi = batched(factory)();
const apiFactory = this.definition.module.API;
if (apiFactory) {
this.companionApi = apiFactory(this.instanceApi);
}
} finally {
// check if we have both an import handler and rootStates; probably dev error
if (this.importHandler && Object.keys(this.rootStates).length > 0) {
throw new Error(
`A custom onImport handler was defined for plugin '${
this.definition.id
}', the 'persist' option of states ${Object.keys(
this.rootStates,
).join(', ')} should not be set.`,
);
}
if (this.initialStates) {
try {
if (this.importHandler) {
batched(this.importHandler)(this.initialStates);
} else {
for (const key in this.rootStates) {
if (key in this.initialStates) {
this.rootStates[key].deserialize(this.initialStates[key]);
} else {
console.warn(
`Tried to initialize plugin with existing data, however data for "${key}" is missing. Was the export created with a different Flipper version?`,
);
}
}
}
} catch (e) {
const msg = `An error occurred when importing data for plugin '${this.definition.id}': '${e}`;
// msg is already specific
// eslint-disable-next-line
console.error(msg, e);
this.events.emit('error', msg);
}
}
this.initialStates = undefined;
setCurrentPluginInstance(undefined);
}
try {
this.events.emit('ready');
} catch (e) {
const msg = `An error occurred when initializing plugin '${this.definition.id}': '${e}`;
// msg is already specific
// eslint-disable-next-line
console.error(msg, e);
this.events.emit('error', msg);
}
}
protected createBasePluginClient(): BasePluginClient<any, any> {
return {
pluginKey: this.pluginKey,
device: this.device,
onActivate: (cb) => {
this.events.on('activate', batched(cb));
},
onDeactivate: (cb) => {
this.events.on('deactivate', batched(cb));
},
onDeepLink: (cb) => {
this.events.on('deeplink', batched(cb));
},
onDestroy: (cb) => {
this.events.on('destroy', batched(cb));
},
onExport: (cb) => {
if (this.exportHandler) {
throw new Error('onExport handler already set');
}
this.exportHandler = cb;
},
onImport: (cb) => {
if (this.importHandler) {
throw new Error('onImport handler already set');
}
this.importHandler = cb;
},
onReady: (cb) => {
this.events.on('ready', batched(cb));
},
addMenuEntry: (...entries) => {
for (const entry of entries) {
const normalized = normalizeMenuEntry(entry);
const idx = this.menuEntries.findIndex(
(existing) =>
existing.label === normalized.label ||
existing.action === normalized.action,
);
if (idx !== -1) {
this.menuEntries[idx] = normalizeMenuEntry(entry);
} else {
this.menuEntries.push(normalizeMenuEntry(entry));
}
if (this.activated) {
// entries added after initial registration
this.flipperLib.enableMenuEntries(this.menuEntries);
}
}
},
onDeviceLogEntry: (cb: DeviceLogListener): (() => void) => {
const handle = this.device.addLogListener(cb);
this.logListeners.push(handle);
return () => {
this.device.removeLogListener(handle);
};
},
onDeviceCrash: (cb: CrashLogListener): (() => void) => {
const handle = this.device.addCrashListener(cb);
this.crashListeners.push(handle);
return () => {
this.device.removeCrashListener(handle);
};
},
writeTextToClipboard: this.flipperLib.writeTextToClipboard,
createPaste: this.flipperLib.createPaste,
isFB: this.flipperLib.isFB,
GK: this.flipperLib.GK,
showNotification: (notification: Notification) => {
this.flipperLib.showNotification(this.pluginKey, notification);
},
logger: this.flipperLib.logger,
onServerAddOnStart: (cb) => {
this.events.on('serverAddOnStart', batched(cb));
if (this.serverAddOnStarted) {
batched(cb)();
}
},
onServerAddOnStop: (cb) => {
this.events.on('serverAddOnStop', batched(cb));
if (this.serverAddOnStopped) {
batched(cb)();
}
},
sendToServerAddOn: (method, params) =>
this.serverAddOnControls.sendMessage(
this.definition.packageName,
method,
params,
),
onServerAddOnMessage: (event, cb) => {
this.serverAddOnControls.receiveMessage(
this.definition.packageName,
event,
batched(cb),
);
},
onServerAddOnUnhandledMessage: (cb) => {
this.serverAddOnControls.receiveAnyMessage(
this.definition.packageName,
batched(cb),
);
},
};
}
// the plugin is selected in the UI
activate() {
this.assertNotDestroyed();
if (!this.activated) {
this.flipperLib.enableMenuEntries(this.menuEntries);
this.activated = true;
try {
this.events.emit('activate');
} catch (e) {
console.error(`Failed to activate plugin: ${this.definition.id}`, e);
}
this.flipperLib.logger.trackTimeSince(
`activePlugin-${this.definition.id}`,
);
}
}
deactivate() {
if (this.destroyed) {
return;
}
if (this.activated) {
this.activated = false;
this.lastDeeplink = undefined;
try {
this.events.emit('deactivate');
} catch (e) {
console.error(`Failed to deactivate plugin: ${this.definition.id}`, e);
}
}
}
destroy() {
this.assertNotDestroyed();
this.deactivate();
this.logListeners.splice(0).forEach((handle) => {
this.device.removeLogListener(handle);
});
this.crashListeners.splice(0).forEach((handle) => {
this.device.removeCrashListener(handle);
});
this.serverAddOnControls.unsubscribePlugin(this.definition.packageName);
this.events.emit('destroy');
this.destroyed = true;
}
triggerDeepLink(deepLink: unknown) {
this.assertNotDestroyed();
if (deepLink !== this.lastDeeplink) {
this.lastDeeplink = deepLink;
// we only want to trigger deeplinks after the plugin had a chance to render
setTimeout(() => {
this.events.emit('deeplink', deepLink);
}, 0);
}
}
exportStateSync() {
// This method is mainly intended for unit testing
if (this.exportHandler) {
throw new Error(
'Cannot export sync a plugin that does have an export handler',
);
}
return this.serializeRootStates();
}
private serializeRootStates() {
return Object.fromEntries(
Object.entries(this.rootStates).map(([key, atom]) => {
try {
return [key, atom.serialize()];
} catch (e) {
throw new Error(`Failed to serialize state '${key}': ${e}`);
}
}),
);
}
async exportState(
idler: Idler,
onStatusMessage: (msg: string) => void,
): Promise<Record<string, any>> {
if (this.exportHandler) {
const result = await this.exportHandler(idler, onStatusMessage);
if (result !== undefined) {
return result;
}
// intentional fall-through, the export handler merely updated the state, but prefers the default export format
}
return this.serializeRootStates();
}
isPersistable(): boolean {
return !!this.exportHandler || Object.keys(this.rootStates).length > 0;
}
protected assertNotDestroyed() {
if (this.destroyed) {
throw new Error('Plugin has been destroyed already');
}
}
abstract toJSON(): string;
protected abstract serverAddOnOwner: string;
protected startServerAddOn() {
const pluginDetails = this.definition.details;
if (pluginDetails.serverAddOn) {
this.serverAddOnControls
.start(
pluginDetails.name,
pluginDetails.isBundled
? {isBundled: true}
: {path: pluginDetails.serverAddOnEntry!},
this.serverAddOnOwner,
)
.then(() => {
this.events.emit('serverAddOnStart');
this.serverAddOnStarted = true;
})
.catch((e) => {
console.warn(
'Failed to start a server add on',
pluginDetails.name,
this.serverAddOnOwner,
e,
);
});
}
}
protected stopServerAddOn() {
const {serverAddOn, name} = this.definition.details;
if (serverAddOn) {
this.serverAddOnControls
.stop(name, this.serverAddOnOwner)
.finally(() => {
this.events.emit('serverAddOnStop');
this.serverAddOnStopped = true;
})
.catch((e) => {
console.warn(
'Failed to stop a server add on',
name,
this.serverAddOnOwner,
e,
);
});
}
}
}

139
desktop/flipper-plugin-core/src/plugin/SandyPluginDefinition.tsx Normal file
View File

@@ -0,0 +1,139 @@
/**
* Copyright (c) Meta Platforms, Inc. and affiliates.
*
* This source code is licensed under the MIT license found in the
* LICENSE file in the root directory of this source tree.
*
* @format
*/
import {ActivatablePluginDetails} from 'flipper-common';
import {PluginFactory, FlipperPluginComponent} from './Plugin';
import {DevicePluginPredicate, DevicePluginFactory} from './DevicePlugin';
export type FlipperPluginAPI<T extends (...args: any[]) => object> = (
pluginInstance: ReturnType<T>,
) => object;
export type FlipperPluginInstance<T extends (...args: any[]) => object> =
Parameters<FlipperPluginAPI<T>>[0];
/**
* FlipperPluginModule describe the exports that are provided by a typical Flipper Desktop plugin
*/
export type FlipperDevicePluginModule = {
/** predicate that determines if this plugin applies to the currently selcted device */
supportsDevice?: DevicePluginPredicate; // TODO T84453692: remove this function after some transition period in favor of BaseDevice.supportsPlugin.
/** the factory function that exposes plugin API over the wire */
API?: FlipperPluginAPI<DevicePluginFactory>;
/** the factory function that initializes a plugin instance */
devicePlugin: DevicePluginFactory;
/** the component type that can render this plugin */
Component: FlipperPluginComponent;
};
/**
* FlipperPluginModule describe the exports that are provided by a typical Flipper Desktop plugin
*/
export type FlipperPluginModule<
Factory extends PluginFactory<any, any, any, any>,
> = {
/** the factory function that exposes plugin API over the wire */
API?: FlipperPluginAPI<Factory>;
/** the factory function that initializes a plugin instance */
plugin: Factory;
/** the component type that can render this plugin */
Component: FlipperPluginComponent;
};
/**
* A sandy plugin definition represents a loaded plugin definition, storing two things:
* the loaded JS module, and the meta data (typically coming from package.json).
*
* Also delegates some of the standard plugin functionality to have a similar public static api as FlipperPlugin
*/
export class SandyPluginDefinition {
id: string;
module: FlipperPluginModule<any> | FlipperDevicePluginModule;
details: ActivatablePluginDetails;
isDevicePlugin: boolean;
constructor(
details: ActivatablePluginDetails,
module: FlipperPluginModule<any> | FlipperDevicePluginModule,
);
constructor(details: ActivatablePluginDetails, module: any) {
this.id = details.id;
this.details = details;
if (
details.pluginType === 'device' ||
module.supportsDevice ||
module.devicePlugin
) {
// device plugin
this.isDevicePlugin = true;
if (!module.devicePlugin || typeof module.devicePlugin !== 'function') {
throw new Error(
`Flipper device plugin '${this.id}' should export named function called 'devicePlugin'`,
);
}
} else {
this.isDevicePlugin = false;
if (!module.plugin || typeof module.plugin !== 'function') {
throw new Error(
`Flipper plugin '${this.id}' should export named function called 'plugin'`,
);
}
}
if (!module.Component || typeof module.Component !== 'function') {
throw new Error(
`Flipper plugin '${this.id}' should export named function called 'Component'`,
);
}
this.module = module;
this.module.Component.displayName = `FlipperPlugin(${this.id})`;
}
asDevicePluginModule(): FlipperDevicePluginModule {
if (!this.isDevicePlugin) throw new Error('Not a device plugin');
return this.module as FlipperDevicePluginModule;
}
asPluginModule(): FlipperPluginModule<any> {
if (this.isDevicePlugin) throw new Error('Not an application plugin');
return this.module as FlipperPluginModule<any>;
}
get packageName() {
return this.details.name;
}
get title() {
return this.details.title;
}
get icon() {
return this.details.icon;
}
get category() {
return this.details.category;
}
get gatekeeper() {
return this.details.gatekeeper;
}
get version() {
return this.details.version;
}
get isBundled() {
return this.details.isBundled;
}
get keyboardActions() {
// TODO: T68882551 support keyboard actions
return [];
}
}

71
desktop/flipper-plugin-core/src/state/__tests__/atom.node.tsx Normal file
View File

@@ -0,0 +1,71 @@
/**
* Copyright (c) Meta Platforms, Inc. and affiliates.
*
* This source code is licensed under the MIT license found in the
* LICENSE file in the root directory of this source tree.
*
* @format
*/
import {createState} from '../atom';
test('can subscribe to atom state changes', () => {
const state = createState('abc');
let receivedValue: string | undefined;
let receivedPrevValue: string | undefined;
const unsubscribe = state.subscribe((value, prevValue) => {
receivedValue = value;
receivedPrevValue = prevValue;
});
try {
state.set('def');
expect(receivedValue).toBe('def');
expect(receivedPrevValue).toBe('abc');
state.set('ghi');
expect(receivedValue).toBe('ghi');
expect(receivedPrevValue).toBe('def');
} finally {
unsubscribe();
}
});
test('can unsubscribe from atom state changes', () => {
const state = createState('abc');
let receivedValue: string | undefined;
let receivedPrevValue: string | undefined;
const unsubscribe = state.subscribe((value, prevValue) => {
receivedValue = value;
receivedPrevValue = prevValue;
});
try {
state.set('def');
expect(receivedValue).toBe('def');
expect(receivedPrevValue).toBe('abc');
} finally {
unsubscribe();
}
state.set('ghi');
expect(receivedValue).toBe('def');
expect(receivedPrevValue).toBe('abc');
});
test('can unsubscribe from atom state changes using unsubscribe method', () => {
const state = createState('abc');
let receivedValue: string | undefined;
let receivedPrevValue: string | undefined;
const listener = (value: string, prevValue: string) => {
receivedValue = value;
receivedPrevValue = prevValue;
};
state.subscribe(listener);
try {
state.set('def');
expect(receivedValue).toBe('def');
expect(receivedPrevValue).toBe('abc');
} finally {
state.unsubscribe(listener);
}
state.set('ghi');
expect(receivedValue).toBe('def');
expect(receivedPrevValue).toBe('abc');
});

141
desktop/flipper-plugin-core/src/state/atom.tsx Normal file
View File

@@ -0,0 +1,141 @@
/**
* Copyright (c) Meta Platforms, Inc. and affiliates.
*
* This source code is licensed under the MIT license found in the
* LICENSE file in the root directory of this source tree.
*
* @format
*/
import {produce, Draft, enableMapSet} from 'immer';
import {
getCurrentPluginInstance,
Persistable,
registerStorageAtom,
} from '../plugin/PluginBase';
import {
deserializeShallowObject,
makeShallowSerializable,
} from '../utils/shallowSerialization';
enableMapSet();
export interface ReadOnlyAtom<T> {
get(): T;
subscribe(listener: (value: T, prevValue: T) => void): () => void;
unsubscribe(listener: (value: T, prevValue: T) => void): void;
}
export interface Atom<T> extends ReadOnlyAtom<T> {
set(newValue: T): void;
update(recipe: (draft: Draft<T>) => void): void;
update<X extends T>(recipe: (draft: X) => void): void;
}
export class AtomValue<T> implements Atom<T>, Persistable {
value: T;
listeners: ((value: T, prevValue: T) => void)[] = [];
constructor(initialValue: T) {
this.value = initialValue;
}
get() {
return this.value;
}
set(nextValue: T) {
if (nextValue !== this.value) {
const prevValue = this.value;
this.value = nextValue;
this.notifyChanged(prevValue);
}
}
deserialize(value: T) {
this.set(deserializeShallowObject(value));
}
serialize() {
return makeShallowSerializable(this.get());
}
update(recipe: (draft: Draft<T>) => void) {
this.set(produce(this.value, recipe));
}
notifyChanged(prevValue: T) {
// TODO: add scheduling
this.listeners.slice().forEach((l) => l(this.value, prevValue));
}
subscribe(listener: (value: T, prevValue: T) => void) {
this.listeners.push(listener);
return () => this.unsubscribe(listener);
}
unsubscribe(listener: (value: T, prevValue: T) => void) {
const idx = this.listeners.indexOf(listener);
if (idx !== -1) {
this.listeners.splice(idx, 1);
}
}
}
type StateOptions = {
/**
* Should this state persist when exporting a plugin?
* If set, the atom will be saved / loaded under the key provided
*/
persist?: string;
/**
* Store this state in local storage, instead of as part of the plugin import / export.
* State stored in local storage is shared between the same plugin
* across multiple clients/ devices, but not actively synced.
*/
persistToLocalStorage?: boolean;
};
export function createState<T>(
initialValue: T,
options?: StateOptions,
): Atom<T>;
export function createState<T>(): Atom<T | undefined>;
export function createState(
initialValue: any = undefined,
options: StateOptions = {},
): Atom<any> {
const atom = new AtomValue(initialValue);
if (options?.persistToLocalStorage) {
syncAtomWithLocalStorage(options, atom);
} else {
registerStorageAtom(options.persist, atom);
}
return atom;
}
function syncAtomWithLocalStorage(options: StateOptions, atom: AtomValue<any>) {
if (!options?.persist) {
throw new Error(
"The 'persist' option should be set when 'persistToLocalStorage' is set",
);
}
const pluginInstance = getCurrentPluginInstance();
if (!pluginInstance) {
throw new Error(
"The 'persistToLocalStorage' option cannot be used outside a plugin definition",
);
}
const storageKey = `flipper:${pluginInstance.definition.id}:atom:${options.persist}`;
const storedValue = window.localStorage.getItem(storageKey);
if (storedValue != null) {
atom.deserialize(JSON.parse(storedValue));
}
atom.subscribe(() => {
window.localStorage.setItem(storageKey, JSON.stringify(atom.serialize()));
});
}
export function isAtom(value: any): value is Atom<any> {
return value instanceof AtomValue;
}

29
desktop/flipper-plugin-core/src/state/batch.tsx Normal file
View File

@@ -0,0 +1,29 @@
/**
* Copyright (c) Meta Platforms, Inc. and affiliates.
*
* This source code is licensed under the MIT license found in the
* LICENSE file in the root directory of this source tree.
*
* @format
*/
export let batch: (callback: (...args: any[]) => void) => void = (callback) =>
callback();
export const setBatchedUpdateImplementation = (
impl: (callback: (...args: any[]) => void) => void,
) => {
batch = impl;
};
export function batched<T extends Function>(fn: T): T;
export function batched(fn: any) {
return function (this: any) {
let res: any;
batch(() => {
// eslint-disable-next-line
res = fn.apply(this, arguments);
});
return res;
};
}

43
desktop/flipper-plugin-core/src/state/createDataSource.tsx Normal file
View File

@@ -0,0 +1,43 @@
/**
* Copyright (c) Meta Platforms, Inc. and affiliates.
*
* This source code is licensed under the MIT license found in the
* LICENSE file in the root directory of this source tree.
*
* @format
*/
import {
DataSource,
createDataSource as baseCreateDataSource,
DataSourceOptions as BaseDataSourceOptions,
DataSourceOptionKey as BaseDataSourceOptionKey,
} from '../data-source/DataSource';
import {registerStorageAtom} from '../plugin/PluginBase';
type DataSourceOptions = BaseDataSourceOptions & {
/**
* Should this state persist when exporting a plugin?
* If set, the dataSource will be saved / loaded under the key provided
*/
persist?: string;
};
export function createDataSource<T, Key extends keyof T>(
initialSet: readonly T[],
options: DataSourceOptions & BaseDataSourceOptionKey<Key>,
): DataSource<T, T[Key] extends string | number ? T[Key] : never>;
export function createDataSource<T>(
initialSet?: readonly T[],
options?: DataSourceOptions,
): DataSource<T, never>;
export function createDataSource<T, Key extends keyof T>(
initialSet: readonly T[] = [],
options?: DataSourceOptions & BaseDataSourceOptionKey<Key>,
): DataSource<T, T[Key] extends string | number ? T[Key] : never> {
const ds = options
? baseCreateDataSource(initialSet, options)
: baseCreateDataSource(initialSet);
registerStorageAtom(options?.persist, ds);
return ds;
}

209
desktop/flipper-plugin-core/src/test-utils/test-utils.tsx Normal file
View File

@@ -0,0 +1,209 @@
/**
* Copyright (c) Meta Platforms, Inc. and affiliates.
*
* This source code is licensed under the MIT license found in the
* LICENSE file in the root directory of this source tree.
*
* @format
*/
import {
BundledPluginDetails,
fsConstants,
InstalledPluginDetails,
} from 'flipper-common';
import {FlipperServer, FlipperServerCommands} from 'flipper-common';
import {Device} from '../plugin/DevicePlugin';
import {FlipperLib} from '../plugin/FlipperLib';
import {PluginFactory} from '../plugin/Plugin';
import {
FlipperDevicePluginModule,
FlipperPluginModule,
SandyPluginDefinition,
} from '../plugin/SandyPluginDefinition';
import {stubLogger} from '../utils/Logger';
declare const process: any;
export interface StartPluginOptions {
initialState?: Record<string, any>;
isArchived?: boolean;
isBackgroundPlugin?: boolean;
startUnactivated?: boolean;
/** Provide a set of unsupported methods to simulate older clients that don't support certain methods yet */
unsupportedMethods?: string[];
/**
* Provide a set of GKs that are enabled in this test.
*/
GKs?: string[];
testDevice?: Device;
}
export function createStubFunction(): jest.Mock<any, any> {
// we shouldn't be usign jest.fn() outside a unit test, as it would not resolve / cause jest to be bundled up!
if (typeof jest !== 'undefined') {
return jest.fn();
}
return (() => {
console.warn('Using a stub function outside a test environment!');
}) as any;
}
export function createMockFlipperLib(options?: StartPluginOptions): FlipperLib {
return {
isFB: false,
logger: stubLogger,
enableMenuEntries: createStubFunction(),
createPaste: createStubFunction(),
GK(gk: string) {
return options?.GKs?.includes(gk) || false;
},
selectPlugin: createStubFunction(),
writeTextToClipboard: createStubFunction(),
openLink: createStubFunction(),
showNotification: createStubFunction(),
exportFile: createStubFunction(),
importFile: createStubFunction(),
paths: {
appPath: process.cwd(),
homePath: `/dev/null`,
staticPath: process.cwd(),
tempPath: `/dev/null`,
},
environmentInfo: {
os: {
arch: 'Test',
unixname: 'test',
platform: 'linux',
},
},
intern: {
graphGet: createStubFunction(),
graphPost: createStubFunction(),
},
remoteServerContext: {
childProcess: {
exec: createStubFunction(),
},
fs: {
access: createStubFunction(),
pathExists: createStubFunction(),
unlink: createStubFunction(),
mkdir: createStubFunction(),
rm: createStubFunction(),
copyFile: createStubFunction(),
constants: fsConstants,
stat: createStubFunction(),
readlink: createStubFunction(),
readFile: createStubFunction(),
readFileBinary: createStubFunction(),
writeFile: createStubFunction(),
writeFileBinary: createStubFunction(),
},
downloadFile: createStubFunction(),
},
};
}
export function createMockPluginDetails(
details?: Partial<InstalledPluginDetails>,
): InstalledPluginDetails {
return {
id: 'TestPlugin',
dir: '',
name: 'TestPlugin',
specVersion: 0,
entry: '',
isBundled: false,
isActivatable: true,
main: '',
source: '',
title: 'Testing Plugin',
version: '',
...details,
};
}
export function createTestPlugin<T extends PluginFactory<any, any, any, any>>(
implementation: Pick<FlipperPluginModule<T>, 'plugin'> &
Partial<FlipperPluginModule<T>>,
details?: Partial<InstalledPluginDetails>,
) {
return new SandyPluginDefinition(
createMockPluginDetails({
pluginType: 'client',
...details,
}),
{
Component() {
return null;
},
...implementation,
},
);
}
export function createTestDevicePlugin(
implementation: Pick<FlipperDevicePluginModule, 'devicePlugin'> &
Partial<FlipperDevicePluginModule>,
details?: Partial<InstalledPluginDetails>,
) {
return new SandyPluginDefinition(
createMockPluginDetails({
pluginType: 'device',
...details,
}),
{
supportsDevice() {
return true;
},
Component() {
return null;
},
...implementation,
},
);
}
export function createMockBundledPluginDetails(
details?: Partial<BundledPluginDetails>,
): BundledPluginDetails {
return {
id: 'TestBundledPlugin',
name: 'TestBundledPlugin',
specVersion: 0,
pluginType: 'client',
isBundled: true,
isActivatable: true,
main: '',
source: '',
title: 'Testing Bundled Plugin',
version: '',
...details,
};
}
export function createFlipperServerMock(
overrides?: Partial<FlipperServerCommands>,
): FlipperServer {
return {
async connect() {},
on: createStubFunction(),
off: createStubFunction(),
exec: jest
.fn()
.mockImplementation(
async (cmd: keyof FlipperServerCommands, ...args: any[]) => {
if (overrides?.[cmd]) {
return (overrides[cmd] as any)(...args);
}
console.warn(
`Empty server response stubbed for command '${cmd}', set 'getRenderHostInstance().flipperServer.exec' in your test to override the behavior.`,
);
return undefined;
},
),
close: createStubFunction(),
};
}

15
desktop/flipper-plugin-core/src/utils/Idler.tsx Normal file
View File

@@ -0,0 +1,15 @@
/**
* Copyright (c) Meta Platforms, Inc. and affiliates.
*
* This source code is licensed under the MIT license found in the
* LICENSE file in the root directory of this source tree.
*
* @format
*/
export interface Idler {
shouldIdle(): boolean;
idle(): Promise<void>;
cancel(): void;
isCancelled(): boolean;
}

32
desktop/flipper-plugin-core/src/utils/Logger.tsx Normal file
View File

@@ -0,0 +1,32 @@
/**
* Copyright (c) Meta Platforms, Inc. and affiliates.
*
* This source code is licensed under the MIT license found in the
* LICENSE file in the root directory of this source tree.
*
* @format
*/
import {Logger} from 'flipper-common';
export {Logger} from 'flipper-common';
export const stubLogger: Logger = {
track() {},
trackTimeSince() {},
info() {
// eslint-disable-next-line
console.log.apply(console, arguments as any);
},
warn() {
// eslint-disable-next-line
console.warn.apply(console, arguments as any);
},
error() {
// eslint-disable-next-line
console.error.apply(console, arguments as any);
},
debug() {
// eslint-disable-next-line
console.debug.apply(console, arguments as any);
},
};

255
desktop/flipper-plugin-core/src/utils/__tests__/shallowSerialization.node.tsx Normal file
View File

@@ -0,0 +1,255 @@
/**
* Copyright (c) Meta Platforms, Inc. and affiliates.
*
* This source code is licensed under the MIT license found in the
* LICENSE file in the root directory of this source tree.
*
* @format
*/
import {
makeShallowSerializable,
deserializeShallowObject,
} from '../shallowSerialization';
import mockConsole from 'jest-mock-console';
class TestObject extends Object {
constructor(title: Object, map?: Map<any, any>, set?: Set<any>) {
super();
this.title = title;
this.map = map;
this.set = set;
}
title: Object;
map?: Map<any, any>;
set?: Set<any>;
}
test('test cyclic data structure', () => {
const a: any = {x: 0, b: {c: []}};
a.b.c.push(a);
expect(() => {
makeShallowSerializable(a);
}).toThrowErrorMatchingInlineSnapshot(
`"Cycle detected: object at path '.b.c.0' is referring to itself: '[object Object]'"`,
);
});
test('test shared data structure', () => {
const restoreConsole = mockConsole();
try {
const a = {hello: 'world'};
const b = {x: a, y: a};
const res = JSON.parse(JSON.stringify(makeShallowSerializable(b)));
expect(res).toEqual({
x: {hello: 'world'},
y: {hello: 'world'},
});
expect(b.x).toBe(b.y);
expect(res.x).not.toBe(res.y);
// @ts-ignore
expect(console.warn.mock.calls).toMatchInlineSnapshot(`
Array [
Array [
"Duplicate value, object lives at path '.y', but also at path '.x': '[object Object]'. This might not behave correct after import and lead to unnecessary big exports.",
],
]
`);
} finally {
restoreConsole();
}
});
test('test makeObjectSerializable function for unnested object with no Set and Map', () => {
const obj = {key1: 'value1', key2: 'value2'};
const output = makeShallowSerializable(obj);
expect(output).toEqual(obj);
// Testing numbers
const obj2 = {key1: 1, key2: 2};
const output2 = makeShallowSerializable(obj2);
expect(output2).toEqual(obj2);
});
test('makeObjectSerializable function for unnested object with values which returns false when put in an if condition', () => {
const obj2 = {key1: 0, key2: ''};
const output2 = makeShallowSerializable(obj2);
return expect(output2).toEqual(obj2);
});
test('test deserializeShallowObject function for unnested object with no Set and Map', () => {
const obj = {key1: 'value1', key2: 'value2'};
const output = deserializeShallowObject(obj);
expect(output).toEqual(obj);
// Testing numbers
const obj2 = {key1: 1, key2: 2};
const output2 = deserializeShallowObject(obj2);
expect(output2).toEqual(obj2);
});
test('test makeObjectSerializable and deserializeShallowObject function for nested object with no Set and Map', () => {
const subObj = {key1: 'value1', key2: 'value2'};
const subObj2 = {key21: 'value21', key22: 'value22'};
const obj = {key1: subObj, key2: subObj2};
const output = makeShallowSerializable(obj);
expect(output).toEqual(obj);
expect(deserializeShallowObject(output)).toEqual(obj);
const subObjNum = {key1: 1, key2: 2};
const subObjNum2 = {key21: 21, key22: 22};
const obj2 = {key1: subObjNum, key2: subObjNum2};
const output2 = makeShallowSerializable(obj2);
expect(output2).toEqual(obj2);
expect(deserializeShallowObject(output2)).toEqual(obj2);
});
test('test makeObjectSerializable and deserializeShallowObject function for Map and Set with no nesting', () => {
const map = new Map([
['k1', 'v1'],
['k2', 'v2'],
]);
const output = makeShallowSerializable(map);
const expected = {
__flipper_object_type__: 'Map',
data: [
['k1', 'v1'],
['k2', 'v2'],
],
};
expect(output).toEqual(expected);
expect(deserializeShallowObject(output)).toEqual(map);
const set = new Set([1, 2, 3, 4, 5, 6, 5, 4, 3, 2, 1]);
const outputSet = makeShallowSerializable(set);
const expectedSet = {
__flipper_object_type__: 'Set',
data: [1, 2, 3, 4, 5, 6],
};
expect(outputSet).toEqual(expectedSet);
expect(deserializeShallowObject(outputSet)).toEqual(set);
});
test('test makeObjectSerializable and deserializeShallowObject function for Map and Set with nesting', () => {
const map = new Map([
[{title: 'k1'}, {title: 'v1'}],
[{title: 'k2'}, {title: 'v2'}],
]);
const output = makeShallowSerializable(map);
const expected = {
__flipper_object_type__: 'Map',
data: [
[{title: 'k1'}, {title: 'v1'}],
[{title: 'k2'}, {title: 'v2'}],
],
};
expect(output).toEqual(expected);
expect(deserializeShallowObject(output)).toEqual(map);
const set = new Set([
{title: '1'},
{title: '2'},
{title: '3'},
{title: '4'},
{title: '5'},
{title: '6'},
]);
const outputSet = makeShallowSerializable(set);
const expectedSet = {
__flipper_object_type__: 'Set',
data: [
{title: '1'},
{title: '2'},
{title: '3'},
{title: '4'},
{title: '5'},
{title: '6'},
],
};
expect(outputSet).toEqual(expectedSet);
expect(deserializeShallowObject(outputSet)).toEqual(set);
});
test('test makeObjectSerializable and deserializeShallowObject function for custom Object', () => {
const obj = new TestObject('title');
expect(() => {
makeShallowSerializable(obj);
}).toThrowErrorMatchingInlineSnapshot(
`"Unserializable object type (TestObject) at path '.': [object Object]."`,
);
});
test('test makeObjectSerializable and deserializeShallowObject object with map', () => {
const nestedObjWithMap = {
map: new Map([
['k1', 'v1'],
['k2', 'v2'],
]),
};
expect(() => {
makeShallowSerializable(nestedObjWithMap);
}).toThrowErrorMatchingInlineSnapshot(
`"Unserializable object type (Map) at path '.map': [object Map]."`,
);
});
test('test makeObjectSerializable and deserializeShallowObject function for Array as input', () => {
const arr = [1, 2, 4, 5];
const output = makeShallowSerializable(arr);
expect(output).toEqual(arr);
expect(deserializeShallowObject(output)).toEqual(arr);
const arrMap = [
new Map([
['a1', 'v1'],
['a2', 'v2'],
]),
];
expect(() => {
makeShallowSerializable(arrMap);
}).toThrowErrorMatchingInlineSnapshot(
`"Unserializable object type (Map) at path '.0': [object Map]."`,
);
});
test('test serialize and deserializeShallowObject function for non Object input', () => {
expect(makeShallowSerializable('octopus')).toEqual('octopus');
expect(deserializeShallowObject(makeShallowSerializable('octopus'))).toEqual(
'octopus',
);
expect(makeShallowSerializable(24567)).toEqual(24567);
expect(deserializeShallowObject(makeShallowSerializable(24567))).toEqual(
24567,
);
});
// dates on windows don't support changed timezones
test.unix(
'test makeObjectSerializable and deserializeShallowObject function for Date input',
() => {
const date = new Date(2021, 1, 29, 10, 31, 7, 205);
expect(makeShallowSerializable(date)).toMatchInlineSnapshot(`
Object {
"__flipper_object_type__": "Date",
"data": 1614555067205,
}
`);
expect(deserializeShallowObject(makeShallowSerializable(date))).toEqual(
date,
);
},
);
test('test makeObjectSerializable and deserializeShallowObject function for Map of Sets', () => {
const map = new Map([
['k1', new Set([1, 2, 3, 4, 5, 6])],
[new Set([1, 2]), new Map([['k3', 'v3']])],
] as any);
expect(() => {
makeShallowSerializable(map);
}).toThrowErrorMatchingInlineSnapshot(
`"Unserializable object type (Set) at path '.01': [object Set]."`,
);
});

285
desktop/flipper-plugin-core/src/utils/path.tsx Normal file
View File

@@ -0,0 +1,285 @@
/**
* Copyright (c) Meta Platforms, Inc. and affiliates.
*
* This source code is licensed under the MIT license found in the
* LICENSE file in the root directory of this source tree.
*
* @format
*/
// Partial clone of the POSIX part of https://github.com/nodejs/node/blob/master/lib/path.js
// Docs are copied from https://github.com/nodejs/node/blob/master/doc/api/path.md
const CHAR_DOT = 46;
const CHAR_FORWARD_SLASH = 47;
function isPosixPathSeparator(code: number) {
return code === CHAR_FORWARD_SLASH;
}
// Resolves . and .. elements in a path with directory names
function normalizeString(
path: string,
allowAboveRoot: boolean,
separator: string,
isPathSeparator: (code: number) => boolean,
): string {
let res = '';
let lastSegmentLength = 0;
let lastSlash = -1;
let dots = 0;
let code = 0;
for (let i = 0; i <= path.length; ++i) {
if (i < path.length) code = path.charCodeAt(i);
else if (isPathSeparator(code)) break;
else code = CHAR_FORWARD_SLASH;
if (isPathSeparator(code)) {
if (lastSlash === i - 1 || dots === 1) {
// NOOP
} else if (dots === 2) {
if (
res.length < 2 ||
lastSegmentLength !== 2 ||
res.charCodeAt(res.length - 1) !== CHAR_DOT ||
res.charCodeAt(res.length - 2) !== CHAR_DOT
) {
if (res.length > 2) {
const lastSlashIndex = res.lastIndexOf(separator);
if (lastSlashIndex === -1) {
res = '';
lastSegmentLength = 0;
} else {
res = res.slice(0, lastSlashIndex);
lastSegmentLength = res.length - 1 - res.lastIndexOf(separator);
}
lastSlash = i;
dots = 0;
continue;
} else if (res.length !== 0) {
res = '';
lastSegmentLength = 0;
lastSlash = i;
dots = 0;
continue;
}
}
if (allowAboveRoot) {
res += res.length > 0 ? `${separator}..` : '..';
lastSegmentLength = 2;
}
} else {
if (res.length > 0)
res += `${separator}${path.slice(lastSlash + 1, i)}`;
else res = path.slice(lastSlash + 1, i);
lastSegmentLength = i - lastSlash - 1;
}
lastSlash = i;
dots = 0;
} else if (code === CHAR_DOT && dots !== -1) {
++dots;
} else {
dots = -1;
}
}
return res;
}
/**
* The path.join() method joins all given path segments together using the platform-specific separator as a delimiter, then normalizes the resulting path.
* Zero-length path segments are ignored. If the joined path string is a zero-length string then '.' will be returned, representing the current working directory.
*
* @example
*
* path.join('/foo', 'bar', 'baz/asdf', 'quux', '..');
* Returns: '/foo/bar/baz/asdf'
*/
export function join(...args: string[]): string {
if (args.length === 0) return '.';
let joined;
for (let i = 0; i < args.length; ++i) {
const arg = args[i];
if (arg.length > 0) {
if (joined === undefined) joined = arg;
else joined += `/${arg}`;
}
}
if (joined === undefined) return '.';
return normalize(joined);
}
/**
* The path.normalize() method normalizes the given path, resolving '..' and '.' segments.
* When multiple, sequential path segment separation characters are found (e.g. /), they are replaced by a single instance of /. Trailing separators are preserved.
* If the path is a zero-length string, '.' is returned, representing the current working directory.
*
* @example
* path.normalize('/foo/bar//baz/asdf/quux/..');
* Returns: '/foo/bar/baz/asdf'
*/
export function normalize(path: string): string {
if (path.length === 0) return '.';
const isAbsolute = path.charCodeAt(0) === CHAR_FORWARD_SLASH;
const trailingSeparator =
path.charCodeAt(path.length - 1) === CHAR_FORWARD_SLASH;
// Normalize the path
path = normalizeString(path, !isAbsolute, '/', isPosixPathSeparator);
if (path.length === 0) {
if (isAbsolute) return '/';
return trailingSeparator ? './' : '.';
}
if (trailingSeparator) path += '/';
return isAbsolute ? `/${path}` : path;
}
/**
* The path.extname() method returns the extension of the path, from the last occurrence of the . (period) character to end of string in the last portion of the path. If there is no . in the last portion of the path, or if there are no . characters other than the first character of the basename of path (see path.basename()) , an empty string is returned.
*
* @example
* path.extname('index.html');
* Returns: '.html'
*
* path.extname('index.coffee.md');
* Returns: '.md'
*
* path.extname('index.');
* Returns: '.'
*
* path.extname('index');
* Returns: ''
*
* path.extname('.index');
* Returns: ''
*
* path.extname('.index.md');
* Returns: '.md'
*/
export function extname(path: string): string {
let startDot = -1;
let startPart = 0;
let end = -1;
let matchedSlash = true;
// Track the state of characters (if any) we see before our first dot and
// after any path separator we find
let preDotState = 0;
for (let i = path.length - 1; i >= 0; --i) {
const code = path.charCodeAt(i);
if (code === CHAR_FORWARD_SLASH) {
// If we reached a path separator that was not part of a set of path
// separators at the end of the string, stop now
if (!matchedSlash) {
startPart = i + 1;
break;
}
continue;
}
if (end === -1) {
// We saw the first non-path separator, mark this as the end of our
// extension
matchedSlash = false;
end = i + 1;
}
if (code === CHAR_DOT) {
// If this is our first dot, mark it as the start of our extension
if (startDot === -1) startDot = i;
else if (preDotState !== 1) preDotState = 1;
} else if (startDot !== -1) {
// We saw a non-dot and non-path separator before our dot, so we should
// have a good chance at having a non-empty extension
preDotState = -1;
}
}
if (
startDot === -1 ||
end === -1 ||
// We saw a non-dot character immediately before the dot
preDotState === 0 ||
// The (right-most) trimmed path component is exactly '..'
(preDotState === 1 && startDot === end - 1 && startDot === startPart + 1)
) {
return '';
}
return path.slice(startDot, end);
}
/**
* The path.basename() method returns the last portion of a path, similar to the Unix basename command. Trailing directory separators are ignored.
*
* @example
* path.basename('/foo/bar/baz/asdf/quux.html');
* Returns: 'quux.html'
*
* path.basename('/foo/bar/baz/asdf/quux.html', '.html');
* Returns: 'quux'
*/
export function basename(path: string, ext?: string) {
let start = 0;
let end = -1;
let matchedSlash = true;
if (ext !== undefined && ext.length > 0 && ext.length <= path.length) {
if (ext === path) return '';
let extIdx = ext.length - 1;
let firstNonSlashEnd = -1;
for (let i = path.length - 1; i >= 0; --i) {
const code = path.charCodeAt(i);
if (code === CHAR_FORWARD_SLASH) {
// If we reached a path separator that was not part of a set of path
// separators at the end of the string, stop now
if (!matchedSlash) {
start = i + 1;
break;
}
} else {
if (firstNonSlashEnd === -1) {
// We saw the first non-path separator, remember this index in case
// we need it if the extension ends up not matching
matchedSlash = false;
firstNonSlashEnd = i + 1;
}
if (extIdx >= 0) {
// Try to match the explicit extension
if (code === ext.charCodeAt(extIdx)) {
if (--extIdx === -1) {
// We matched the extension, so mark this as the end of our path
// component
end = i;
}
} else {
// Extension does not match, so our result is the entire path
// component
extIdx = -1;
end = firstNonSlashEnd;
}
}
}
}
if (start === end) end = firstNonSlashEnd;
else if (end === -1) end = path.length;
return path.slice(start, end);
}
for (let i = path.length - 1; i >= 0; --i) {
if (path.charCodeAt(i) === CHAR_FORWARD_SLASH) {
// If we reached a path separator that was not part of a set of path
// separators at the end of the string, stop now
if (!matchedSlash) {
start = i + 1;
break;
}
} else if (end === -1) {
// We saw the first non-path separator, mark this as the end of our
// path component
matchedSlash = false;
end = i + 1;
}
}
if (end === -1) return '';
return path.slice(start, end);
}

16
desktop/flipper-plugin-core/src/utils/safeStringify.tsx Normal file
View File

@@ -0,0 +1,16 @@
/**
* Copyright (c) Meta Platforms, Inc. and affiliates.
*
* This source code is licensed under the MIT license found in the
* LICENSE file in the root directory of this source tree.
*
* @format
*/
export function safeStringify(value: any) {
try {
return JSON.stringify(value, null, 2);
} catch (e) {
return '<Failed to serialize: ' + e + '>';
}
}

186
desktop/flipper-plugin-core/src/utils/shallowSerialization.tsx Normal file
View File

@@ -0,0 +1,186 @@
/**
* Copyright (c) Meta Platforms, Inc. and affiliates.
*
* This source code is licensed under the MIT license found in the
* LICENSE file in the root directory of this source tree.
*
* @format
*/
import {isProduction} from 'flipper-common';
/**
* makeShallowSerializable will prepare common data structures, like Map and Set, for JSON serialization.
* However, this will happen only for the root object and not recursively to keep things efficiently.
*
* The function does not take care of actual stringification; use JSON.serialize.
*/
export function makeShallowSerializable(obj: any): any {
if (!obj || typeof obj !== 'object') {
assertSerializable(obj);
return obj;
}
if (obj instanceof Map) {
const data = Array.from(obj.entries());
assertSerializable(data);
return {
__flipper_object_type__: 'Map',
data,
};
} else if (obj instanceof Set) {
const data = Array.from(obj.values());
assertSerializable(data);
return {
__flipper_object_type__: 'Set',
data,
};
} else if (obj instanceof Date) {
return {
__flipper_object_type__: 'Date',
data: obj.getTime(),
};
} else {
assertSerializable(obj);
return obj;
}
}
/**
* Inverse of makeShallowSerializable
*/
export function deserializeShallowObject(obj: any): any {
if (!obj || typeof obj !== 'object') {
return obj;
}
if (obj['__flipper_object_type__']) {
const type = obj['__flipper_object_type__'];
switch (type) {
case 'Map': {
return new Map(obj.data);
}
case 'Set': {
return new Set(obj.data);
}
case 'Date':
return new Date(obj.data);
}
}
return obj;
}
/**
* Asserts a value is JSON serializable.
* Will print a warning if a value is JSON serializable, but isn't a pure tree
*/
export function assertSerializable(obj: any) {
if (isProduction()) {
return;
}
// path to current object
const path: string[] = [];
// current object stack
const stack = new Set<any>();
// past objects, object -> path to reach it
const seen = new Set<any>();
// to safe a lot of memory allocations, if we find a duplicate, we just start over again to search for the first,
// rather than storing all paths at first encounter
let duplicateFound = false;
let duplicatePath: string[] | undefined;
let duplicateObject: any = undefined;
let done = false;
function check(value: any) {
if (value === null || done) {
return;
}
switch (typeof value) {
case 'undefined':
// undefined is not strictly speaking serializable, but behaves fine.
// JSON.stringify({x : undefined}) ==> '{}'
break;
case 'boolean':
case 'number':
case 'string':
break;
case 'object':
// A cycle is truly not serializable, as it would create an unending serialization loop...
if (stack.has(value)) {
throw new Error(
`Cycle detected: object at path '.${path.join(
'.',
)}' is referring to itself: '${value}'`,
);
}
// Encountering an object multiple times is bad, as reference equality will be lost upon
// deserialization, so the data isn't properly normalised.
// But it *might* work fine, and can serialize, so we just warn
// Warning is only printed during the second check loop, so that we know *both* paths
// - Second walk (which finds first object)
if (duplicateFound && duplicateObject && value === duplicateObject) {
console.warn(
`Duplicate value, object lives at path '.${duplicatePath!.join(
'.',
)}', but also at path '.${path!.join(
'.',
)}': '${value}'. This might not behave correct after import and lead to unnecessary big exports.`,
);
done = true; // no need to finish the second walk
break;
}
// - First walk (which detects the duplicate and stores location of duplicate)
if (!duplicateFound) {
if (seen.has(value)) {
duplicateFound = true;
duplicateObject = value;
duplicatePath = path.slice();
}
seen.add(value);
}
stack.add(value);
const proto = Object.getPrototypeOf(value);
if (Array.isArray(value)) {
value.forEach((child, index) => {
path.push('' + index);
check(child);
path.pop();
});
} else if (proto === null || proto === Object.prototype) {
for (const key in value) {
path.push(key);
check(value[key]);
path.pop();
}
} else {
throw new Error(
`Unserializable object type (${
proto?.constructor?.name ?? 'Unknown'
}) at path '.${path.join('')}': ${value}.`,
);
}
stack.delete(value);
break;
case 'bigint':
case 'function':
case 'symbol':
default:
throw new Error(
`Unserializable value (${typeof value}) at path '.${path.join(
'.',
)}': '${value}'`,
);
}
}
check(obj);
// if there is a duplicate found, re-walk the tree so that we can print both of the paths and report it
// this setup is slightly more confusion in code than walking once and storing past paths,
// but a lot more efficient :)
if (duplicateFound) {
path.splice(0);
seen.clear();
stack.clear();
check(obj);
}
}