@dxos/echo 0.8.4-main.3eb6e50203 → 0.8.4-main.3fbcb4aa9b

package/src/internal/{ref → Ref}/ref.test.ts

@@ -7,16 +7,15 @@ import { describe, expect, test } from 'vitest';
 
 import { DXN, ObjectId } from '@dxos/keys';
 
-import { EchoObjectSchema, getObjectDXN } from '../entities';
-import { createObject } from '../object';
-
+import { EchoObjectSchema, getObjectDXN } from '../Entity';
+import { createObject } from '../Obj';
 import { Ref, getReferenceAst } from './ref';
 
 const Task = Schema.Struct({
   title: Schema.optional(Schema.String),
 }).pipe(
   EchoObjectSchema({
-    typename: 'example.com/type/Task',
+    typename: 'com.example.type.task',
     version: '0.1.0',
   }),
 );
@@ -29,7 +28,7 @@ const Contact = Schema.Struct({
   tasks: Schema.Array(Ref(Task)),
 }).pipe(
   EchoObjectSchema({
-    typename: 'example.com/type/Person',
+    typename: 'com.example.type.person',
     version: '0.1.0',
   }),
 );

package/src/internal/{ref → Ref}/ref.ts

@@ -19,9 +19,9 @@ import { assertArgument, invariant } from '@dxos/invariant';
 import { DXN, ObjectId } from '@dxos/keys';
 
 import * as Database from '../../Database';
-import { ReferenceAnnotationId, getSchemaDXN, getTypeAnnotation, getTypeIdentifierAnnotation } from '../annotations';
-import { type JsonSchemaType } from '../json-schema';
-import type { AnyEntity, AnyProperties } from '../types';
+import { ReferenceAnnotationId, getSchemaDXN, getTypeAnnotation, getTypeIdentifierAnnotation } from '../Annotation';
+import type { AnyEntity, AnyProperties } from '../common/types';
+import { type JsonSchemaType } from '../JsonSchema';
 
 /**
  * The `$id` and `$ref` fields for an ECHO reference schema.
@@ -164,6 +164,16 @@ export interface Ref<T> extends Pipeable.Pipeable {
 
   tryLoad(): Promise<T | undefined>;
 
+  /**
+   * Subscribe to the ref's resolution event.
+   * The callback fires when the target object becomes available in the working set
+   * (e.g. when its document is loaded after sibling-client mutation).
+   * Note: the resolver only schedules a notification when the target is requested
+   * via {@link target} while it is not yet loaded.
+   * @returns Function that unsubscribes the callback.
+   */
+  onResolved(callback: () => void): () => void;
+
   /**
    * Do not inline the target object in the reference.
    * Makes .target unavailable unless the reference is connected to a database context.
@@ -420,6 +430,13 @@ export class RefImpl<T> implements Ref<T> {
     return (await this.#resolver.resolve(this.#dxn)) as T | undefined;
   }
 
+  /**
+   * @inheritdoc
+   */
+  onResolved(callback: () => void): () => void {
+    return this.#resolved.on(callback);
+  }
+
   /**
    * Do not inline the target object in the reference.
    * Makes .target unavailable unless the reference is connected to a database context.

package/src/internal/{schema → Type}/compose.test.ts

@@ -5,11 +5,10 @@
 import * as Schema from 'effect/Schema';
 import { describe, test } from 'vitest';
 
-import { FieldPath } from '../annotations';
-import { EchoObjectSchema } from '../entities';
-import { FormatAnnotation, TypeFormat } from '../formats';
-import { ECHO_ANNOTATIONS_NS_KEY, toJsonSchema } from '../json-schema';
-
+import { FieldPath } from '../Annotation';
+import { EchoObjectSchema } from '../Entity';
+import { FormatAnnotation, TypeFormat } from '../Format';
+import { ECHO_ANNOTATIONS_NS_KEY, toJsonSchema } from '../JsonSchema';
 import { composeSchema } from './compose';
 
 describe('schema composition', () => {
@@ -17,7 +16,7 @@ describe('schema composition', () => {
     const BaseType = Schema.Struct({
       name: Schema.String,
       email: Schema.String,
-    }).pipe(EchoObjectSchema({ typename: 'example.com/Person', version: '0.1.0' }));
+    }).pipe(EchoObjectSchema({ typename: 'com.example.person', version: '0.1.0' }));
 
     const OverlaySchema = Schema.Struct({
       email: Schema.String.pipe(FieldPath('$.email'), FormatAnnotation.set(TypeFormat.Email)),

package/src/internal/{schema → Type}/compose.ts

@@ -6,7 +6,7 @@ import type * as Types from 'effect/Types';
 
 import { invariant } from '@dxos/invariant';
 
-import { type JsonSchemaType } from '../json-schema';
+import { type JsonSchemaType } from '../JsonSchema';
 
 /**
  * Creates a composite schema from the source and projection schemas.

package/src/internal/{schema → Type}/echo-schema.ts

@@ -9,12 +9,11 @@ import { invariant } from '@dxos/invariant';
 import { type ObjectId } from '@dxos/keys';
 
 import type * as Type from '../../Type';
-import { type SchemaMeta, SchemaMetaSymbol, type TypeAnnotation, getTypeAnnotation } from '../annotations';
-import { type JsonSchemaType, toEffectSchema, toJsonSchema } from '../json-schema';
-import { type TypedObject, type TypedObjectPrototype, getSnapshot } from '../object';
-import { ChangeId } from '../proxy';
-import { EntityKind, SchemaKindId } from '../types';
-
+import { type SchemaMeta, SchemaMetaSymbol, type TypeAnnotation, getTypeAnnotation } from '../Annotation';
+import { ChangeId } from '../common/proxy';
+import { EntityKind, SchemaKindId } from '../common/types';
+import { type JsonSchemaType, toEffectSchema, toJsonSchema } from '../JsonSchema';
+import { type TypedObject, type TypedObjectPrototype, getSnapshot } from '../Obj';
 import {
   addFieldsToSchema,
   removeFieldsFromSchema,
@@ -178,7 +177,7 @@ const schemaVariance = {
  *
  * @example
  * ```ts
- * export class TableType extends Schema.Struct({...}).pipe(Type.object({ typename: 'example.org/type/Table', version: '0.1.0' })){
+ * export class TableType extends Schema.Struct({...}).pipe(Type.object({ typename: 'com.example.type.table', version: '0.1.0' })){
  *   title: Schema.String,
  *   schema: Schema.optional(ref(EchoSchema)),
  *   props: Schema.mutable(S.Array(TablePropSchema)),
@@ -193,7 +192,7 @@ export class EchoSchema<A = any, I = any> extends EchoSchemaConstructor() implem
 
   /**
    * Schema kind key that marks this as an ECHO schema.
-   * Makes EchoSchema satisfy the Type.Obj.Any type.
+   * Makes EchoSchema satisfy the Type.AnyObj type.
    */
   readonly [SchemaKindId]: EntityKind.Object = EntityKind.Object;
 
@@ -373,7 +372,7 @@ export class EchoSchema<A = any, I = any> extends EchoSchemaConstructor() implem
   }
 
   /**
-   * Wrapper for Obj.change that handles the change context for the persistent schema.
+   * Wrapper for Obj.update that handles the change context for the persistent schema.
    */
   private _change(callback: (schema: PersistentSchema) => void): void {
     const changeFn = (this._persistentSchema as any)[ChangeId];
@@ -400,7 +399,7 @@ export class EchoSchema<A = any, I = any> extends EchoSchemaConstructor() implem
    */
   _rebuild(): void {
     if (this._isDirty || this._schema == null) {
-      this._schema = toEffectSchema(getSnapshot(this._persistentSchema.jsonSchema));
+      this._schema = toEffectSchema(getSnapshot(this._persistentSchema).jsonSchema);
       this._isDirty = false;
     }
   }

package/src/internal/{schema → Type}/manipulation.ts

@@ -8,7 +8,7 @@ import * as SchemaAST from 'effect/SchemaAST';
 import { invariant } from '@dxos/invariant';
 import { DXN } from '@dxos/keys';
 
-import { type TypeAnnotation, TypeAnnotationId, TypeIdentifierAnnotationId } from '../annotations';
+import { type TypeAnnotation, TypeAnnotationId, TypeIdentifierAnnotationId } from '../Annotation';
 
 // TODO(ZaymonFC): Do this one at a time. This might be dangerous.
 export const addFieldsToSchema = (

package/src/internal/{schema → Type}/persistent-schema.ts

@@ -4,9 +4,10 @@
 
 import * as Schema from 'effect/Schema';
 
-import { LabelAnnotation, TypenameSchema, VersionSchema } from '../annotations';
-import { EchoObjectSchema } from '../entities';
-import { JsonSchemaType } from '../json-schema';
+import { IconAnnotation } from '../Annotation';
+import { LabelAnnotation, TypenameSchema, VersionSchema } from '../Annotation';
+import { EchoObjectSchema } from '../Entity';
+import { JsonSchemaType } from '../JsonSchema';
 
 /**
  * Persistent representation of a schema.
@@ -19,10 +20,14 @@ export const PersistentSchema = Schema.Struct({
   jsonSchema: JsonSchemaType,
 }).pipe(
   EchoObjectSchema({
-    typename: 'dxos.org/type/Schema',
+    typename: 'org.dxos.type.schema',
     version: '0.1.0',
   }),
   LabelAnnotation.set(['name']),
+  IconAnnotation.set({
+    icon: 'ph--database--regular',
+    hue: 'green',
+  }),
 );
 
 export interface PersistentSchema extends Schema.Schema.Type<typeof PersistentSchema> {}

package/src/internal/{README.md → common/README.md}

@@ -30,7 +30,7 @@
 
 - [x] QueryResult namespace
 - [x] SchemaRegistry interface
-- [x] Schema registry should return Type.Entity.Any instead of Schema.Schema.AnyNoContext.
+- [x] Schema registry should return Type.AnyEntity instead of Schema.Schema.AnyNoContext.
 - [x] Hypergraph interface
 - [x] Obj.getDatabase
 - [x] SpaceAction.AddObject target should be a db not a space.
@@ -99,4 +99,4 @@
 - [ ] ReactiveObject should specify id property? Reconcile AnyProperties, ReactiveObject, HasId, WithId, etc.
 - [ ] Can we us S.is(MyType) to detect objects with our types system? (Branding?)
 - [ ] Type.Expando doesn't work with AtomQuery result type (have to use Obj.Any instead).
-- [ ] Obj.Any doesn't work with Obj.change callback types (have to use `any` for the mutable parameter).
+- [ ] Obj.Any doesn't work with Obj.update callback types (have to use `any` for the mutable parameter).

package/src/internal/{api → common/api}/index.ts

@@ -12,8 +12,4 @@
  * and prevent external packages from using internals directly.
  */
 
-export * from './annotations';
-export * from './entity';
 export * from './meta';
-export * from './sorting';
-export * from './version';

package/src/internal/{api → common/api}/meta.ts

@@ -48,7 +48,7 @@ export const getKeys = (entity: AnyProperties, source: string): ForeignKey[] =>
 
 /**
  * Delete all keys from the entity for the specified source.
- * Must be called within an Obj.change or Relation.change callback.
+ * Must be called within an Obj.update or Relation.update callback.
  */
 export const deleteKeys = (entity: Mutable<AnyProperties>, source: string) => {
   const meta = getMetaChecked(entity);
@@ -62,7 +62,7 @@ export const deleteKeys = (entity: Mutable<AnyProperties>, source: string) => {
 
 /**
  * Add a tag to the entity.
- * Must be called within an Obj.change or Relation.change callback.
+ * Must be called within an Obj.update or Relation.update callback.
  */
 export const addTag = (entity: Mutable<AnyProperties>, tag: string) => {
   const meta = getMetaChecked(entity);
@@ -72,7 +72,7 @@ export const addTag = (entity: Mutable<AnyProperties>, tag: string) => {
 
 /**
  * Remove a tag from the entity.
- * Must be called within an Obj.change or Relation.change callback.
+ * Must be called within an Obj.update or Relation.update callback.
  */
 export const removeTag = (entity: Mutable<AnyProperties>, tag: string) => {
   const meta = getMetaChecked(entity);

package/src/internal/common/index.ts

@@ -0,0 +1,7 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+export * from './api';
+export * from './proxy';
+export * from './types';

package/src/internal/{proxy → common/proxy}/change-context.ts

@@ -35,7 +35,7 @@ const pendingOwnerNotifications = new Set<object>();
 /**
  * Enter a change context for the given key.
  * While in a change context, mutations are allowed on the associated object.
- * Nested Obj.change calls are not supported.
+ * Nested Obj.update calls are not supported.
  *
  * @param key - The key to enter the change context for (target object or ObjectCore).
  * @returns A cleanup function that exits the change context.