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

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/entity.ts

@@ -1,248 +0,0 @@
-//
-// Copyright 2024 DXOS.org
-//
-
-import * as Schema from 'effect/Schema';
-import * as SchemaAST from 'effect/SchemaAST';
-import type * as Types from 'effect/Types';
-
-import { raise } from '@dxos/debug';
-import { assertArgument, invariant } from '@dxos/invariant';
-import { DXN } from '@dxos/keys';
-
-import {
-  EntityKind,
-  type TypeAnnotation,
-  TypeAnnotationId,
-  type TypeMeta,
-  getEntityKind,
-  getSchemaTypename,
-  getTypeIdentifierAnnotation,
-} from '../ast';
-import { type HasId, type ToMutable } from '../types';
-
-import { type RelationSourceTargetRefs } from './relation';
-
-// TODO(burdon): Define Schema type for `typename` and use consistently for all DXN-like properties.
-
-// type RequiredKeys<T> = { [K in keyof T]-?: {} extends Pick<T, K> ? never : K }[keyof T];
-type EchoTypeSchemaProps<T, ExtraFields = {}> = Types.Simplify<HasId & ToMutable<T> & ExtraFields>;
-
-export interface EchoTypeSchema<Self extends Schema.Schema.Any, ExtraFields = {}>
-  extends TypeMeta,
-    Schema.AnnotableClass<
-      EchoTypeSchema<Self, ExtraFields>,
-      EchoTypeSchemaProps<Schema.Schema.Type<Self>, ExtraFields>,
-      EchoTypeSchemaProps<Schema.Schema.Encoded<Self>, ExtraFields>,
-      Schema.Schema.Context<Self>
-    > {
-  // make(
-  //   props: RequiredKeys<Schema.TypeLiteral.Constructor<Fields, []>> extends never
-  //     ? void | Simplify<Schema.TypeLiteral.Constructor<Fields, []>>
-  //     : Simplify<Schema.TypeLiteral.Constructor<Fields, []>>,
-  //   options?: MakeOptions,
-  // ): Simplify<Schema.TypeLiteral.Type<Fields, []>>;
-
-  instanceOf(value: unknown): boolean;
-}
-
-/**
- * Pipeable function to add ECHO object annotations to a schema.
- */
-// TODO(dmaretskyi): Rename EchoObjectSchema.
-export const EchoObject: {
-  // TODO(burdon): Tighten Self type to Schema.TypeLiteral or Schema.Struct to facilitate definition of `make` method.
-  // (meta: TypeMeta): <Self extends Schema.Struct<Fields>, Fields extends Schema.Struct.Fields>(self: Self) => EchoObjectSchema<Self, Fields>;
-  (meta: TypeMeta): <Self extends Schema.Schema.Any>(self: Self) => EchoTypeSchema<Self>;
-} = ({ typename, version }) => {
-  return <Self extends Schema.Schema.Any>(self: Self): EchoTypeSchema<Self> => {
-    invariant(typeof TypeAnnotationId === 'symbol', 'Sanity.');
-    invariant(SchemaAST.isTypeLiteral(self.ast), 'Schema must be a TypeLiteral.');
-
-    // TODO(dmaretskyi): Does `Schema.mutable` work for deep mutability here?
-    // TODO(dmaretskyi): Do not do mutable here.
-    const schemaWithId = Schema.extend(Schema.mutable(self), Schema.Struct({ id: Schema.String }));
-    const ast = SchemaAST.annotations(schemaWithId.ast, {
-      // TODO(dmaretskyi): `extend` kills the annotations.
-      ...self.ast.annotations,
-      [TypeAnnotationId]: { kind: EntityKind.Object, typename, version } satisfies TypeAnnotation,
-      // TODO(dmaretskyi): TypeIdentifierAnnotationId?
-      [SchemaAST.JSONSchemaAnnotationId]: makeTypeJsonSchemaAnnotation({
-        kind: EntityKind.Object,
-        typename,
-        version,
-      }),
-    });
-
-    return makeEchoObjectSchema<Self>(/* self.fields, */ ast, typename, version);
-  };
-};
-
-export type EchoRelationOptions<
-  TSource extends Schema.Schema.AnyNoContext,
-  TTarget extends Schema.Schema.AnyNoContext,
-> = TypeMeta & {
-  source: TSource;
-  target: TTarget;
-};
-
-// TODO(dmaretskyi): Rename EchoRelationSchema.
-export const EchoRelation = <Source extends Schema.Schema.AnyNoContext, Target extends Schema.Schema.AnyNoContext>(
-  options: EchoRelationOptions<Source, Target>,
-) => {
-  assertArgument(Schema.isSchema(options.source), 'source');
-  assertArgument(Schema.isSchema(options.target), 'target');
-  const sourceDXN = getDXNForRelationSchemaRef(options.source);
-  const targetDXN = getDXNForRelationSchemaRef(options.target);
-  if (getEntityKind(options.source) !== EntityKind.Object) {
-    raise(new Error('Source schema must be an echo object schema.'));
-  }
-  if (getEntityKind(options.target) !== EntityKind.Object) {
-    raise(new Error('Target schema must be an echo object schema.'));
-  }
-
-  return <Self extends Schema.Schema.Any>(
-    self: Self,
-  ): EchoTypeSchema<Self, RelationSourceTargetRefs<Schema.Schema.Type<Source>, Schema.Schema.Type<Target>>> => {
-    invariant(SchemaAST.isTypeLiteral(self.ast), 'Schema must be a TypeLiteral.');
-
-    // TODO(dmaretskyi): Does `Schema.mutable` work for deep mutability here?
-    // TODO(dmaretskyi): Do not do mutable here.
-    const schemaWithId = Schema.extend(Schema.mutable(self), Schema.Struct({ id: Schema.String }));
-    const ast = SchemaAST.annotations(schemaWithId.ast, {
-      // TODO(dmaretskyi): `extend` kills the annotations.
-      ...self.ast.annotations,
-      [TypeAnnotationId]: {
-        kind: EntityKind.Relation,
-        typename: options.typename,
-        version: options.version,
-        sourceSchema: sourceDXN,
-        targetSchema: targetDXN,
-      } satisfies TypeAnnotation,
-      // TODO(dmaretskyi): TypeIdentifierAnnotationId?
-
-      [SchemaAST.JSONSchemaAnnotationId]: makeTypeJsonSchemaAnnotation({
-        kind: EntityKind.Relation,
-        typename: options.typename,
-        version: options.version,
-        relationSource: sourceDXN,
-        relationTarget: targetDXN,
-      }),
-    });
-
-    return makeEchoObjectSchema<Self>(/* self.fields, */ ast, options.typename, options.version);
-  };
-};
-
-/**
- * @returns JSON-schema annotation so that the schema can be serialized with correct parameters.
- */
-export const makeTypeJsonSchemaAnnotation = (options: {
-  identifier?: string;
-  kind: EntityKind;
-  typename: string;
-  version: string;
-  relationSource?: string;
-  relationTarget?: string;
-}) => {
-  assertArgument(!!options.relationSource === (options.kind === EntityKind.Relation), 'relationSource');
-  assertArgument(!!options.relationTarget === (options.kind === EntityKind.Relation), 'relationTarget');
-
-  const obj = {
-    // TODO(dmaretskyi): Should this include the version?
-    $id: options.identifier ?? DXN.fromTypename(options.typename).toString(),
-    entityKind: options.kind,
-    version: options.version,
-    typename: options.typename,
-  } as any;
-  if (options.kind === EntityKind.Relation) {
-    obj.relationSource = { $ref: options.relationSource };
-    obj.relationTarget = { $ref: options.relationTarget };
-  }
-  return obj;
-};
-
-const getDXNForRelationSchemaRef = (schema: Schema.Schema.Any): string => {
-  assertArgument(Schema.isSchema(schema), 'schema');
-  const identifier = getTypeIdentifierAnnotation(schema);
-  if (identifier) {
-    return identifier;
-  }
-
-  const typename = getSchemaTypename(schema);
-  if (!typename) {
-    throw new Error('Schema must have a typename');
-  }
-
-  return DXN.fromTypename(typename).toString();
-};
-
-// type MakeOptions =
-//   | boolean
-//   | {
-//       readonly disableValidation?: boolean;
-//     };
-
-// NOTE: Utils copied from Effect `Schema.ts`.
-// const _ownKeys = (o: object): Array<PropertyKey> =>
-//   (Object.keys(o) as Array<PropertyKey>).concat(Object.getOwnPropertySymbols(o));
-
-// const _lazilyMergeDefaults = (
-//   fields: Schema.Struct.Fields,
-//   out: Record<PropertyKey, unknown>,
-// ): { [x: string | symbol]: unknown } => {
-//   const ownKeys = _ownKeys(fields);
-//   for (const key of ownKeys) {
-//     const field = fields[key];
-//     if (out[key] === undefined && Schema.isPropertySignature(field)) {
-//       const ast = field.ast;
-//       const defaultValue = ast._tag === 'PropertySignatureDeclaration' ? ast.defaultValue : ast.to.defaultValue;
-//       if (defaultValue !== undefined) {
-//         out[key] = defaultValue();
-//       }
-//     }
-//   }
-//   return out;
-// };
-
-// const _getDisableValidationMakeOption = (options: MakeOptions | undefined): boolean =>
-//   Predicate.isBoolean(options) ? options : options?.disableValidation ?? false;
-
-const makeEchoObjectSchema = <Self extends Schema.Schema.Any>(
-  // fields: Fields,
-  ast: SchemaAST.AST,
-  typename: string,
-  version: string,
-): EchoTypeSchema<Self> => {
-  return class EchoObjectSchemaClass extends Schema.make<
-    EchoTypeSchemaProps<Schema.Schema.Type<Self>>,
-    EchoTypeSchemaProps<Schema.Schema.Encoded<Self>>,
-    Schema.Schema.Context<Self>
-  >(ast) {
-    static readonly typename = typename;
-    static readonly version = version;
-
-    static override annotations(
-      annotations: Schema.Annotations.GenericSchema<EchoTypeSchemaProps<Schema.Schema.Type<Self>>>,
-    ): EchoTypeSchema<Self> {
-      const schema = Schema.make<EchoTypeSchemaProps<Schema.Schema.Type<Self>>>(ast).annotations(annotations);
-      return makeEchoObjectSchema<Self>(/* fields, */ schema.ast, typename, version);
-    }
-
-    // static make(
-    //   props: RequiredKeys<Schema.TypeLiteral.Constructor<Fields, []>> extends never
-    //     ? void | Simplify<Schema.TypeLiteral.Constructor<Fields, []>>
-    //     : Simplify<Schema.TypeLiteral.Constructor<Fields, []>>,
-    //   options?: MakeOptions,
-    // ): Simplify<Schema.TypeLiteral.Type<Fields, []>> {
-    //   const propsWithDefaults: any = _lazilyMergeDefaults(fields, { ...(props as any) });
-    //   return _getDisableValidationMakeOption(options)
-    //     ? propsWithDefaults
-    //     : ParseResult.validateSync(this)(propsWithDefaults);
-    // }
-
-    static instanceOf(value: unknown): boolean {
-      return Schema.is(this)(value);
-    }
-  };
-};

package/src/internal/object/expando.ts

@@ -1,21 +0,0 @@
-//
-// Copyright 2024 DXOS.org
-//
-
-import * as Schema from 'effect/Schema';
-
-import { EchoObject } from './entity';
-
-export const EXPANDO_TYPENAME = 'dxos.org/type/Expando';
-
-const ExpandoSchema = Schema.Struct({}, { key: Schema.String, value: Schema.Any }).pipe(
-  EchoObject({ typename: EXPANDO_TYPENAME, version: '0.1.0' }),
-);
-
-/**
- * Expando object is an object with an arbitrary set of properties.
- */
-// TODO(dmaretskyi): Can we consider expando a top-type, i.e. have a ref to expando potentially be a valid ref to any object?
-export interface Expando extends Schema.Schema.Type<typeof ExpandoSchema> {}
-
-export const Expando: Schema.Schema<Expando> = ExpandoSchema;

package/src/internal/object/meta.ts

@@ -1,61 +0,0 @@
-//
-// Copyright 2024 DXOS.org
-//
-
-import * as Schema from 'effect/Schema';
-
-import { ForeignKey } from '@dxos/echo-protocol';
-import { invariant } from '@dxos/invariant';
-import { type Comparator, intersection } from '@dxos/util';
-
-import { type BaseObject } from '../types';
-
-import { MetaId } from './model';
-
-//
-// ObjectMeta
-//
-
-// TODO(dmaretskyi): Rename to ObjectMeta
-export const ObjectMetaSchema = Schema.mutable(
-  Schema.Struct({
-    keys: Schema.mutable(Schema.Array(ForeignKey)),
-
-    /**
-     * A set of tags.
-     * Tags are arbitrary application-defined strings.
-     * ECHO makes no assumptions about the tag structure.
-     */
-    // TODO(dmaretskyi): Has to be optional for compatibility with old data.
-    // Defaulting to an empty array is possible but requires a bit more work.
-    tags: Schema.optional(Schema.mutable(Schema.Array(Schema.String))),
-  }),
-);
-export type ObjectMeta = Schema.Schema.Type<typeof ObjectMetaSchema>;
-
-export const foreignKey = (source: string, id: string): ForeignKey => ({ source, id });
-export const foreignKeyEquals = (a: ForeignKey, b: ForeignKey) => a.source === b.source && a.id === b.id;
-
-/**
- * Get metadata from object.
- * Only callable on the object root.
- * @deprecated Use {@link getMeta}.
- */
-// TODO(dmaretskyi): Remove.
-export const getObjectMeta = (obj: any): ObjectMeta => {
-  return getMeta(obj);
-};
-
-/*
- * Get metadata from object.
- * Only callable on the object root.
- */
-export const getMeta = (obj: BaseObject): ObjectMeta => {
-  const metadata = (obj as any)[MetaId];
-  invariant(metadata, 'ObjectMeta not found.');
-  return metadata;
-};
-
-// TODO(dmaretskyi): Move to echo-schema.
-export const compareForeignKeys: Comparator<BaseObject> = (a: BaseObject, b: BaseObject) =>
-  intersection(getMeta(a).keys, getMeta(b).keys, foreignKeyEquals).length > 0;