@dxos/echo 0.8.4-main.fffef41 → 0.8.4-staging.60fe92afc8

package/src/internal/ast/annotations.ts

@@ -1,226 +0,0 @@
-//
-// Copyright 2024 DXOS.org
-//
-
-import * as Function from 'effect/Function';
-import * as Option from 'effect/Option';
-import * as Schema from 'effect/Schema';
-import * as SchemaAST from 'effect/SchemaAST';
-
-import { assertArgument } from '@dxos/invariant';
-import { DXN } from '@dxos/keys';
-import { type Primitive } from '@dxos/util';
-
-import { createAnnotationHelper } from './annotation-helper';
-import { EntityKind } from './entity-kind';
-
-/**
- * If property is optional returns the nested property, otherwise returns the property.
- */
-// TODO(wittjosiah): Is there a way to do this as a generic?
-export const unwrapOptional = (property: SchemaAST.PropertySignature) => {
-  if (!property.isOptional || !SchemaAST.isUnion(property.type)) {
-    return property;
-  }
-
-  return property.type.types[0];
-};
-
-/**
- * ECHO identifier (for a stored schema).
- * Must be a `dxn:echo:` URI.
- */
-export const TypeIdentifierAnnotationId = Symbol.for('@dxos/schema/annotation/TypeIdentifier');
-
-export const getTypeIdentifierAnnotation = (schema: Schema.Schema.All) =>
-  Function.flow(
-    SchemaAST.getAnnotation<string>(TypeIdentifierAnnotationId),
-    Option.getOrElse(() => undefined),
-  )(schema.ast);
-
-/**
- * ECHO type.
- */
-export const TypeAnnotationId = Symbol.for('@dxos/schema/annotation/Type');
-
-// TODO(burdon): Create echo-schema Format types.
-// TODO(burdon): Reconcile with "short" DXN.
-export const Typename = Schema.String.pipe(Schema.pattern(/^[a-zA-Z]\w+\.[a-zA-Z]\w{1,}\/[\w/_-]+$/));
-export const SchemaVersion = Schema.String.pipe(Schema.pattern(/^\d+.\d+.\d+$/));
-
-/**
- * Payload stored under {@link TypeAnnotationId}.
- */
-// TODO(dmaretskyi): Rename getTypeAnnotation to represent commonality between objects and relations (e.g. `entity`).
-export const TypeAnnotation = Schema.Struct({
-  kind: Schema.Enums(EntityKind),
-  typename: Typename,
-  version: SchemaVersion,
-
-  /**
-   * If this is a relation, the schema of the source object.
-   * Must be present if entity kind is {@link EntityKind.Relation}.
-   */
-  sourceSchema: Schema.optional(DXN.Schema),
-
-  /**
-   * If this is a relation, the schema of the target object.
-   * Must be present if entity kind is {@link EntityKind.Relation}.
-   */
-  targetSchema: Schema.optional(DXN.Schema),
-});
-
-export interface TypeAnnotation extends Schema.Schema.Type<typeof TypeAnnotation> {}
-
-export type TypeMeta = Pick<TypeAnnotation, 'typename' | 'version'>;
-
-/**
- * @returns {@link TypeAnnotation} from a schema.
- * Schema must have been created with {@link TypedObject} or {@link TypedLink} or manually assigned an appropriate annotation.
- */
-export const getTypeAnnotation = (schema: Schema.Schema.All): TypeAnnotation | undefined => {
-  assertArgument(schema != null && schema.ast != null, 'schema', 'invalid schema');
-  return Function.flow(
-    SchemaAST.getAnnotation<TypeAnnotation>(TypeAnnotationId),
-    Option.getOrElse(() => undefined),
-  )(schema.ast);
-};
-
-/**
- * @returns {@link EntityKind} from a schema.
- */
-export const getEntityKind = (schema: Schema.Schema.All): EntityKind | undefined => getTypeAnnotation(schema)?.kind;
-
-/**
- * @deprecated Use {@link Type.getTypename} instead.
- * @returns Schema typename (without dxn: prefix or version number).
- */
-export const getSchemaTypename = (schema: Schema.Schema.All): string | undefined => getTypeAnnotation(schema)?.typename;
-
-/**
- * @deprecated Use {@link Type.getVersion} instead.
- * @returns Schema version in semver format.
- */
-export const getSchemaVersion = (schema: Schema.Schema.All): string | undefined => getTypeAnnotation(schema)?.version;
-
-/**
- * PropertyMeta (metadata for dynamic schema properties).
- * For user-defined annotations.
- */
-export const PropertyMetaAnnotationId = Symbol.for('@dxos/schema/annotation/PropertyMeta');
-
-export type PropertyMetaValue = Primitive | Record<string, Primitive> | Primitive[];
-
-export type PropertyMetaAnnotation = {
-  [name: string]: PropertyMetaValue;
-};
-
-export const PropertyMeta = (name: string, value: PropertyMetaValue) => {
-  return <A, I, R>(self: Schema.Schema<A, I, R>): Schema.Schema<A, I, R> => {
-    const existingMeta = self.ast.annotations[PropertyMetaAnnotationId] as PropertyMetaAnnotation;
-    return self.annotations({
-      [PropertyMetaAnnotationId]: {
-        ...existingMeta,
-        [name]: value,
-      },
-    });
-  };
-};
-
-export const getPropertyMetaAnnotation = <T>(prop: SchemaAST.PropertySignature, name: string) =>
-  Function.pipe(
-    SchemaAST.getAnnotation<PropertyMetaAnnotation>(PropertyMetaAnnotationId)(prop.type),
-    Option.map((meta) => meta[name] as T),
-    Option.getOrElse(() => undefined),
-  );
-
-/**
- * Schema reference.
- */
-export const ReferenceAnnotationId = Symbol.for('@dxos/schema/annotation/Reference');
-
-export type ReferenceAnnotationValue = TypeAnnotation;
-
-export const getReferenceAnnotation = (schema: Schema.Schema.AnyNoContext) =>
-  Function.pipe(
-    SchemaAST.getAnnotation<ReferenceAnnotationValue>(ReferenceAnnotationId)(schema.ast),
-    Option.getOrElse(() => undefined),
-  );
-
-/**
- * SchemaMeta.
- */
-export const SchemaMetaSymbol = Symbol.for('@dxos/schema/SchemaMeta');
-
-export type SchemaMeta = TypeMeta & { id: string };
-
-/**
- * Identifies a schema as a view.
- */
-export const ViewAnnotationId = Symbol.for('@dxos/schema/annotation/View');
-export const ViewAnnotation = createAnnotationHelper<boolean>(ViewAnnotationId);
-
-/**
- * Identifies label property or JSON path expression.
- * Either a string or an array of strings representing field accessors each matched in priority order.
- */
-export const LabelAnnotationId = Symbol.for('@dxos/schema/annotation/Label');
-export const LabelAnnotation = createAnnotationHelper<string[]>(LabelAnnotationId);
-
-/**
- * Identifies description property or JSON path expression.
- * A string representing field accessor.
- */
-export const DescriptionAnnotationId = Symbol.for('@dxos/schema/annotation/Description');
-export const DescriptionAnnotation = createAnnotationHelper<string>(DescriptionAnnotationId);
-
-/**
- * Identifies if a property should be included in a form or not.
- * By default, all properties are included in forms, so this is opt-out.
- */
-export const FormAnnotationId = Symbol.for('@dxos/schema/annotation/Form');
-export const FormAnnotation = createAnnotationHelper<boolean>(FormAnnotationId);
-
-/**
- * Default field to be used on referenced schema to lookup the value.
- */
-export const FieldLookupAnnotationId = Symbol.for('@dxos/schema/annotation/FieldLookup');
-
-/**
- * Generate test data.
- */
-export const GeneratorAnnotationId = Symbol.for('@dxos/schema/annotation/Generator');
-
-export type GeneratorAnnotationValue =
-  | string
-  | {
-      generator: string;
-      args?: any[];
-      probability?: number;
-    };
-
-export const GeneratorAnnotation = createAnnotationHelper<GeneratorAnnotationValue>(GeneratorAnnotationId);
-
-/**
- * @returns DXN of the schema.
- *
- * For non-stored schema returns `dxn:type:`.
- * For stored schema returns `dxn:echo:`.
- * @deprecated Use `Type.getDXN`.
- */
-export const getSchemaDXN = (schema: Schema.Schema.All): DXN | undefined => {
-  assertArgument(Schema.isSchema(schema), 'schema', 'invalid schema');
-
-  const id = getTypeIdentifierAnnotation(schema);
-  if (id) {
-    return DXN.parse(id);
-  }
-
-  // TODO(dmaretskyi): Add support for dynamic schema.
-  const objectAnnotation = getTypeAnnotation(schema);
-  if (!objectAnnotation) {
-    return undefined;
-  }
-
-  return DXN.fromTypenameAndVersion(objectAnnotation.typename, objectAnnotation.version);
-};

package/src/internal/ast/entity-kind.ts

@@ -1,15 +0,0 @@
-//
-// Copyright 2025 DXOS.org
-//
-
-import * as Schema from 'effect/Schema';
-
-/**
- * Kinds of entities stored in ECHO: objects and relations.
- */
-export enum EntityKind {
-  Object = 'object',
-  Relation = 'relation',
-}
-
-export const EntityKindSchema = Schema.Enums(EntityKind);

package/src/internal/ast/index.ts

@@ -1,8 +0,0 @@
-//
-// Copyright 2024 DXOS.org
-//
-
-export * from './annotations';
-export * from './annotation-helper';
-export * from './types';
-export * from './entity-kind';

package/src/internal/ast/types.ts

@@ -1,17 +0,0 @@
-//
-// Copyright 2024 DXOS.org
-//
-
-import { PropertyMeta } from './annotations';
-
-/**
- * @internal
- */
-export const FIELD_PATH_ANNOTATION = 'path';
-
-/**
- * Sets the path for the field.
- * @param path Data source path in the json path format. This is the field path in the source object.
- */
-// TODO(burdon): Field, vs. path vs. property.
-export const FieldPath = (path: string) => PropertyMeta(FIELD_PATH_ANNOTATION, path);

package/src/internal/object/accessors.ts

@@ -1,153 +0,0 @@
-//
-// Copyright 2025 DXOS.org
-//
-
-import * as Option from 'effect/Option';
-import * as Schema from 'effect/Schema';
-
-import { type JsonPath, getField } from '@dxos/effect';
-import { assertArgument, invariant } from '@dxos/invariant';
-import { DXN, ObjectId } from '@dxos/keys';
-import { assumeType } from '@dxos/util';
-
-import { DescriptionAnnotation, LabelAnnotation } from '../ast';
-
-import { type InternalObjectProps, SchemaId, SelfDXNId } from './model';
-
-//
-// Accessors based on model.
-//
-
-/**
- * Returns a DXN for an object or schema.
- * @deprecated Use `Obj.getDXN`.
- */
-export const getObjectDXN = (object: any): DXN | undefined => {
-  invariant(!Schema.isSchema(object), 'schema not allowed in this function');
-  assertArgument(typeof object === 'object' && object != null, 'object', 'expected object');
-  assumeType<InternalObjectProps>(object);
-
-  if (object[SelfDXNId]) {
-    invariant(object[SelfDXNId] instanceof DXN, 'Invalid object model: invalid self dxn');
-    return object[SelfDXNId];
-  }
-
-  if (!ObjectId.isValid(object.id)) {
-    throw new TypeError('Object id is not valid.');
-  }
-
-  return DXN.fromLocalObjectId(object.id);
-};
-
-/**
- * Returns the schema for the given object if one is defined.
- */
-// TODO(burdon): Reconcile with `getTypename`.
-// TODO(dmaretskyi): For echo objects, this always returns the root schema.
-export const getSchema = (obj: unknown | undefined): Schema.Schema.AnyNoContext | undefined => {
-  if (obj) {
-    return (obj as any)[SchemaId];
-  }
-};
-
-/**
- * Internal use only.
- */
-export const setSchema = (obj: any, schema: Schema.Schema.AnyNoContext) => {
-  Object.defineProperty(obj, SchemaId, {
-    value: schema,
-    writable: false,
-    enumerable: false,
-    configurable: false,
-  });
-};
-
-/**
- * @deprecated Use {@link Obj.getLabel} instead.
- * Returns the label for a given object based on {@link LabelAnnotationId}.
- */
-export const getLabelForObject = (obj: unknown | undefined): string | undefined => {
-  const schema = getSchema(obj);
-  if (schema) {
-    return getLabel(schema, obj);
-  }
-};
-
-/**
- * Returns the label for a given object based on {@link LabelAnnotationId}.
- */
-// TODO(burdon): Convert to JsonPath?
-export const getLabel = <S extends Schema.Schema.Any>(schema: S, object: Schema.Schema.Type<S>): string | undefined => {
-  const annotation = LabelAnnotation.get(schema).pipe(Option.getOrElse(() => ['name']));
-  for (const accessor of annotation) {
-    assertArgument(
-      typeof accessor === 'string',
-      'accessor',
-      'Label annotation must be a string or an array of strings',
-    );
-    const value = getField(object, accessor as JsonPath);
-    switch (typeof value) {
-      case 'string':
-      case 'number':
-      case 'boolean':
-      case 'bigint':
-      case 'symbol':
-        return value.toString();
-      case 'undefined':
-      case 'object':
-      case 'function':
-        continue;
-    }
-  }
-
-  return undefined;
-};
-
-/**
- * Sets the label for a given object based on {@link LabelAnnotationId}.
- */
-export const setLabel = <S extends Schema.Schema.Any>(schema: S, object: Schema.Schema.Type<S>, label: string) => {
-  const annotation = LabelAnnotation.get(schema).pipe(
-    Option.map((field) => field[0]),
-    Option.getOrElse(() => 'name'),
-  );
-  object[annotation] = label;
-};
-
-/**
- * Returns the label for a given object based on {@link LabelAnnotationId}.
- */
-// TODO(burdon): Convert to JsonPath?
-export const getDescription = <S extends Schema.Schema.Any>(
-  schema: S,
-  object: Schema.Schema.Type<S>,
-): string | undefined => {
-  const accessor = DescriptionAnnotation.get(schema).pipe(Option.getOrElse(() => 'description'));
-  assertArgument(typeof accessor === 'string', 'accessor', 'Description annotation must be a string');
-  const value = getField(object, accessor as JsonPath);
-  switch (typeof value) {
-    case 'string':
-    case 'number':
-    case 'boolean':
-    case 'bigint':
-    case 'symbol':
-      return value.toString();
-    case 'undefined':
-    case 'object':
-    case 'function':
-    default:
-      return undefined;
-  }
-};
-
-/**
- * Sets the description for a given object based on {@link DescriptionAnnotationId}.
- */
-export const setDescription = <S extends Schema.Schema.Any>(
-  schema: S,
-  object: Schema.Schema.Type<S>,
-  description: string,
-) => {
-  const accessor = DescriptionAnnotation.get(schema).pipe(Option.getOrElse(() => 'description'));
-  object[accessor] = description;
-};

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

@@ -1,118 +0,0 @@
-//
-// 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 { getSchemaDXN } from '../ast';
-import { Testing } from '../testing';
-import { isInstanceOf } from '../types';
-
-import { getSchema } from './accessors';
-import { create } from './create';
-import { objectToJSON } from './json-serializer';
-import { RelationSourceId, RelationTargetId } from './model';
-import { getType } from './typename';
-
-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 = create(Testing.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(getType(contact)?.toString()).toBe(getSchemaDXN(Testing.Person)!.toString());
-    expect(isInstanceOf(Testing.Person, contact)).toBe(true);
-  });
-
-  test('JSON encoding', () => {
-    const contact = create(Testing.Person, {
-      name: 'Bot',
-      email: 'bot@example.com',
-    });
-
-    const json = JSON.parse(JSON.stringify(contact));
-    expect(json).toEqual({
-      id: contact.id,
-      '@type': DXN.fromTypenameAndVersion(Testing.Person.typename, Testing.Person.version).toString(),
-      '@meta': {
-        keys: [],
-      },
-      name: 'Bot',
-      email: 'bot@example.com',
-    });
-    expect(objectToJSON(contact)).toStrictEqual(json);
-  });
-
-  test('JSON encoding with relation', () => {
-    const contactA = create(Testing.Person, {
-      name: 'Bot',
-      email: 'bot@example.com',
-    });
-    const contactB = create(Testing.Person, {
-      name: 'Bot',
-      email: 'bot@example.com',
-    });
-    const hasManager = create(Testing.HasManager, {
-      [RelationSourceId]: contactA,
-      [RelationTargetId]: contactB,
-    });
-
-    const json = JSON.parse(JSON.stringify(hasManager));
-    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': {
-        keys: [],
-      },
-    });
-  });
-
-  test('getSchema', () => {
-    const contact = create(Testing.Person, {
-      name: 'Bot',
-      email: 'bot@example.com',
-    });
-
-    expect(getSchema(contact)).toBe(Testing.Person);
-  });
-
-  test('inspect', () => {
-    const contact = create(Testing.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/Person');
-    expect(text).toContain('0.1.0');
-  });
-});

package/src/internal/object/create.ts

@@ -1,96 +0,0 @@
-//
-// 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 { 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 {
-  EntityKindId,
-  MetaId,
-  RelationSourceDXNId,
-  RelationSourceId,
-  RelationTargetDXNId,
-  RelationTargetId,
-  assertObjectModelShape,
-} from './model';
-import { setTypename } from './typename';
-
-// Make `id` optional.
-type CreateData<T> = T extends { id: string } ? Omit<T, 'id' | typeof EntityKindId> & { 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 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.Obj({
- *   typename: 'example.com/type/Person',
- *   version: '0.1.0',
- * }))
- *
- * // Creates a non-reactive contact object
- * const contact = create(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>(
-  schema: S,
-  data: CreateData<Schema.Schema.Type<S>>,
-): CreateData<Schema.Schema.Type<S>> & { id: string } => {
-  const annotation = getTypeAnnotation(schema);
-  if (!annotation) {
-    throw new Error('Schema is not an object 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(
-    RelationSourceId in data === RelationTargetId in data,
-    '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'));
-  setSchema(obj, schema);
-  attachTypedJsonSerializer(obj);
-  attachedTypedObjectInspector(obj);
-  defineHiddenProperty(obj, MetaId, { keys: [] });
-  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'));
-    defineHiddenProperty(obj, RelationSourceDXNId, sourceDXN);
-    defineHiddenProperty(obj, RelationTargetDXNId, targetDXN);
-  }
-
-  assertObjectModelShape(obj);
-  return obj;
-};

package/src/internal/object/deleted.ts

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