@dxos/echo 0.8.4-main.ae835ea → 0.8.4-main.bc2380dfbc

package/src/internal/ast/annotations.test.ts

@@ -1,98 +0,0 @@
-//
-// Copyright 2025 DXOS.org
-//
-
-import * as Schema from 'effect/Schema';
-import { describe, test } from 'vitest';
-
-import { EchoObject, getLabel } from '../object';
-
-import { LabelAnnotation, SchemaVersion, Typename } from './annotations';
-
-// TODO(dmaretskyi): Use one of the testing schemas.
-const TestObject = Schema.Struct({
-  name: Schema.optional(Schema.String),
-  fallbackName: Schema.optional(Schema.String),
-  other: Schema.String,
-}).pipe(LabelAnnotation.set(['name', 'fallbackName']));
-
-const a: Schema.Struct<typeof TestObject.fields> = TestObject;
-console.log(a);
-
-type TestObject = Schema.Schema.Type<typeof TestObject>;
-
-const TestEchoSchema = TestObject.pipe(
-  EchoObject({
-    typename: 'dxos.org/type/Test',
-    version: '0.1.0',
-  }),
-);
-type TestEchoSchema = Schema.Schema.Type<typeof TestEchoSchema>;
-
-describe('annotations', () => {
-  describe('Typename', () => {
-    test('should validate typename', ({ expect }) => {
-      // Valid.
-      expect(Typename.make('dxos.org/type/foo')).to.exist;
-      expect(Typename.make('dxos.org/type/foo-bar')).to.exist;
-      expect(Typename.make('dxos.org/type/foo_bar')).to.exist;
-
-      // Invalid.
-      expect(() => Typename.make('dxn:dxos.org')).to.throw();
-      expect(() => Typename.make('2dxos.org')).to.throw();
-      expect(() => Typename.make('dxos org')).to.throw();
-    });
-
-    test('should validate version', ({ expect }) => {
-      // Valid.
-      expect(SchemaVersion.make('0.1.0')).to.exist;
-
-      // Invalid.
-      expect(() => SchemaVersion.make('0.1.x')).to.throw();
-      expect(() => SchemaVersion.make('0.1.0-alpha')).to.throw();
-    });
-  });
-
-  describe('getLabel', () => {
-    test('should return first available label value', ({ expect }) => {
-      const obj: TestObject = {
-        name: 'Primary Name',
-        fallbackName: 'Fallback Name',
-        other: 'Other',
-      };
-
-      expect(getLabel(TestObject, obj)).toEqual('Primary Name');
-    });
-
-    test('should fallback to second path if first is undefined', ({ expect }) => {
-      const obj: TestObject = {
-        name: undefined,
-        fallbackName: 'Fallback Name',
-        other: 'Other',
-      };
-
-      expect(getLabel(TestObject, obj)).toEqual('Fallback Name');
-    });
-
-    test('should return undefined if no label paths resolve', ({ expect }) => {
-      const obj: TestObject = {
-        name: undefined,
-        fallbackName: undefined,
-        other: 'Other',
-      };
-
-      expect(getLabel(TestObject, obj)).toBeUndefined();
-    });
-
-    test('should return label from echo object', ({ expect }) => {
-      const obj: TestEchoSchema = {
-        id: 'test',
-        name: 'Primary Name',
-        fallbackName: 'Fallback Name',
-        other: 'Other',
-      };
-
-      expect(getLabel(TestEchoSchema, obj)).toEqual('Primary Name');
-    });
-  });
-});

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/json/index.ts

@@ -1,5 +0,0 @@
-//
-// Copyright 2024 DXOS.org
-//
-
-export * from './json-schema';

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/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;
-};