@dxos/echo 0.8.4-main.66e292d → 0.8.4-main.69d29f4

package/src/internal/object/snapshot.ts

@@ -0,0 +1,70 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { deepMapValues } from '@dxos/util';
+
+import { RelationSourceDXNId, RelationSourceId, RelationTargetDXNId, RelationTargetId } from '../entities/relation';
+import { KindId, SnapshotKindId } from '../types/entity';
+import { MetaId } from '../types/meta';
+import { SchemaId, TypeId } from '../types/typename';
+
+/**
+ * Copy a Symbol-keyed property from source to target if it exists.
+ */
+const copySymbolProperty = (source: any, target: any, symbol: symbol): void => {
+  if (symbol in source) {
+    Object.defineProperty(target, symbol, {
+      value: source[symbol],
+      writable: false,
+      enumerable: false,
+      configurable: false,
+    });
+  }
+};
+
+/**
+ * Returns an immutable snapshot of the reactive object.
+ * The snapshot is branded with SnapshotKindId (not KindId).
+ */
+export const getSnapshot = <T extends object>(obj: T): T => {
+  const snapshot = deepMapValues(obj, (value, recurse) => {
+    // Do not recurse on references (but do recurse on arrays).
+    if (
+      typeof value === 'object' &&
+      value !== null &&
+      Object.getPrototypeOf(value) !== Object.prototype &&
+      !Array.isArray(value)
+    ) {
+      return value;
+    }
+
+    return recurse(value);
+  }) as any;
+
+  // Add SnapshotKindId brand based on original KindId.
+  if (obj != null && typeof obj === 'object' && KindId in obj) {
+    snapshot[SnapshotKindId] = (obj as any)[KindId];
+  }
+
+  // Preserve Symbol-keyed properties that are important for type introspection.
+  // These are not copied by deepMapValues since Object.keys() doesn't include symbols.
+  if (obj != null && typeof obj === 'object') {
+    const source = obj as any;
+
+    // Type introspection symbols.
+    copySymbolProperty(source, snapshot, TypeId);
+    copySymbolProperty(source, snapshot, SchemaId);
+
+    // Metadata symbol.
+    copySymbolProperty(source, snapshot, MetaId);
+
+    // Relation endpoint symbols.
+    copySymbolProperty(source, snapshot, RelationSourceDXNId);
+    copySymbolProperty(source, snapshot, RelationTargetDXNId);
+    copySymbolProperty(source, snapshot, RelationSourceId);
+    copySymbolProperty(source, snapshot, RelationTargetId);
+  }
+
+  return Object.freeze(snapshot) as T;
+};

package/src/internal/object/typed-object.test.ts

@@ -6,16 +6,20 @@ import * as Schema from 'effect/Schema';
 import * as SchemaAST from 'effect/SchemaAST';
 import { describe, expect, test } from 'vitest';
 
-import { TypedObject } from './typed-object';
+import { EchoObjectSchema } from '../entities';
 
-class Organization extends TypedObject({
-  typename: 'example.com/type/Organization',
-  version: '0.1.0',
-})({
+const Organization = Schema.Struct({
   name: Schema.String,
-}) {}
+}).pipe(
+  EchoObjectSchema({
+    typename: 'example.com/type/Organization',
+    version: '0.1.0',
+  }),
+);
 
-describe('EchoObjectSchema class DSL', () => {
+interface Organization extends Schema.Schema.Type<typeof Organization> {}
+
+describe('EchoObjectSchema DSL', () => {
   test('type is a valid schema', async () => {
     expect(Schema.isSchema(Organization)).to.be.true;
   });
@@ -24,10 +28,6 @@ describe('EchoObjectSchema class DSL', () => {
     expect(Organization.typename).to.eq('example.com/type/Organization');
   });
 
-  test('expect constructor to throw', async () => {
-    expect(() => new Organization()).to.throw();
-  });
-
   test('expect schema', async () => {
     expect(SchemaAST.isTypeLiteral(Organization.ast)).to.be.true;
   });

package/src/internal/object/typed-object.ts

@@ -2,22 +2,10 @@
 // Copyright 2024 DXOS.org
 //
 
-import * as Schema from 'effect/Schema';
-import * as SchemaAST from 'effect/SchemaAST';
+import type * as Schema from 'effect/Schema';
 
-import { invariant } from '@dxos/invariant';
-
-import {
-  type TypeAnnotation,
-  TypeAnnotationId,
-  type TypeMeta,
-  TypenameSchema,
-  VersionSchema,
-  makeTypeJsonSchemaAnnotation,
-} from '../annotations';
-import { EntityKind, type HasId } from '../types';
-
-import { type TypedObjectFields, type TypedObjectOptions, makeTypedEntityClass } from './common';
+import { type TypeMeta } from '../annotations';
+import { type AnyEntity } from '../types';
 
 /**
  * Definition for an object type that can be stored in an ECHO database.
@@ -25,70 +13,18 @@ import { type TypedObjectFields, type TypedObjectOptions, makeTypedEntityClass }
  * Has a typename and version.
  *
  * In contrast to {@link EchoSchema} this definition is not recorded in the database.
+ *
+ * @deprecated Use `Type.Obj.Any` from `@dxos/echo` instead.
  */
 export interface TypedObject<A = any, I = any> extends TypeMeta, Schema.Schema<A, I> {}
 
 /**
  * Typed object that could be used as a prototype in class definitions.
  * This is an internal API type.
- * Use {@link TypedObject} for the common use-cases.
+ *
+ * @deprecated Use `Type.Obj.Any` from `@dxos/echo` instead.
  */
 export interface TypedObjectPrototype<A = any, I = any> extends TypedObject<A, I> {
   /** Type constructor. */
-  new (): HasId & A;
+  new (): AnyEntity & A;
 }
-
-export type TypedObjectProps = TypeMeta & {
-  // TODO(dmaretskyi): Remove after all legacy types has been removed.
-  disableValidation?: boolean;
-};
-
-/**
- * Base class factory for typed objects.
- * @deprecated Use Function.pipe(Type.Obj) instead.
- */
-export const TypedObject = ({
-  typename: typenameParam,
-  version: versionParam,
-  disableValidation,
-}: TypedObjectProps) => {
-  const typename = TypenameSchema.make(typenameParam, { disableValidation });
-  const version = VersionSchema.make(versionParam, { disableValidation });
-
-  /**
-   * Return class definition factory.
-   */
-  return <SchemaFields extends Schema.Struct.Fields, Options extends TypedObjectOptions>(
-    fields: SchemaFields,
-    options?: Options,
-  ): TypedObjectPrototype<TypedObjectFields<SchemaFields, Options>, Schema.Struct.Encoded<SchemaFields>> => {
-    // Create schema from fields.
-    const schema: Schema.Schema.All = options?.record
-      ? Schema.Struct(fields, { key: Schema.String, value: Schema.Any })
-      : Schema.Struct(fields);
-
-    // Set ECHO object id property.
-    const typeSchema = Schema.extend(
-      Schema.mutable(options?.partial ? Schema.partial(schema) : schema),
-      Schema.Struct({ id: Schema.String }),
-    );
-
-    // Set ECHO annotations.
-    invariant(typeof EntityKind.Object === 'string');
-    const annotatedSchema = typeSchema.annotations({
-      [TypeAnnotationId]: { kind: EntityKind.Object, typename, version } satisfies TypeAnnotation,
-      [SchemaAST.JSONSchemaAnnotationId]: makeTypeJsonSchemaAnnotation({
-        kind: EntityKind.Object,
-        typename,
-        version,
-      }),
-    });
-
-    /**
-     * Return class definition.
-     * NOTE: Actual reactive ECHO objects must be created via the `live(Type)` function.
-     */
-    // TODO(burdon): This is missing fields required by TypedObject (e.g., Type, Encoded, Context)?
-    return class TypedObject extends makeTypedEntityClass(typename, version, annotatedSchema as any) {} as any;
-  };
-};

package/src/internal/proxy/change-context.ts

@@ -0,0 +1,138 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { batchEvents } from './event-batch';
+import { EventId } from './symbols';
+
+/**
+ * Generic change context tracking.
+ * Only one object can be in a change context at a time (synchronous changes).
+ *
+ * This module provides a unified change context mechanism used by both:
+ * - TypedReactiveHandler (for non-database objects, using target as key)
+ * - EchoReactiveHandler (for database objects, using ObjectCore as key)
+ */
+
+/**
+ * The object currently in a change context.
+ * Can be a target object (for typed reactive) or ObjectCore (for database objects).
+ */
+let currentChangeContext: object | null = null;
+
+/**
+ * The primary object that has pending notifications, if any.
+ * This uses the contextKey (target or ObjectCore).
+ */
+let pendingNotificationKey: object | null = null;
+
+/**
+ * Additional objects (owner chain) that need notifications.
+ * These are separate from the primary notification because they use EventId directly.
+ */
+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.
+ *
+ * @param key - The key to enter the change context for (target object or ObjectCore).
+ * @returns A cleanup function that exits the change context.
+ */
+export const enterChangeContext = (key: object): (() => void) => {
+  currentChangeContext = key;
+  return () => {
+    currentChangeContext = null;
+  };
+};
+
+/**
+ * Check if the given key is currently in a change context.
+ *
+ * @param key - The key to check (target object or ObjectCore).
+ * @returns True if the key is in a change context, false otherwise.
+ */
+export const isInChangeContext = (key: object): boolean => {
+  return currentChangeContext === key;
+};
+
+/**
+ * Queue a notification for the given key to be fired when the change context exits.
+ *
+ * @param key - The key to queue a notification for.
+ */
+export const queueNotification = (key: object): void => {
+  if (currentChangeContext === key) {
+    pendingNotificationKey = key;
+  }
+};
+
+/**
+ * Queue an owner notification. Owner notifications are for objects in the ownership
+ * chain that should be notified when a nested object changes.
+ * These objects have EventId and emit directly.
+ * Skip if the target is already the current change context (to avoid duplicate notifications).
+ *
+ * @param target - The owner target that has EventId.
+ */
+export const queueOwnerNotification = (target: object): void => {
+  // Skip if this is the object already being changed (primary notification handles it).
+  if (currentChangeContext !== null && target !== currentChangeContext) {
+    pendingOwnerNotifications.add(target);
+  }
+};
+
+/**
+ * Check if there are any pending notifications for the given key.
+ *
+ * @param key - The key to check.
+ * @returns True if there are pending notifications, false otherwise.
+ */
+export const hasPendingNotifications = (key: object): boolean => {
+  return pendingNotificationKey === key;
+};
+
+/**
+ * Clear any pending notifications for the given key.
+ *
+ * @param key - The key to clear notifications for.
+ */
+export const clearPendingNotifications = (key: object): void => {
+  if (pendingNotificationKey === key) {
+    pendingNotificationKey = null;
+  }
+};
+
+/**
+ * Execute a callback within a change context.
+ * This is the shared implementation used by both TypedReactiveHandler and EchoReactiveHandler.
+ *
+ * @param contextKey - The key for the change context (target for typed, ObjectCore for db).
+ * @param eventTarget - The object that has the EventId for notifications.
+ * @param proxy - The proxy object to pass to the callback.
+ * @param callback - The callback to execute with mutations allowed.
+ */
+export const executeChange = (
+  contextKey: object,
+  eventTarget: object,
+  proxy: any,
+  callback: (proxy: any) => void,
+): void => {
+  const exitContext = enterChangeContext(contextKey);
+  try {
+    batchEvents(() => callback(proxy));
+  } finally {
+    exitContext();
+    // Fire primary notification.
+    if (hasPendingNotifications(contextKey)) {
+      clearPendingNotifications(contextKey);
+      (eventTarget as any)[EventId]?.emit();
+    }
+    // Fire owner chain notifications.
+    for (const ownerTarget of pendingOwnerNotifications) {
+      (ownerTarget as any)[EventId]?.emit();
+    }
+    pendingOwnerNotifications.clear();
+  }
+};