@dxos/echo-db 2.29.2-dev.8c2ad8e5 → 2.29.2-dev.f6ed60b8

package/src/api/database.ts

@@ -14,16 +14,16 @@ import { DatabaseBackend, DataServiceHost, ItemManager } from '../database';
 import { Entity } from './entity';
 import { Item } from './item';
 import { Link } from './link';
-import { RootFilter, Selection, createSelector } from './selection';
+import { RootFilter, Selection, createSelection } from './selection';
 
-export interface ItemCreationOptions<M extends Model> {
+export interface CreateItemOption<M extends Model> {
   model?: ModelConstructor<M>
   type?: ItemType
   parent?: ItemID
   props?: any // TODO(marik-d): Type this better. Rename properties?
 }
 
-export interface LinkCreationOptions<M extends Model, L extends Model, R extends Model> {
+export interface CreateLinkOptions<M extends Model, L extends Model, R extends Model> {
   model?: ModelConstructor<M>
   type?: ItemType
   source: Item<L>
@@ -31,20 +31,19 @@ export interface LinkCreationOptions<M extends Model, L extends Model, R extends
   props?: any // TODO(marik-d): Type this better.
 }
 
-enum State {
-  INITIAL = 'INITIAL',
-  OPEN = 'OPEN',
+export enum State {
+  NULL = 'NULL',
+  INITIALIZED = 'INITIALIZED',
   DESTROYED = 'DESTROYED',
 }
 
 /**
- * Represents a shared dataset containing queryable Items that are constructed from an ordered stream
- * of mutations.
+ * Represents a shared dataset containing queryable Items that are constructed from an ordered stream of mutations.
  */
 export class Database {
   private readonly _itemManager: ItemManager;
 
-  private _state = State.INITIAL;
+  private _state = State.NULL;
 
   /**
    * Creates a new database instance. `database.initialize()` must be called afterwards to complete the initialization.
@@ -57,6 +56,10 @@ export class Database {
     this._itemManager = new ItemManager(this._modelFactory, memberKey, this._backend.getWriteStream());
   }
 
+  get state () {
+    return this._state;
+  }
+
   get isReadOnly () {
     return this._backend.isReadOnly;
   }
@@ -71,26 +74,26 @@ export class Database {
 
   /**
    * Fired immediately after any update in the entities.
-   *
    * If the information about which entity got updated is not required prefer using `update`.
    */
+  // TODO(burdon): Unused?
   get entityUpdate (): Event<Entity<any>> {
     return this._itemManager.update;
   }
 
   @synchronized
   async initialize () {
-    if (this._state !== State.INITIAL) {
+    if (this._state !== State.NULL) {
       throw new Error('Invalid state: database was already initialized.');
     }
 
     await this._backend.open(this._itemManager, this._modelFactory);
-    this._state = State.OPEN;
+    this._state = State.INITIALIZED;
   }
 
   @synchronized
   async destroy () {
-    if (this._state === State.DESTROYED || this._state === State.INITIAL) {
+    if (this._state === State.DESTROYED || this._state === State.NULL) {
       return;
     }
 
@@ -101,7 +104,7 @@ export class Database {
   /**
    * Creates a new item with the given queryable type and model.
    */
-  async createItem <M extends Model<any>> (options: ItemCreationOptions<M>): Promise<Item<M>> {
+  async createItem <M extends Model<any>> (options: CreateItemOption<M> = {}): Promise<Item<M>> {
     this._assertInitialized();
     if (!options.model) {
       options.model = ObjectModel as any as ModelConstructor<M>;
@@ -109,22 +112,21 @@ export class Database {
 
     validateModelClass(options.model);
 
-    if (options.type && typeof options.type !== 'string') {
+    if (options.type && typeof options.type !== 'string' as ItemType) {
       throw new TypeError('Invalid type.');
     }
 
-    if (options.parent && typeof options.parent !== 'string') {
+    if (options.parent && typeof options.parent !== 'string' as ItemID) {
       throw new TypeError('Optional parent item id must be a string id of an existing item.');
     }
 
     // TODO(burdon): Get modelType from somewhere other than `ObjectModel.meta.type`.
-    const item = await this._itemManager.createItem(
+    return await this._itemManager.createItem(
       options.model.meta.type, options.type, options.parent, options.props) as any;
-    return item;
   }
 
   async createLink<M extends Model<any>, S extends Model<any>, T extends Model<any>> (
-    options: LinkCreationOptions<M, S, T>
+    options: CreateLinkOptions<M, S, T>
   ): Promise<Link<M, S, T>> {
     this._assertInitialized();
 
@@ -135,15 +137,12 @@ export class Database {
 
     validateModelClass(model);
 
-    if (options.type && typeof options.type !== 'string') {
+    if (options.type && typeof options.type !== 'string' as ItemType) {
       throw new TypeError('Invalid type.');
     }
 
-    assert(options.source instanceof Item);
-    assert(options.target instanceof Item);
-
-    return this._itemManager
-      .createLink(model.meta.type, options.type, options.source.id, options.target.id, options.props);
+    return this._itemManager.createLink(
+      model.meta.type, options.type, options.source.id, options.target.id, options.props);
   }
 
   /**
@@ -158,11 +157,12 @@ export class Database {
   /**
    * Waits for item matching the filter to be present and returns it.
    */
+  // TODO(burdon): Generalize waitForCondition.
   async waitForItem<T extends Model<any>> (filter: RootFilter): Promise<Item<T>> {
-    const result = this.select(filter).query();
+    const result = this.select(filter).exec();
     await result.update.waitForCondition(() => result.entities.length > 0);
     const item = result.expectOne();
-    assert(item, 'Possible condition detected.');
+    assert(item, 'Possible race condition detected.');
     return item as Item<T>;
   }
 
@@ -171,7 +171,7 @@ export class Database {
    * @param filter
    */
   select (filter?: RootFilter): Selection<Item<any>> {
-    return createSelector<void>(
+    return createSelection<void>(
       () => this._itemManager.items,
       () => this._itemManager.debouncedUpdate,
       this,
@@ -186,7 +186,7 @@ export class Database {
    * @param filter
    */
   reduce<R> (result: R, filter?: RootFilter): Selection<Item<any>, R> {
-    return createSelector<R>(
+    return createSelection<R>(
       () => this._itemManager.items,
       () => this._itemManager.debouncedUpdate,
       this,
@@ -205,7 +205,7 @@ export class Database {
   }
 
   private _assertInitialized () {
-    if (this._state !== State.OPEN) {
+    if (this._state !== State.INITIALIZED) {
       throw new Error('Database not initialized.');
     }
   }

package/src/api/item.ts

@@ -10,7 +10,7 @@ import { Model, StateManager } from '@dxos/model-factory';
 import { ItemManager } from '../database';
 import { Entity } from './entity';
 import type { Link } from './link';
-import { Selection, createItemSelector } from './selection';
+import { Selection, createItemSelection } from './selection';
 
 const log = debug('dxos:echo-db:item');
 
@@ -102,7 +102,7 @@ export class Item<M extends Model | null = Model> extends Entity<M> {
    * Returns a selection context, which can be used to traverse the object graph starting from this item.
    */
   select (): Selection<Item<any>> {
-    return createItemSelector(this as Item, this._itemManager.debouncedUpdate, undefined);
+    return createItemSelection(this as Item, this._itemManager.debouncedUpdate, undefined);
   }
 
   /**

package/src/api/result-set.ts

@@ -9,6 +9,7 @@ import { Event, ReadOnlyEvent } from '@dxos/async';
 /**
  * Reactive query results.
  */
+// TODO(burdon): Replace with Selection?
 export class ResultSet<T> {
   private readonly _resultsUpdate = new Event<T[]>();
   private readonly _itemUpdate: ReadOnlyEvent;

package/src/api/selection/index.ts

@@ -0,0 +1,8 @@
+//
+// Copyright 2022 DXOS.org
+//
+
+export * from './queries';
+export * from './result';
+export * from './selection';
+export * from './util';

package/src/api/selection/queries.ts

@@ -0,0 +1,108 @@
+//
+// Copyright 2020 DXOS.org
+//
+
+import { ItemID } from '@dxos/echo-protocol';
+
+import { Entity } from '../entity';
+import { Item } from '../item';
+import { Link } from '../link';
+import { coerceToId, OneOrMultiple, testOneOrMultiple } from './util';
+
+//
+// Types
+//
+
+export type ItemIdFilter = {
+  id: ItemID
+}
+
+export type ItemFilter = {
+  type?: OneOrMultiple<string>
+  parent?: ItemID | Item
+}
+
+export type LinkFilter = {
+  type?: OneOrMultiple<string>;
+}
+
+export type Predicate<T extends Entity> = (entity: T) => boolean;
+
+export type RootFilter = ItemIdFilter | ItemFilter | Predicate<Item>
+
+/**
+ * Visitor callback.
+ * The visitor is passed the current entities and result (accumulator),
+ * which may be modified and returned.
+ */
+export type Callable<T extends Entity, R> = (entities: T[], result: R) => R
+
+/**
+ * Controls how deleted items are filtered.
+ */
+export enum ItemFilterDeleted {
+  /**
+   * Do not return deleted items. Default behaviour.
+   */
+  HIDE_DELETED = 0,
+  /**
+   * Return deleted and regular items.
+   */
+  SHOW_DELETED = 1,
+  /**
+   * Return only deleted items.
+   */
+  SHOW_DELETED_ONLY = 2
+}
+
+export type QueryOptions = {
+  /**
+   * Controls how deleted items are filtered.
+   */
+  deleted?: ItemFilterDeleted
+}
+
+//
+// Filters
+//
+
+export const filterToPredicate = (filter: ItemFilter | ItemIdFilter | Predicate<any>): Predicate<any> => {
+  if (typeof filter === 'function') {
+    return filter;
+  }
+
+  return itemFilterToPredicate(filter);
+};
+
+export const itemFilterToPredicate = (filter: ItemFilter | ItemIdFilter): Predicate<Item> => {
+  if ('id' in filter) {
+    return item => item.id === filter.id;
+  } else {
+    return item =>
+      (!filter.type || testOneOrMultiple(filter.type, item.type)) &&
+      (!filter.parent || item.parent?.id === coerceToId(filter.parent));
+  }
+};
+
+export const linkFilterToPredicate = (filter: LinkFilter): Predicate<Link> => {
+  return link => (!filter.type || testOneOrMultiple(filter.type, link.type));
+};
+
+export const createQueryOptionsFilter = ({
+  deleted = ItemFilterDeleted.HIDE_DELETED
+}: QueryOptions): Predicate<Entity> => {
+  return entity => {
+    if (entity.model === null) {
+      return false;
+    }
+
+    switch (deleted) {
+      case ItemFilterDeleted.HIDE_DELETED:
+        return !(entity instanceof Item) || !entity.deleted;
+      case ItemFilterDeleted.SHOW_DELETED:
+        return true;
+      case ItemFilterDeleted.SHOW_DELETED_ONLY:
+        return entity instanceof Item && entity.deleted;
+    }
+  };
+};

package/src/api/selection/result.ts

@@ -0,0 +1,112 @@
+//
+// Copyright 2020 DXOS.org
+//
+
+import assert from 'assert';
+
+import { Event } from '@dxos/async';
+
+import { Database } from '../database';
+import { Entity } from '../entity';
+import { dedupe } from './util';
+
+/**
+ * Represents where the selection has started.
+ */
+export type SelectionRoot = Database | Entity
+
+/**
+ * Returned from each stage of the visitor.
+ */
+export type SelectionContext<T extends Entity, R> = [entities: T[], result?: R]
+
+/**
+ * Query subscription.
+ * Represents a live-query (subscription) that can notify about future updates to the relevant subset of items.
+ */
+export class SelectionResult<T extends Entity, R = any> {
+  /**
+   * Fired when there are updates in the selection.
+   * Only update that are relevant to the selection cause the update.
+   */
+  readonly update = new Event<SelectionResult<T>>(); // TODO(burdon): Result result object.
+
+  private _lastResult: SelectionContext<T, R> = [[]];
+
+  constructor (
+    private readonly _execute: () => SelectionContext<T, R>,
+    private readonly _update: Event<Entity[]>,
+    private readonly _root: SelectionRoot,
+    private readonly _reducer: boolean
+  ) {
+    this.refresh();
+
+    // Re-run if deps change.
+    this.update.addEffect(() => _update.on(currentEntities => {
+      const [previousEntities] = this._lastResult;
+      this.refresh();
+
+      // Filters mutation events only if selection (since we can't reason about deps of call methods).
+      const set = new Set([...previousEntities, ...this._lastResult![0]]);
+      if (this._reducer || currentEntities.some(entity => set.has(entity as any))) {
+        this.update.emit(this);
+      }
+    }));
+  }
+
+  toString () {
+    const [entities] = this._lastResult;
+    return `SelectionResult<${JSON.stringify({
+      entities: entities.length
+    })}>`;
+  }
+
+  /**
+   * Re-run query.
+   */
+  refresh () {
+    const [entities, result] = this._execute();
+    this._lastResult = [dedupe(entities), result];
+    return this;
+  }
+
+  /**
+   * The root of the selection. Either a database or an item. Must be a stable reference.
+   */
+  get root (): SelectionRoot {
+    return this._root;
+  }
+
+  /**
+   * Get the result of this selection.
+   */
+  get entities (): T[] {
+    if (!this._lastResult) {
+      this.refresh();
+    }
+
+    const [entities] = this._lastResult!;
+    return entities;
+  }
+
+  /**
+   * Returns the selection or reducer result.
+   */
+  get value (): R extends void ? T[] : R {
+    if (!this._lastResult) {
+      this.refresh();
+    }
+
+    const [entities, value] = this._lastResult!;
+    return (this._reducer ? value : entities) as any;
+  }
+
+  /**
+   * Return the first element if the set has exactly one element.
+   */
+  expectOne (): T {
+    const entities = this.entities;
+    assert(entities.length === 1, `Expected one result; got ${entities.length}`);
+    return entities[0];
+  }
+}

package/src/api/{selection.test.ts → selection/selection.test.ts}

@@ -11,10 +11,11 @@ import { ItemID, ItemType } from '@dxos/echo-protocol';
 import { ModelFactory } from '@dxos/model-factory';
 import { ObjectModel } from '@dxos/object-model';
 
-import { Entity } from './entity';
-import { Item } from './item';
-import { Link } from './link';
-import { RootFilter, createSelector } from './selection';
+import { Entity } from '../entity';
+import { Item } from '../item';
+import { Link } from '../link';
+import { RootFilter } from './queries';
+import { createSelection } from './selection';
 
 // Use to prevent ultra-long diffs.
 const ids = (entities: Entity[]) => entities.map(entity => entity.id);
@@ -23,8 +24,9 @@ const modelFactory = new ModelFactory().registerModel(ObjectModel);
 
 const createModel = (id: ItemID) => modelFactory.createModel(ObjectModel.meta.type, id, {}, PublicKey.random());
 
-const createItem = (id: ItemID, type: ItemType, parent?: Item<any>) =>
-  new Item(null as any, id, type, createModel(id), undefined, parent);
+const createItem = (id: ItemID, type: ItemType, parent?: Item<any>) => {
+  return new Item(null as any, id, type, createModel(id), undefined, parent);
+};
 
 const createLink = (id: ItemID, type: ItemType, source: Item<any>, target: Item<any>) => {
   const link = new Link(null as any, id, type, createModel(id), {
@@ -40,11 +42,11 @@ const createLink = (id: ItemID, type: ItemType, source: Item<any>, target: Item<
   return link;
 };
 
-const createRootSelector = (filter?: RootFilter) =>
-  createSelector<void>(() => items, () => new Event(), null as any, filter, undefined);
+const createRootSelection = (filter?: RootFilter) =>
+  createSelection<void>(() => items, () => new Event(), null as any, filter, undefined);
 
 const createReducer = <R>(result: R) =>
-  createSelector<R>(() => items, () => new Event(), null as any, undefined, result);
+  createSelection<R>(() => items, () => new Event(), null as any, undefined, result);
 
 // TODO(burdon): Use more complex data set (org, person, project, task).
 
@@ -90,34 +92,34 @@ describe('Selection', () => {
   describe('root', () => {
     test('all', () => {
       expect(
-        createRootSelector()
-          .query().entities
+        createRootSelection()
+          .exec().entities
       ).toHaveLength(items.length);
     });
 
     test('by id', () => {
       expect(
-        createRootSelector({ id: org1.id })
-          .query().entities
+        createRootSelection({ id: org1.id })
+          .exec().entities
       ).toEqual([org1]);
 
       expect(
-        createRootSelector({ id: org2.id })
-          .query().entities
+        createRootSelection({ id: org2.id })
+          .exec().entities
       ).toEqual([org2]);
     });
 
     test('single type', () => {
       expect(
-        createRootSelector({ type: ITEM_PROJECT })
-          .query().entities
+        createRootSelection({ type: ITEM_PROJECT })
+          .exec().entities
       ).toHaveLength(3);
     });
 
     test('multiple types', () => {
       expect(
-        createRootSelector({ type: [ITEM_ORG, ITEM_PROJECT] })
-          .query().entities
+        createRootSelection({ type: [ITEM_ORG, ITEM_PROJECT] })
+          .exec().entities
       ).toHaveLength(5);
     });
   });
@@ -125,33 +127,33 @@ describe('Selection', () => {
   describe('filter', () => {
     test('invalid', () => {
       expect(
-        createRootSelector()
-          .filter({ type: 'dxos:type.invalid' })
-          .query().entities
+        createRootSelection()
+          .filter({ type: 'dxos:type/invalid' })
+          .exec().entities
       ).toHaveLength(0);
     });
 
     test('single type', () => {
       expect(
-        createRootSelector()
+        createRootSelection()
           .filter({ type: ITEM_PROJECT })
-          .query().entities
+          .exec().entities
       ).toHaveLength(3);
     });
 
     test('multiple types', () => {
       expect(
-        createRootSelector()
+        createRootSelection()
           .filter({ type: [ITEM_ORG, ITEM_PROJECT] })
-          .query().entities
+          .exec().entities
       ).toHaveLength(5);
     });
 
     test('by function', () => {
       expect(
-        createRootSelector()
+        createRootSelection()
           .filter(item => item.type === ITEM_ORG)
-          .query().entities
+          .exec().entities
       ).toHaveLength(2);
     });
   });
@@ -159,10 +161,10 @@ describe('Selection', () => {
   describe('children', () => {
     test('from multiple items', () => {
       expect(ids(
-        createRootSelector()
+        createRootSelection()
           .filter({ type: ITEM_ORG })
           .children({ type: ITEM_PROJECT })
-          .query().entities
+          .exec().entities
       )).toStrictEqual(ids([
         project1,
         project2,
@@ -172,9 +174,9 @@ describe('Selection', () => {
 
     test('from single item', () => {
       expect(ids(
-        createRootSelector({ id: org1.id })
+        createRootSelection({ id: org1.id })
           .children()
-          .query().entities
+          .exec().entities
       )).toStrictEqual(ids([
         project1,
         project2,
@@ -187,10 +189,10 @@ describe('Selection', () => {
   describe('parent', () => {
     test('from multiple items', () => {
       expect(ids(
-        createRootSelector()
+        createRootSelection()
           .filter({ type: ITEM_PROJECT })
           .parent()
-          .query().entities
+          .exec().entities
       )).toStrictEqual(ids([
         org1,
         org2
@@ -199,9 +201,9 @@ describe('Selection', () => {
 
     test('from single item', () => {
       expect(ids(
-        createRootSelector({ id: project1.id })
+        createRootSelection({ id: project1.id })
           .parent()
-          .query().entities
+          .exec().entities
       )).toStrictEqual(ids([
         org1
       ]));
@@ -209,9 +211,9 @@ describe('Selection', () => {
 
     test('is empty', () => {
       expect(
-        createRootSelector({ id: org1.id })
+        createRootSelection({ id: org1.id })
           .parent()
-          .query().entities
+          .exec().entities
       ).toEqual([]);
     });
   });
@@ -219,10 +221,10 @@ describe('Selection', () => {
   describe('links', () => {
     test('links from single item', () => {
       expect(ids(
-        createRootSelector({ id: project1.id })
+        createRootSelection({ id: project1.id })
           .links()
           .target()
-          .query().entities
+          .exec().entities
       )).toStrictEqual(ids([
         person1,
         person2
@@ -231,18 +233,18 @@ describe('Selection', () => {
 
     test('links from multiple items', () => {
       expect(
-        createRootSelector({ type: ITEM_PROJECT })
+        createRootSelection({ type: ITEM_PROJECT })
           .links()
-          .query().entities
+          .exec().entities
       ).toHaveLength(links.length);
     });
 
     test('sources', () => {
       expect(ids(
-        createRootSelector({ type: ITEM_PERSON })
+        createRootSelection({ type: ITEM_PERSON })
           .refs()
           .source()
-          .query().entities
+          .exec().entities
       )).toStrictEqual(ids([
         project1,
         project2
@@ -252,7 +254,7 @@ describe('Selection', () => {
 
   describe('reducer', () => {
     test('simple reducer', () => {
-      const query = createReducer(0).call((items, count) => count + items.length).query();
+      const query = createReducer(0).call((items, count) => count + items.length).exec();
       expect(query.value).toEqual(items.length);
     });
 
@@ -272,7 +274,7 @@ describe('Selection', () => {
           return { ...rest, numLinks: numLinks + links.length, stage: 'c' };
         })
         .target()
-        .query();
+        .exec();
 
       expect(query.value).toEqual({ numItems: 5, numLinks: 4, stage: 'c' });
     });
@@ -282,9 +284,9 @@ describe('Selection', () => {
     test('events get filtered correctly', async () => {
       const update = new Event<Entity[]>();
 
-      const query = createSelector<void>(() => items, () => update, null as any, { type: ITEM_ORG }, undefined)
+      const query = createSelection<void>(() => items, () => update, null as any, { type: ITEM_ORG }, undefined)
         .children()
-        .query();
+        .exec();
 
       {
         const promise = query.update.waitForCount(1);