@dxos/echo-db 2.29.1 → 2.29.2-dev.f64f2a6f

package/src/api/database.test.ts

@@ -80,7 +80,7 @@ describe('Database', () => {
       expect(item.id).not.toBeUndefined();
       expect(item.model).toBeInstanceOf(ObjectModel);
 
-      const result = database.select().query();
+      const result = database.select().exec();
       expect(result.expectOne()).toBeTruthy();
     });
 
@@ -111,7 +111,7 @@ describe('Database', () => {
       const parent = await database.createItem({ model: ObjectModel });
       const child = await database.createItem({ model: ObjectModel, parent: parent.id });
 
-      const result = database.select().query();
+      const result = database.select().exec();
       expect(result.entities).toHaveLength(2);
       expect(result.entities).toEqual([parent, child]);
 
@@ -203,14 +203,14 @@ describe('Database', () => {
         const database = await setupBackend(modelFactory);
 
         {
-          const waiting = database.waitForItem({ type: 'example:type.test' });
-          const item = await database.createItem({ model: ObjectModel, type: 'example:type.test' });
+          const waiting = database.waitForItem({ type: 'example:type/test-1' });
+          const item = await database.createItem({ model: ObjectModel, type: 'example:type/test-1' });
           expect(await promiseTimeout(waiting, 100, new Error('timeout'))).toEqual(item);
         }
 
         {
-          const item = await database.createItem({ model: ObjectModel, type: 'example:type.test-2' });
-          const waiting = database.waitForItem({ type: 'example:type.test-2' });
+          const item = await database.createItem({ model: ObjectModel, type: 'example:type/test-2' });
+          const waiting = database.waitForItem({ type: 'example:type/test-2' });
           expect(await promiseTimeout(waiting, 100, new Error('timeout'))).toEqual(item);
         }
       });
@@ -223,7 +223,7 @@ describe('Database', () => {
           database.createItem({ model: TestListModel })
         ));
 
-        const result = database.select().query();
+        const result = database.select().exec();
         const items = result.entities;
         expect(items).toHaveLength(10);
 
@@ -232,17 +232,17 @@ describe('Database', () => {
         await update;
 
         {
-          const result = database.select().query();
+          const result = database.select().exec();
           expect(result.entities).toHaveLength(9);
         }
 
         {
-          const result = database.select().query({ deleted: ItemFilterDeleted.SHOW_DELETED });
+          const result = database.select().exec({ deleted: ItemFilterDeleted.SHOW_DELETED });
           expect(result.entities).toHaveLength(10);
         }
 
         {
-          const result = database.select().query({ deleted: ItemFilterDeleted.SHOW_DELETED_ONLY });
+          const result = database.select().exec({ deleted: ItemFilterDeleted.SHOW_DELETED_ONLY });
           expect(result.entities).toHaveLength(1);
         }
       });
@@ -255,7 +255,7 @@ describe('Database', () => {
         const item2 = await database.createItem({ model: ObjectModel });
 
         // 1. Create a query
-        const query = database.select().query();
+        const query = database.select().exec();
         const update = query.update.waitForCount(1);
 
         // 2. Create a link
@@ -277,7 +277,7 @@ describe('Database', () => {
 
         const parentItem = await database.createItem({ model: ObjectModel });
 
-        const query = database.select({ id: parentItem.id }).query();
+        const query = database.select({ id: parentItem.id }).exec();
         const update = query.update.waitForCount(1);
 
         const childItem = await database.createItem({
@@ -295,7 +295,7 @@ describe('Database', () => {
         const database = await setupBackend(modelFactory);
 
         await Promise.all(Array.from({ length: 8 }).map(() => database.createItem({ model: ObjectModel })));
-        const { value } = database.reduce(0).call((items) => items.length).query();
+        const { value } = database.reduce(0).call((items) => items.length).exec();
         expect(value).toBe(8);
       });
     });

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);
   }
 
   /**
@@ -159,7 +158,7 @@ export class Database {
    * Waits for item matching the filter to be present and returns it.
    */
   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.');
@@ -171,7 +170,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 +185,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 +204,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];
+  }
+}