@dxos/echo 0.8.4-main.84f28bd → 0.8.4-main.937b3ca

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

@@ -0,0 +1,116 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { inspect } from 'util';
+
+import * as Schema from 'effect/Schema';
+import { describe, expect, test } from 'vitest';
+
+import { DXN } from '@dxos/keys';
+
+import { Relation } from '../../index';
+import { TestSchema } from '../../testing';
+import { getSchemaDXN, getTypeDXN, isInstanceOf } from '../annotations';
+import { ATTR_RELATION_SOURCE, ATTR_RELATION_TARGET } from '../entities';
+import { ATTR_META, ATTR_TYPE, getSchema } from '../types';
+
+import { createObject } from './create-object';
+import { objectToJSON } from './json-serializer';
+
+describe('create (static version)', () => {
+  test('defaults', ({ expect }) => {
+    const Contact = Schema.Struct({
+      name: Schema.String.pipe(
+        Schema.optional,
+        Schema.withConstructorDefault(() => 'Anonymous'),
+      ),
+      email: Schema.String.pipe(Schema.optional),
+    });
+
+    const obj = Contact.make({});
+    expect(obj.name).toBe('Anonymous');
+  });
+
+  test('create static object', () => {
+    const contact = createObject(TestSchema.Person, {
+      name: 'Bot',
+      email: 'bot@example.com',
+    });
+
+    expect(contact.id).toBeDefined();
+    expect(contact.name).toBe('Bot');
+    expect(contact.email).toBe('bot@example.com');
+    expect((contact as any)['@type']).toBeUndefined();
+    expect(getTypeDXN(contact)?.toString()).toBe(getSchemaDXN(TestSchema.Person)!.toString());
+    expect(isInstanceOf(TestSchema.Person, contact)).toBe(true);
+  });
+
+  test('JSON encoding', () => {
+    const contact = createObject(TestSchema.Person, {
+      name: 'Bot',
+      email: 'bot@example.com',
+    });
+
+    const json = JSON.parse(JSON.stringify(contact));
+    expect(json).toEqual({
+      id: contact.id,
+      '@type': DXN.fromTypenameAndVersion(TestSchema.Person.typename, TestSchema.Person.version).toString(),
+      '@meta': {
+        keys: [],
+      },
+      name: 'Bot',
+      email: 'bot@example.com',
+    });
+    expect(objectToJSON(contact)).toStrictEqual(json);
+  });
+
+  test('JSON encoding with relation', () => {
+    const person1 = createObject(TestSchema.Person, {
+      name: 'Alice',
+      email: 'alice@example.com',
+    });
+    const person2 = createObject(TestSchema.Person, {
+      name: 'Bob',
+      email: 'bob@example.com',
+    });
+
+    const manager = createObject(TestSchema.HasManager, {
+      [Relation.Source]: person1 as any,
+      [Relation.Target]: person2 as any,
+    });
+
+    const json = JSON.parse(JSON.stringify(manager));
+    expect(json).toEqual({
+      id: manager.id,
+      [ATTR_TYPE]: DXN.fromTypenameAndVersion(TestSchema.HasManager.typename, TestSchema.HasManager.version).toString(),
+      [ATTR_RELATION_SOURCE]: DXN.fromLocalObjectId(person1.id).toString(),
+      [ATTR_RELATION_TARGET]: DXN.fromLocalObjectId(person2.id).toString(),
+      [ATTR_META]: {
+        keys: [],
+      },
+    });
+  });
+
+  test('getSchema', () => {
+    const contact = createObject(TestSchema.Person, {
+      name: 'Bot',
+      email: 'bot@example.com',
+    });
+
+    expect(getSchema(contact)).toBe(TestSchema.Person);
+  });
+
+  test('inspect', () => {
+    const contact = createObject(TestSchema.Person, {
+      name: 'Bot',
+      email: 'bot@example.com',
+    });
+
+    const text = inspect(contact);
+    expect(text).toContain('Bot');
+    expect(text).toContain('bot@example.com');
+    expect(text).toContain('example.com/type/Person');
+    expect(text).toContain('0.1.0');
+  });
+});

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

@@ -0,0 +1,95 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import type * as Schema from 'effect/Schema';
+
+import { raise } from '@dxos/debug';
+import { assertArgument, failedInvariant } from '@dxos/invariant';
+import { ObjectId } from '@dxos/keys';
+
+import { getSchemaDXN, getTypeAnnotation, setTypename } from '../annotations';
+import {
+  RelationSourceDXNId,
+  RelationSourceId,
+  RelationTargetDXNId,
+  RelationTargetId,
+  assertObjectModel,
+  getObjectDXN,
+} from '../entities';
+import { defineHiddenProperty } from '../proxy';
+import { EntityKind, KindId, MetaId, setSchema } from '../types';
+
+import { attachedTypedObjectInspector } from './inspect';
+import { attachTypedJsonSerializer } from './json-serializer';
+
+export type CreateObjectProps<T> = T extends { id: string } ? Omit<T, 'id' | KindId> & { id?: string } : T;
+
+/**
+ * Creates a new object instance from a schema and data, without signal reactivity.
+ * This static version creates plain JavaScript objects that are not reactive/observable.
+ * For reactive objects that automatically update UI when changed, use the regular live() function.
+ *
+ * @param schema - The Effect schema that defines the object's structure and type, piped into EchoObjectSchema
+ * @param data - The data to initialize the object with. The id and @type fields are handled automatically.
+ * @returns A new non-reactive object instance conforming to the schema
+ * @throws {Error} If the schema is not an object schema
+ * @throws {TypeError} If data contains an @type field
+ *
+ * @example
+ * ```ts
+ * const Contact = Schema.Struct({
+ *   name: Schema.String,
+ *   email: Schema.String,
+ * }).pipe(Type.object({
+ *   typename: 'example.com/type/Person',
+ *   version: '0.1.0',
+ * }))
+ *
+ * const contact = createObject(Contact, {
+ *   name: "John",
+ *   email: "john@example.com",
+ * })
+ * ```
+ */
+// TODO(burdon): Make internal.
+export const createObject = <S extends Schema.Schema.AnyNoContext>(
+  schema: S,
+  props: CreateObjectProps<Schema.Schema.Type<S>>,
+): CreateObjectProps<Schema.Schema.Type<S>> & { id: string; [KindId]: EntityKind } => {
+  const annotation = getTypeAnnotation(schema);
+  if (!annotation) {
+    throw new Error('Schema is not an ECHO schema');
+  }
+  assertArgument(!('@type' in props), 'data', '@type is not allowed');
+  assertArgument(!(RelationSourceDXNId in props), 'data', 'Relation source DXN is not allowed in the constructor');
+  assertArgument(!(RelationTargetDXNId in props), 'data', 'Relation target DXN is not allowed in the constructor');
+  assertArgument(
+    RelationSourceId in props === RelationTargetId in props,
+    'data',
+    'Relation source and target must be provided together',
+  );
+
+  // Raw object.
+  const obj = { ...props, id: props.id ?? ObjectId.random() };
+
+  // Metadata.
+  const kind = RelationSourceId in props ? EntityKind.Relation : EntityKind.Object;
+  defineHiddenProperty(obj, KindId, kind);
+  defineHiddenProperty(obj, MetaId, { keys: [] });
+  setSchema(obj, schema);
+  setTypename(obj, getSchemaDXN(schema) ?? failedInvariant('Missing schema DXN'));
+  attachTypedJsonSerializer(obj);
+  attachedTypedObjectInspector(obj);
+
+  // Relation.
+  if (kind === EntityKind.Relation) {
+    const sourceDXN = getObjectDXN(props[RelationSourceId]) ?? raise(new Error('Unresolved relation source'));
+    const targetDXN = getObjectDXN(props[RelationTargetId]) ?? raise(new Error('Unresolved relation target'));
+    defineHiddenProperty(obj, RelationSourceDXNId, sourceDXN);
+    defineHiddenProperty(obj, RelationTargetDXNId, targetDXN);
+  }
+
+  assertObjectModel(obj);
+  return obj;
+};

package/src/internal/object/deleted.ts

@@ -0,0 +1,19 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { ObjectDeletedId } from '../entities';
+import { type AnyProperties } from '../types';
+
+/**
+ * @returns `true` if the object has been marked as deleted.
+ */
+export const isDeleted = (obj: AnyProperties): boolean => {
+  if ((obj as any)[ObjectDeletedId] === undefined) {
+    // TODO(dmaretskyi): Return to prior behavior of throwing.
+    // throw new Error('Object does not support deletion marker');
+    return false;
+  }
+
+  return (obj as any)[ObjectDeletedId] ?? false;
+};

package/src/internal/object/ids.ts

@@ -0,0 +1,12 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { DXN, ObjectId, QueueSubspaceTags, SpaceId } from '@dxos/keys';
+
+/**
+ * @deprecated Use `db.queues.create()`
+ */
+// TODO(burdon): Move to @dxos/keys.
+export const createQueueDXN = (spaceId = SpaceId.random(), queueId = ObjectId.random()) =>
+  new DXN(DXN.kind.QUEUE, [QueueSubspaceTags.DATA, spaceId, queueId]);

package/src/internal/object/index.ts

@@ -0,0 +1,14 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+export * from './common';
+export * from './create-object';
+export * from './deleted';
+export * from './ids';
+export * from './json-serializer';
+export * from './schema-validator';
+export * from './set-value';
+export * from './snapshot';
+export * from './typed-object';
+export * from './clone';

package/src/internal/object/inspect.ts

@@ -0,0 +1,46 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import type { InspectOptionsStylized, inspect as inspectFn } from 'node:util';
+
+import { type CustomInspectFunction, inspectCustom } from '@dxos/debug';
+
+import { getTypeDXN } from '../annotations';
+import { ATTR_META, ATTR_TYPE, type AnyEntity, MetaId } from '../types';
+
+/*
+ * @internal
+ */
+export const attachedTypedObjectInspector = (obj: any) => {
+  const descriptor = Object.getOwnPropertyDescriptor(obj, inspectCustom);
+  if (descriptor) {
+    return;
+  }
+
+  Object.defineProperty(obj, inspectCustom, {
+    value: typedObjectInspectFunction,
+    writable: false,
+    enumerable: false,
+    configurable: true,
+  });
+};
+
+// NOTE: KEEP as function.
+const typedObjectInspectFunction: CustomInspectFunction<AnyEntity> = function (
+  this: AnyEntity,
+  depth: number,
+  options: InspectOptionsStylized,
+  inspect: typeof inspectFn,
+) {
+  const { id, ...props } = this;
+  return inspect(
+    {
+      id,
+      [ATTR_TYPE]: getTypeDXN(this),
+      ...props,
+      [ATTR_META]: (this as any)[MetaId], // TODO(dmaretskyi): Couldn't use getMeta since that throw's if the object has no meta.
+    },
+    options,
+  );
+};

package/src/internal/object/json-serializer.test.ts

@@ -0,0 +1,97 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { describe, expect, test } from 'vitest';
+
+import { DXN } from '@dxos/keys';
+
+import * as Obj from '../../Obj';
+import { TestSchema } from '../../testing';
+import { getSchemaDXN, getSchemaTypename, getTypeDXN, getTypename } from '../annotations';
+import { RelationSourceId, RelationTargetId, getObjectDXN } from '../entities';
+import { makeObject } from '../proxy';
+import { Ref, StaticRefResolver } from '../ref';
+import { ATTR_TYPE, EntityKind, KindId, MetaId, TypeId, getMeta, getSchema } from '../types';
+
+import { createObject } from './create-object';
+import { objectFromJSON, objectToJSON } from './json-serializer';
+
+describe('Object JSON serializer', () => {
+  test('should serialize and deserialize object', async () => {
+    const contact = makeObject(TestSchema.Person, { name: 'Alice' });
+    Obj.change(contact, (c) => {
+      getMeta(c).keys.push({ id: '12345', source: 'example.com' });
+    });
+
+    const task = createObject(TestSchema.Task, {
+      title: 'Fix the tests',
+      assignee: Ref.make(contact),
+    });
+
+    const contactJson = objectToJSON(contact);
+    const taskJson = objectToJSON(task);
+
+    expect(contactJson.id).toBe(contact.id);
+    expect(contactJson[ATTR_TYPE]).toEqual(getSchemaDXN(TestSchema.Person)!.toString());
+    expect(contactJson.name).toEqual('Alice');
+
+    expect(taskJson.id).toBe(task.id);
+    expect(taskJson[ATTR_TYPE]).toEqual(getSchemaDXN(TestSchema.Task)!.toString());
+    expect(taskJson.title).toEqual('Fix the tests');
+    expect(taskJson.assignee).toEqual({ '/': DXN.fromLocalObjectId(contact.id).toString() });
+
+    const refResolver = new StaticRefResolver()
+      .addSchema(TestSchema.Person)
+      .addSchema(TestSchema.Task)
+      .addObject(contact)
+      .addObject(task);
+
+    const contactFromJson = (await objectFromJSON(contactJson, { refResolver })) as TestSchema.Person;
+    const taskFromJson = (await objectFromJSON(taskJson, { refResolver })) as TestSchema.Task;
+
+    expect(contactFromJson.id).toBe(contact.id);
+    expect(contactFromJson.name).toBe('Alice');
+    expect((contactFromJson as any)[TypeId]).toEqual(getSchemaDXN(TestSchema.Person));
+    expect((contactFromJson as any)[KindId]).toBe(EntityKind.Object);
+    expect((contactFromJson as any)[RelationSourceId]).toBeUndefined();
+    expect((contactFromJson as any)[RelationTargetId]).toBeUndefined();
+    expect((contactFromJson as any)[MetaId]).toEqual({
+      keys: [
+        {
+          id: '12345',
+          source: 'example.com',
+        },
+      ],
+    });
+    expect(getTypeDXN(contactFromJson)?.toString()).toBe(getSchemaDXN(TestSchema.Person)!.toString());
+    expect(getTypename(contactFromJson)).toBe(getSchemaTypename(TestSchema.Person));
+    expect(getObjectDXN(contactFromJson)?.toString()).toEqual(getObjectDXN(contact)?.toString());
+    expect(getSchema(contactFromJson)).toEqual(TestSchema.Person);
+
+    expect(taskFromJson.id).toBe(task.id);
+    expect(taskFromJson.title).toBe('Fix the tests');
+    expect(taskFromJson.assignee!.dxn).toEqual(DXN.fromLocalObjectId(contact.id));
+    expect(taskFromJson.assignee!.target).toEqual(contact);
+    expect(await taskFromJson.assignee!.load()).toEqual(contact);
+    expect((taskFromJson as any)[TypeId]).toEqual(getSchemaDXN(TestSchema.Task));
+    expect((taskFromJson as any)[KindId]).toBe(EntityKind.Object);
+    expect((taskFromJson as any)[RelationSourceId]).toBeUndefined();
+    expect((taskFromJson as any)[RelationTargetId]).toBeUndefined();
+    expect((taskFromJson as any)[MetaId]).toEqual({ keys: [] });
+    expect(getSchema(taskFromJson)).toEqual(TestSchema.Task);
+  });
+
+  test('serialize with unresolved schema', async () => {
+    const contact = createObject(TestSchema.Person, { name: 'Alice' });
+    const contactJson = objectToJSON(contact);
+    const contactFromJson: any = await objectFromJSON(contactJson);
+
+    expect(contactFromJson.id).toBe(contact.id);
+    expect(contactFromJson.name).toBe('Alice');
+    expect(getSchema(contactFromJson)).toBeUndefined();
+    expect(getTypename(contactFromJson)).toEqual(getSchemaTypename(TestSchema.Person));
+    expect(getObjectDXN(contactFromJson)).toEqual(getObjectDXN(contact));
+    expect(getTypeDXN(contactFromJson)).toEqual(getSchemaDXN(TestSchema.Person));
+  });
+});

package/src/internal/object/json-serializer.ts

@@ -0,0 +1,188 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+
+import { raise } from '@dxos/debug';
+import { type EncodedReference, ObjectStructure, isEncodedReference } from '@dxos/echo-protocol';
+import { assertArgument, invariant } from '@dxos/invariant';
+import { DXN, ObjectId } from '@dxos/keys';
+import { assumeType, deepMapValues, visitValues } from '@dxos/util';
+
+import type * as Obj from '../../Obj';
+import { getTypeDXN, setTypename } from '../annotations';
+import {
+  ATTR_DELETED,
+  ATTR_RELATION_SOURCE,
+  ATTR_RELATION_TARGET,
+  ATTR_SELF_DXN,
+  type ObjectJSON,
+  RelationSourceDXNId,
+  RelationSourceId,
+  RelationTargetDXNId,
+  RelationTargetId,
+  SelfDXNId,
+  assertObjectModel,
+} from '../entities';
+import { attachTypedJsonSerializer, defineHiddenProperty, typedJsonSerializer } from '../proxy';
+import { Ref, type RefResolver, refFromEncodedReference, setRefResolver } from '../ref';
+import {
+  ATTR_META,
+  ATTR_TYPE,
+  type AnyEntity,
+  EntityKind,
+  KindId,
+  MetaId,
+  ObjectMetaSchema,
+  setSchema,
+} from '../types';
+
+// Re-export for backward compatibility.
+export { attachTypedJsonSerializer };
+
+type DeepReplaceRef<T> =
+  T extends Ref<any>
+    ? EncodedReference
+    : T extends object
+      ? {
+          [K in keyof T]: DeepReplaceRef<T[K]>;
+        }
+      : T;
+
+type SerializedObject<T extends { id: string }> = {
+  [K in keyof T]: DeepReplaceRef<T[K]>;
+} & ObjectJSON;
+
+/**
+ * Converts object to it's JSON representation.
+ */
+export const objectToJSON = <T extends AnyEntity>(obj: T): SerializedObject<T> => {
+  const typename = getTypeDXN(obj)?.toString();
+  invariant(typename && typeof typename === 'string');
+  return typedJsonSerializer.call(obj);
+};
+
+/**
+ * Creates an object from it's json representation.
+ * Performs schema validation.
+ * References and schema will be resolvable if the `refResolver` is provided.
+ * The function need to be async to support resolving the schema as well as the relation endpoints.
+ */
+export const objectFromJSON = async (
+  jsonData: unknown,
+  { refResolver, dxn }: { refResolver?: RefResolver; dxn?: DXN } = {},
+): Promise<AnyEntity> => {
+  assumeType<ObjectJSON>(jsonData);
+  assertArgument(typeof jsonData === 'object' && jsonData !== null, 'jsonData', 'expect object');
+  assertArgument(typeof jsonData[ATTR_TYPE] === 'string', 'jsonData[ATTR_TYPE]', 'expected object to have a type');
+  assertArgument(typeof jsonData.id === 'string', 'jsonData.id', 'expected object to have an id');
+
+  const type = DXN.parse(jsonData[ATTR_TYPE]);
+  const schema = await refResolver?.resolveSchema(type);
+  invariant(schema === undefined || Schema.isSchema(schema));
+
+  let obj: any;
+  if (schema != null) {
+    obj = await schema.pipe(Schema.decodeUnknownPromise)(jsonData);
+    if (refResolver) {
+      setRefResolverOnData(obj, refResolver);
+    }
+  } else {
+    obj = decodeGeneric(jsonData, { refResolver });
+  }
+
+  invariant(ObjectId.isValid(obj.id), 'Invalid object id');
+  setTypename(obj, type);
+  if (schema) {
+    setSchema(obj, schema);
+  }
+
+  const isRelation =
+    typeof jsonData[ATTR_RELATION_SOURCE] === 'string' || typeof jsonData[ATTR_RELATION_TARGET] === 'string';
+  if (isRelation) {
+    const sourceDxn: DXN = DXN.parse(jsonData[ATTR_RELATION_SOURCE] ?? raise(new TypeError('Missing relation source')));
+    const targetDxn: DXN = DXN.parse(jsonData[ATTR_RELATION_TARGET] ?? raise(new TypeError('Missing relation target')));
+
+    const source = (await refResolver?.resolve(sourceDxn)) as AnyEntity | undefined;
+    const target = (await refResolver?.resolve(targetDxn)) as AnyEntity | undefined;
+
+    defineHiddenProperty(obj, KindId, EntityKind.Relation);
+    defineHiddenProperty(obj, RelationSourceDXNId, sourceDxn);
+    defineHiddenProperty(obj, RelationTargetDXNId, targetDxn);
+    defineHiddenProperty(obj, RelationSourceId, source);
+    defineHiddenProperty(obj, RelationTargetId, target);
+  } else {
+    defineHiddenProperty(obj, KindId, EntityKind.Object);
+  }
+
+  if (typeof jsonData[ATTR_META] === 'object') {
+    const meta = await ObjectMetaSchema.pipe(Schema.decodeUnknownPromise)(jsonData[ATTR_META]);
+    invariant(Array.isArray(meta.keys));
+    defineHiddenProperty(obj, MetaId, meta);
+  } else {
+    defineHiddenProperty(obj, MetaId, {
+      keys: [],
+    });
+  }
+
+  if (dxn) {
+    defineHiddenProperty(obj, SelfDXNId, dxn);
+  }
+
+  assertObjectModel(obj);
+  invariant((obj as any)[ATTR_TYPE] === undefined, 'Invalid object model');
+  invariant((obj as any)[ATTR_META] === undefined, 'Invalid object model');
+  invariant((obj as any)[ATTR_DELETED] === undefined, 'Invalid object model');
+  invariant((obj as any)[ATTR_SELF_DXN] === undefined, 'Invalid object model');
+  invariant((obj as any)[ATTR_RELATION_SOURCE] === undefined, 'Invalid object model');
+  invariant((obj as any)[ATTR_RELATION_TARGET] === undefined, 'Invalid object model');
+  return obj;
+};
+
+const decodeGeneric = (jsonData: unknown, options: { refResolver?: RefResolver }) => {
+  const {
+    [ATTR_TYPE]: _type,
+    [ATTR_META]: _meta,
+    [ATTR_DELETED]: _deleted,
+    [ATTR_SELF_DXN]: _selfDxn,
+    [ATTR_RELATION_SOURCE]: _relationSource,
+    [ATTR_RELATION_TARGET]: _relationTarget,
+    ...props
+  } = jsonData as any;
+
+  return deepMapValues(props, (value, visitor) => {
+    if (isEncodedReference(value)) {
+      return refFromEncodedReference(value, options.refResolver);
+    }
+
+    return visitor(value);
+  });
+};
+
+export const setRefResolverOnData = (obj: AnyEntity, refResolver: RefResolver) => {
+  const visitor = (value: unknown) => {
+    if (Ref.isRef(value)) {
+      setRefResolver(value, refResolver);
+    } else {
+      visitValues(value, visitor);
+    }
+  };
+
+  visitor(obj);
+};
+
+/**
+ * Convert ObjectStructure to JSON data for indexing.
+ * Different from {@link objectToJSON} as it takes the internal {@link ObjectStructure} representation directly
+ */
+export const objectStructureToJson = (objectId: string, structure: ObjectStructure): Obj.JSON => {
+  return {
+    ...structure.data,
+    id: objectId,
+    [ATTR_TYPE]: (ObjectStructure.getTypeReference(structure)?.['/'] ?? '') as DXN.String,
+    [ATTR_DELETED]: ObjectStructure.isDeleted(structure),
+    [ATTR_RELATION_SOURCE]: ObjectStructure.getRelationSource(structure)?.['/'] as DXN.String | undefined,
+    [ATTR_RELATION_TARGET]: ObjectStructure.getRelationTarget(structure)?.['/'] as DXN.String | undefined,
+  };
+};