@dxos/echo 0.8.4-main.5ad4a44 → 0.8.4-main.66e292d

package/src/internal/{json → json-schema}/json-schema.ts

@@ -12,7 +12,7 @@ import type * as Types from 'effect/Types';
 
 import { raise } from '@dxos/debug';
 import { mapAst } from '@dxos/effect';
-import { invariant } from '@dxos/invariant';
+import { assertArgument, invariant } from '@dxos/invariant';
 import { DXN, ObjectId } from '@dxos/keys';
 import { log } from '@dxos/log';
 import { clearUndefined, orderKeys, removeProperties } from '@dxos/util';
@@ -21,33 +21,20 @@ import {
   type TypeAnnotation,
   TypeAnnotationId,
   TypeIdentifierAnnotationId,
-  getTypeAnnotation,
-  getTypeIdentifierAnnotation,
-} from '../ast';
-import { EntityKind, EntityKindSchema } from '../ast';
+  makeTypeJsonSchemaAnnotation,
+} from '../annotations';
+import { Expando } from '../entities';
+import { type JsonSchemaReferenceInfo, Ref, createEchoReferenceSchema } from '../ref';
+import { EntityKind, EntityKindSchema } from '../types';
+
+import { CustomAnnotations, DecodedAnnotations, EchoAnnotations } from './annotations';
 import {
   ECHO_ANNOTATIONS_NS_DEPRECATED_KEY,
   ECHO_ANNOTATIONS_NS_KEY,
   type JsonSchemaEchoAnnotations,
   type JsonSchemaType,
   getNormalizedEchoAnnotations,
-} from '../json-schema';
-import { Expando } from '../object';
-import { type JsonSchemaReferenceInfo, Ref, createEchoReferenceSchema } from '../ref';
-
-import { CustomAnnotations, DecodedAnnotations, EchoAnnotations } from './annotations';
-
-/**
- * Create object jsonSchema.
- */
-export const createJsonSchema = (schema: Schema.Struct<any> = Schema.Struct({})): JsonSchemaType => {
-  const jsonSchema = _toJsonSchema(schema);
-
-  // TODO(dmaretskyi): Fix those in the serializer.
-  jsonSchema.type = 'object';
-  delete jsonSchema.anyOf;
-  return jsonSchema;
-};
+} from './json-schema-type';
 
 // TODO(burdon): Are these values stored (can they be changed?)
 export enum PropType {
@@ -89,10 +76,14 @@ export type JsonSchemaOptions = {
 
 /**
  * Convert effect schema to JSON Schema.
+ * NOTE: This handles custom annotations.
  * @param schema
  */
+// TODO(burdon): Reconcile with possibly extending @effect/Schema/JSONSchema
+//  We add additional propertyOrder (but the object properties ARE ordered); and type "string" for literals.
 export const toJsonSchema = (schema: Schema.Schema.All, options: JsonSchemaOptions = {}): JsonSchemaType => {
-  let jsonSchema = _toJsonSchema(schema);
+  assertArgument(Schema.isSchema(schema), 'schema');
+  let jsonSchema = _toJsonSchemaAST(schema.ast);
   if (options.strict) {
     // TOOD(burdon): Workaround to ensure JSON schema is valid (for agv parsing).
     jsonSchema = removeProperties(jsonSchema, (key, value) => {
@@ -113,71 +104,13 @@ export const toJsonSchema = (schema: Schema.Schema.All, options: JsonSchemaOptio
   return jsonSchema;
 };
 
-const _toJsonSchema = (schema: Schema.Schema.All): JsonSchemaType => {
-  invariant(schema);
-  const withRefinements = withEchoRefinements(schema.ast, '#');
-  let jsonSchema = JSONSchema.fromAST(withRefinements, {
+const _toJsonSchemaAST = (ast: SchemaAST.AST): JsonSchemaType => {
+  const withRefinements = withEchoRefinements(ast, '#');
+  const jsonSchema = JSONSchema.fromAST(withRefinements, {
     definitions: {},
   }) as JsonSchemaType;
 
-  jsonSchema.$schema = JSON_SCHEMA_URL;
-
-  if (jsonSchema.properties && 'id' in jsonSchema.properties) {
-    jsonSchema.properties = orderKeys(jsonSchema.properties, ['id']); // Put id first.
-  }
-
-  const echoIdentifier = getTypeIdentifierAnnotation(schema);
-  if (echoIdentifier) {
-    jsonSchema.$id = echoIdentifier;
-  }
-
-  const objectAnnotation = getTypeAnnotation(schema);
-  if (objectAnnotation) {
-    // EchoIdentifier annotation takes precedence but the id can also be defined by the typename.
-    if (!jsonSchema.$id) {
-      // TODO(dmaretskyi): Should this include the version?
-      jsonSchema.$id = DXN.fromTypename(objectAnnotation.typename).toString();
-    }
-    jsonSchema.entityKind = objectAnnotation.kind;
-    jsonSchema.version = objectAnnotation.version;
-    jsonSchema.typename = objectAnnotation.typename;
-    if (jsonSchema.entityKind === EntityKind.Relation) {
-      jsonSchema.relationTarget = {
-        $ref: objectAnnotation.sourceSchema,
-      };
-      jsonSchema.relationSource = {
-        $ref: objectAnnotation.targetSchema,
-      };
-    }
-  }
-
-  // Fix field order.
-  // TODO(dmaretskyi): Makes sure undefined is not left on optional fields for the resulting object.
-  // TODO(dmaretskyi): `orderFields` util.
-  jsonSchema = orderKeys(jsonSchema, [
-    '$schema',
-    '$id',
-
-    'entityKind',
-    'typename',
-    'version',
-    'relationTarget',
-    'relationSource',
-
-    'type',
-    'enum',
-
-    'properties',
-    'required',
-    'propertyOrder', // Custom.
-    'items',
-    'additionalProperties',
-
-    'anyOf',
-    'oneOf',
-  ]);
-
-  return jsonSchema;
+  return normalizeJsonSchema(jsonSchema);
 };
 
 const withEchoRefinements = (
@@ -201,7 +134,7 @@ const withEchoRefinements = (
         },
       });
     } else {
-      const jsonSchema = _toJsonSchema(Schema.make(suspendedAst));
+      const jsonSchema = _toJsonSchemaAST(suspendedAst);
       recursiveResult = new SchemaAST.Suspend(() => withEchoRefinements(suspendedAst, path, suspendCache), {
         [SchemaAST.JSONSchemaAnnotationId]: jsonSchema,
       });
@@ -421,6 +354,7 @@ const refToEffectSchema = (root: any): Schema.Schema.AnyNoContext => {
   if (!('reference' in root)) {
     return Ref(Expando);
   }
+
   const reference: JsonSchemaReferenceInfo = root.reference;
   if (typeof reference !== 'object') {
     throw new Error('Invalid reference field in ref schema');
@@ -528,7 +462,17 @@ const jsonSchemaFieldsToAnnotations = (schema: JsonSchemaType): SchemaAST.Annota
   }
 
   annotations[TypeIdentifierAnnotationId] = decodeTypeIdentifierAnnotation(schema);
-  annotations[TypeAnnotationId] = decodeTypeAnnotation(schema);
+  const typeAnnotation = decodeTypeAnnotation(schema);
+  if (typeAnnotation) {
+    annotations[TypeAnnotationId] = typeAnnotation;
+    annotations[SchemaAST.JSONSchemaAnnotationId] = makeTypeJsonSchemaAnnotation({
+      kind: typeAnnotation.kind,
+      typename: typeAnnotation.typename,
+      version: typeAnnotation.version,
+      relationSource: typeAnnotation.sourceSchema,
+      relationTarget: typeAnnotation.targetSchema,
+    });
+  }
 
   // Custom (at end).
   for (const [key, annotationId] of Object.entries({ ...CustomAnnotations, ...DecodedAnnotations })) {
@@ -546,3 +490,39 @@ const makeAnnotatedRefinement = (ast: SchemaAST.AST, annotations: SchemaAST.Anno
 
 const addJsonSchemaFields = (ast: SchemaAST.AST, schema: JsonSchemaType): SchemaAST.AST =>
   makeAnnotatedRefinement(ast, { [SchemaAST.JSONSchemaAnnotationId]: schema });
+
+/**
+ * Fixes field order.
+ * Sets `$schema` prop.
+ */
+const normalizeJsonSchema = (jsonSchema: JsonSchemaType): JsonSchemaType => {
+  if (jsonSchema.properties && 'id' in jsonSchema.properties) {
+    jsonSchema.properties = orderKeys(jsonSchema.properties, ['id']); // Put id first.
+  }
+
+  // TODO(dmaretskyi): Makes sure undefined is not left on optional fields for the resulting object.
+  jsonSchema.$schema = JSON_SCHEMA_URL;
+  jsonSchema = orderKeys(jsonSchema, [
+    '$schema',
+    '$id',
+
+    'entityKind',
+    'typename',
+    'version',
+    'relationTarget',
+    'relationSource',
+
+    'type',
+    'enum',
+
+    'properties',
+    'required',
+    'propertyOrder', // Custom.
+    'items',
+    'additionalProperties',
+
+    'anyOf',
+    'oneOf',
+  ]);
+  return jsonSchema;
+};

package/src/internal/object/common.ts

@@ -4,9 +4,8 @@
 
 import * as Schema from 'effect/Schema';
 
-import { type BaseObject } from '../types';
-
-import { getTypename } from './typename';
+import { getTypename } from '../annotations';
+import { type AnyProperties } from '../types';
 
 // TODO(dmaretskyi): Rename to represent commonality between objects and relations (e.g. `entity`).
 export type TypedObjectOptions = {
@@ -58,7 +57,7 @@ export const makeTypedEntityClass = (
     static readonly pipe = baseSchema.pipe.bind(baseSchema);
 
     // TODO(burdon): Comment required.
-    static [Symbol.hasInstance](obj: BaseObject) {
+    static [Symbol.hasInstance](obj: AnyProperties) {
       return obj != null && getTypename(obj) === typename;
     }
 

package/src/internal/object/{create.test.ts → create-object.test.ts}

@@ -9,15 +9,14 @@ import { describe, expect, test } from 'vitest';
 
 import { DXN } from '@dxos/keys';
 
-import { getSchemaDXN } from '../ast';
-import { Testing } from '../testing';
-import { isInstanceOf } from '../types';
+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 { getSchema } from './accessors';
-import { create } from './create';
+import { createObject } from './create-object';
 import { objectToJSON } from './json-serializer';
-import { RelationSourceId, RelationTargetId } from './model';
-import { getType } from './typename';
 
 describe('create (static version)', () => {
   test('defaults', ({ expect }) => {
@@ -34,7 +33,7 @@ describe('create (static version)', () => {
   });
 
   test('create static object', () => {
-    const contact = create(Testing.Contact, {
+    const contact = createObject(TestSchema.Person, {
       name: 'Bot',
       email: 'bot@example.com',
     });
@@ -43,12 +42,12 @@ describe('create (static version)', () => {
     expect(contact.name).toBe('Bot');
     expect(contact.email).toBe('bot@example.com');
     expect((contact as any)['@type']).toBeUndefined();
-    expect(getType(contact)?.toString()).toBe(getSchemaDXN(Testing.Contact)!.toString());
-    expect(isInstanceOf(Testing.Contact, contact)).toBe(true);
+    expect(getTypeDXN(contact)?.toString()).toBe(getSchemaDXN(TestSchema.Person)!.toString());
+    expect(isInstanceOf(TestSchema.Person, contact)).toBe(true);
   });
 
   test('JSON encoding', () => {
-    const contact = create(Testing.Contact, {
+    const contact = createObject(TestSchema.Person, {
       name: 'Bot',
       email: 'bot@example.com',
     });
@@ -56,7 +55,7 @@ describe('create (static version)', () => {
     const json = JSON.parse(JSON.stringify(contact));
     expect(json).toEqual({
       id: contact.id,
-      '@type': DXN.fromTypenameAndVersion(Testing.Contact.typename, Testing.Contact.version).toString(),
+      '@type': DXN.fromTypenameAndVersion(TestSchema.Person.typename, TestSchema.Person.version).toString(),
       '@meta': {
         keys: [],
       },
@@ -67,52 +66,51 @@ describe('create (static version)', () => {
   });
 
   test('JSON encoding with relation', () => {
-    const contactA = create(Testing.Contact, {
-      name: 'Bot',
-      email: 'bot@example.com',
+    const person1 = createObject(TestSchema.Person, {
+      name: 'Alice',
+      email: 'alice@example.com',
     });
-    const contactB = create(Testing.Contact, {
-      name: 'Bot',
-      email: 'bot@example.com',
+    const person2 = createObject(TestSchema.Person, {
+      name: 'Bob',
+      email: 'bob@example.com',
     });
-    const hasManager = create(Testing.HasManager, {
-      [RelationSourceId]: contactA,
-      [RelationTargetId]: contactB,
+
+    const manager = createObject(TestSchema.HasManager, {
+      [Relation.Source]: person1 as any,
+      [Relation.Target]: person2 as any,
     });
 
-    const json = JSON.parse(JSON.stringify(hasManager));
+    const json = JSON.parse(JSON.stringify(manager));
     expect(json).toEqual({
-      id: hasManager.id,
-      '@type': DXN.fromTypenameAndVersion(Testing.HasManager.typename, Testing.HasManager.version).toString(),
-      '@relationSource': DXN.fromLocalObjectId(contactA.id).toString(),
-      '@relationTarget': DXN.fromLocalObjectId(contactB.id).toString(),
-      '@meta': {
+      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 = create(Testing.Contact, {
+    const contact = createObject(TestSchema.Person, {
       name: 'Bot',
       email: 'bot@example.com',
     });
 
-    expect(getSchema(contact)).toBe(Testing.Contact);
+    expect(getSchema(contact)).toBe(TestSchema.Person);
   });
 
   test('inspect', () => {
-    const contact = create(Testing.Contact, {
+    const contact = createObject(TestSchema.Person, {
       name: 'Bot',
       email: 'bot@example.com',
     });
 
-    // console.log(contact);
-
     const text = inspect(contact);
     expect(text).toContain('Bot');
     expect(text).toContain('bot@example.com');
-    expect(text).toContain('example.com/type/Contact');
+    expect(text).toContain('example.com/type/Person');
     expect(text).toContain('0.1.0');
   });
 });

package/src/internal/object/{create.ts → create-object.ts}

@@ -9,31 +9,28 @@ import { assertArgument, failedInvariant } from '@dxos/invariant';
 import { ObjectId } from '@dxos/keys';
 import { defineHiddenProperty } from '@dxos/live-object';
 
-import { EntityKind, getSchemaDXN, getTypeAnnotation } from '../ast';
-
-import { getObjectDXN, setSchema } from './accessors';
-import { attachedTypedObjectInspector } from './inspect';
-import { attachTypedJsonSerializer } from './json-serializer';
+import { getSchemaDXN, getTypeAnnotation, setTypename } from '../annotations';
 import {
-  EntityKindId,
-  MetaId,
   RelationSourceDXNId,
   RelationSourceId,
   RelationTargetDXNId,
   RelationTargetId,
-  assertObjectModelShape,
-} from './model';
-import { setTypename } from './typename';
+  assertObjectModel,
+  getObjectDXN,
+} from '../entities';
+import { EntityKind, KindId, MetaId, setSchema } from '../types';
+
+import { attachedTypedObjectInspector } from './inspect';
+import { attachTypedJsonSerializer } from './json-serializer';
 
-// Make `id` optional.
-type CreateData<T> = T extends { id: string } ? Omit<T, 'id' | typeof EntityKindId> & { id?: string } : T;
+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 EchoObject
+ * @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
@@ -45,52 +42,54 @@ type CreateData<T> = T extends { id: string } ? Omit<T, 'id' | typeof EntityKind
  *   name: Schema.String,
  *   email: Schema.String,
  * }).pipe(Type.Obj({
- *   typename: 'example.com/type/Contact',
+ *   typename: 'example.com/type/Person',
  *   version: '0.1.0',
  * }))
  *
- * // Creates a non-reactive contact object
- * const contact = create(Contact, {
+ * const contact = createObject(Contact, {
  *   name: "John",
  *   email: "john@example.com",
  * })
  * ```
  */
-// TODO(burdon): Rename make.
-// TODO(burdon): Handle defaults (see Schema.make).
-// TODO(dmaretskyi): Use `Obj.make` and `Relation.make` from '@dxos/echo' instead.
-export const create = <S extends Schema.Schema.AnyNoContext>(
+// TODO(burdon): Make internal.
+export const createObject = <S extends Schema.Schema.AnyNoContext>(
   schema: S,
-  data: CreateData<Schema.Schema.Type<S>>,
-): CreateData<Schema.Schema.Type<S>> & { id: string } => {
+  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 object schema');
+    throw new Error('Schema is not an ECHO schema');
   }
-  assertArgument(!('@type' in data), 'data', '@type is not allowed');
-  assertArgument(!(RelationSourceDXNId in data), 'data', 'Relation source DXN is not allowed in the constructor');
-  assertArgument(!(RelationTargetDXNId in data), 'data', 'Relation target DXN is not allowed in the constructor');
+  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 data === RelationTargetId in data,
+    RelationSourceId in props === RelationTargetId in props,
     'data',
     'Relation source and target must be provided together',
   );
 
-  const obj = { ...data, id: data.id ?? ObjectId.random() };
-  const kind = RelationSourceId in data ? EntityKind.Relation : EntityKind.Object;
-  defineHiddenProperty(obj, EntityKindId, kind);
-  setTypename(obj, getSchemaDXN(schema) ?? failedInvariant('Missing schema DXN'));
+  // 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);
-  defineHiddenProperty(obj, MetaId, { keys: [] });
+
+  // Relation.
   if (kind === EntityKind.Relation) {
-    const sourceDXN = getObjectDXN(data[RelationSourceId]) ?? raise(new Error('Unresolved relation source'));
-    const targetDXN = getObjectDXN(data[RelationTargetId]) ?? raise(new Error('Unresolved relation target'));
+    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);
   }
 
-  assertObjectModelShape(obj);
+  assertObjectModel(obj);
   return obj;
 };

package/src/internal/object/deleted.ts

@@ -2,18 +2,18 @@
 // Copyright 2025 DXOS.org
 //
 
-import type { BaseObject } from '../types';
-
-import { DeletedId } from './model';
+import { ObjectDeletedId } from '../entities';
+import { type AnyProperties } from '../types';
 
 /**
  * @returns `true` if the object has been marked as deleted.
  */
-export const isDeleted = (obj: BaseObject): boolean => {
-  if ((obj as any)[DeletedId] === undefined) {
+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)[DeletedId] ?? false;
+
+  return (obj as any)[ObjectDeletedId] ?? false;
 };

package/src/internal/object/ids.ts

@@ -4,9 +4,9 @@
 
 import { DXN, ObjectId, QueueSubspaceTags, SpaceId } from '@dxos/keys';
 
-// TODO(burdon): Move to @dxos/keys once ObjectId is moved there.
 /**
  * @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

@@ -3,18 +3,9 @@
 //
 
 export * from './common';
-export * from './create';
-export * from './entity';
-export * from './expando';
+export * from './create-object';
+export * from './deleted';
 export * from './ids';
 export * from './json-serializer';
-export * from './meta';
-export type * from './relation';
-export * from './typed-object';
-export * from './typed-relation';
-export * from './typename';
-export * from './deleted';
-export * from './model';
-export * from './accessors';
 export * from './schema-validator';
-export * from './version';
+export * from './typed-object';

package/src/internal/object/inspect.ts

@@ -6,10 +6,8 @@ import type { InspectOptionsStylized, inspect as inspectFn } from 'node:util';
 
 import { type CustomInspectFunction, inspectCustom } from '@dxos/debug';
 
-import { type AnyEchoObject } from '../types';
-
-import { ATTR_META, ATTR_TYPE, MetaId } from './model';
-import { getType } from './typename';
+import { getTypeDXN } from '../annotations';
+import { ATTR_META, ATTR_TYPE, type AnyEchoObject, MetaId } from '../types';
 
 /*
  * @internal
@@ -39,7 +37,7 @@ const typedObjectInspectFunction: CustomInspectFunction<AnyEchoObject> = functio
   return inspect(
     {
       id,
-      [ATTR_TYPE]: getType(this),
+      [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.
     },