@dxos/echo 0.8.2-staging.7ac8446 → 0.8.3-main.672df60

package/src/Type.ts

@@ -4,96 +4,124 @@
 
 import { type Schema } from 'effect';
 
-import {
-  type BaseSchema,
-  type EchoSchema,
-  type Expando as Expando$,
-  type ImmutableSchema,
-  type JsonSchemaType,
-  type TypeMeta,
-  EchoObject,
-  EntityKind,
-  ObjectId,
-  Ref as Ref$,
-  getTypeAnnotation,
-  getSchema,
-  getSchemaDXN,
-  getSchemaTypename,
-  getSchemaVersion,
-  isInstanceOf,
-} from '@dxos/echo-schema';
-import { create as create$, makeRef } from '@dxos/live-object';
+import type { EncodedReference } from '@dxos/echo-protocol';
+import * as EchoSchema from '@dxos/echo-schema';
+import { invariant } from '@dxos/invariant';
+import type * as Keys from '@dxos/keys';
 
-// NOTES:
-// - New Echo package and namespaces allow for incremental migration; vastly simplifies imports.
-// - Split into separate ECHO namespaces: Database, Space, Type, Query, Queue.
-//  - Example; import { Database, Type, Query, Queue } from '@dxos/echo';
-// - Use `declare namespace` for types (no code is generated). See Effect pattern, where Schema is a namespace, interface, and function.
-// - Test with @dxos/schema/testing types.
-// - Define user (Composer) types in namespace (e.g., of plugin) and drop Type suffix; remove all deprecated Braneframe types.
+/**
+ * ECHO schema.
+ */
+export type Schema = EchoSchema.EchoSchema;
 
-export type { TypeMeta as Meta, JsonSchemaType as JsonSchema };
-export {
-  EntityKind as Kind,
-  ObjectId,
-  getTypeAnnotation as getMeta,
-  getSchema,
-  getSchemaDXN as getDXN,
-  getSchemaTypename as getTypename,
-  getSchemaVersion as getVersion,
-  isInstanceOf as instanceOf,
-};
+/**
+ * EchoObject schema.
+ */
+export const Obj = EchoSchema.EchoObject;
+
+/**
+ * EchoRelation schema.
+ */
+export const Relation = EchoSchema.EchoRelation;
 
 /**
- * Type API.
- *
- * @category api namespace
- * @since 0.9.0
+ * Ref schema.
  */
-export declare namespace Type {
+export const Ref: <S extends Obj.Any>(schema: S) => EchoSchema.Ref$<Schema.Schema.Type<S>> = EchoSchema.Ref;
+
+export namespace Obj {
+  /**
+   * Type that represents an arbitrary schema type of an object.
+   * NOTE: This is not an instance type.
+   */
+  // TODO(dmaretskyi): If schema was covariant, we could specify props in here, like `id: ObjectId`.
+  export type Any = Schema.Schema.AnyNoContext;
+}
+
+export namespace Relation {
+  /**
+   * Type that represents an arbitrary schema type of a relation.
+   * NOTE: This is not an instance type.
+   */
+  // TODO(dmaretskyi): If schema was covariant, we could specify props in here, like `id: ObjectId`.
+  export type Any = Schema.Schema.AnyNoContext;
+
   /**
-   * A schema that can be extended with arbitrary properties.
+   * Get relation target type.
    */
-  export type Expando = Expando$;
+  export type Target<A> = A extends EchoSchema.RelationSourceTargetRefs<infer T, infer _S> ? T : never;
 
-  export type Abstract<T = any> = BaseSchema<T>;
-  export type ImmutableType<T> = ImmutableSchema<T>;
-  export type MutableType<T> = EchoSchema<T>;
+  /**
+   * Get relation source type.
+   */
+  export type Source<A> = A extends EchoSchema.RelationSourceTargetRefs<infer _T, infer S> ? S : never;
 }
 
-//
-// Constructors
-//
+export namespace Ref {
+  /**
+   * Type that represents an arbitrary schema type of a reference.
+   * NOTE: This is not an instance type.
+   */
+  export type Any = Schema.Schema<EchoSchema.Ref<any>, EncodedReference>;
+}
 
-export const ref = makeRef;
-export const create = create$;
+/**
+ * Gets the full DXN of the schema.
+ * Will include the version if it's a `type` DXN.
+ * @example "dxn:example.com/type/Person:0.1.0"
+ * @example "dxn:echo:SSSSSSSSSS:XXXXXXXXXXXXX"
+ */
+export const getDXN = (schema: Obj.Any | Relation.Any): Keys.DXN | undefined => {
+  return EchoSchema.getSchemaDXN(schema);
+};
 
-//
-// Combinators
-//
+/**
+ * @param schema - Schema to get the typename from.
+ * @returns The typename of the schema. Example: `example.com/type/Person`.
+ */
+export const getTypename = (schema: Obj.Any | Relation.Any): string => {
+  const typename = EchoSchema.getSchemaTypename(schema);
+  invariant(typeof typename === 'string' && !typename.startsWith('dxn:'), 'Invalid typename');
+  return typename;
+};
 
 /**
- * Defines an ECHO type.
- *
- * @example
- * ```ts
- * const Org = S.Struct({
- *   name: S.String,
- * }).pipe(Type.def({ typename: 'example.com/type/Org', version: '1.0.0' }));
- * ```
+ * Gets the version of the schema.
+ * @example 0.1.0
  */
-export const def = (meta: TypeMeta) => EchoObject(meta);
+export const getVersion = (schema: Obj.Any | Relation.Any): string => {
+  const version = EchoSchema.getSchemaVersion(schema);
+  invariant(typeof version === 'string' && version.match(/^\d+\.\d+\.\d+$/), 'Invalid version');
+  return version;
+};
 
 /**
- * Defines a reference to an ECHO object.
- *
- * @example
- * ```ts
- * import { Type } from '@dxos/echo';
- * const Contact = S.Struct({
- *   name: S.String,
- *   employer: Type.Ref(Org),
- * }).pipe(Type.def({ typename: 'example.com/type/Contact', version: '1.0.0' }));
- * ```
+ * ECHO type metadata.
  */
-export const Ref = <S extends Schema.Schema.AnyNoContext>(self: S) => Ref$<Schema.Schema.Type<S>>(self);
+export type Meta = EchoSchema.TypeAnnotation;
+
+/**
+ * Gets the meta data of the schema.
+ */
+export const getMeta = (schema: Obj.Any | Relation.Any): Meta | undefined => {
+  return EchoSchema.getTypeAnnotation(schema);
+};
+
+export { EntityKind as Kind } from '@dxos/echo-schema';
+
+/**
+ * @returns True if the schema is mutable.
+ */
+export const isMutable = (schema: Obj.Any | Relation.Any): boolean => {
+  return EchoSchema.isMutable(schema);
+};
+
+export { SpaceId, ObjectId, DXN } from '@dxos/keys';
+
+export {
+  //
+  Expando,
+  JsonSchemaType as JsonSchema,
+  toJsonSchema,
+  Format,
+} from '@dxos/echo-schema';

package/src/{Database.ts → experimental/database.ts}

@@ -8,4 +8,4 @@
  * @category api namespace
  * @since 0.9.0
  */
-export declare namespace Database {}
+export namespace Database {}

package/src/experimental/index.ts

@@ -0,0 +1,7 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+// export type { Database } from './database';
+// export type { Queue } from './queue';
+// export type { Space } from './space';

package/src/{Queue.ts → experimental/queue.ts}

@@ -8,4 +8,4 @@
  * @category api namespace
  * @since 0.9.0
  */
-export declare namespace Queue {}
+export namespace Queue {}

package/src/index.ts

@@ -2,11 +2,10 @@
 // Copyright 2025 DXOS.org
 //
 
-import { DXN } from '@dxos/keys';
-
-export { DXN };
-
-export * as Database from './Database';
-export * as Queue from './Queue';
-export * as Space from './Space';
 export * as Type from './Type';
+export * as Obj from './Obj';
+export * as Relation from './Relation';
+export * as Ref from './Ref';
+
+export { type Live } from '@dxos/live-object';
+export { Filter, Query } from '@dxos/echo-schema';

package/src/test/api.test.ts

@@ -0,0 +1,128 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { Schema } from 'effect';
+import { describe, test } from 'vitest';
+
+import { raise } from '@dxos/debug';
+import { FormatEnum, FormatAnnotation } from '@dxos/echo-schema';
+
+import { Obj, Ref, Type, type Live } from '../index';
+
+namespace Testing {
+  export const Organization = Schema.Struct({
+    id: Type.ObjectId,
+    name: Schema.String,
+  }).pipe(
+    Type.Obj({
+      typename: 'example.com/type/Organization',
+      version: '0.1.0',
+    }),
+  );
+
+  export interface Organization extends Schema.Schema.Type<typeof Organization> {}
+
+  export const Person = Schema.Struct({
+    name: Schema.String,
+    dob: Schema.optional(Schema.String),
+    email: Schema.optional(Schema.String.pipe(FormatAnnotation.set(FormatEnum.Email))),
+    organization: Schema.optional(Type.Ref(Organization)),
+  }).pipe(
+    Type.Obj({
+      typename: 'example.com/type/Person',
+      version: '0.1.0',
+    }),
+  );
+
+  export interface Person extends Schema.Schema.Type<typeof Person> {}
+
+  // export const WorksFor = S.Struct({
+  //   id: Type.ObjectId,
+  //   since: S.String,
+  //   jobTitle: S.String,
+  //   ...Range({ from, to }),
+  //   ...Provenance({ source: 'duckduckgo.com', confidence: 0.9 }), // keys
+  //   ...Relation.make({ source: Contact, target: Organization }),
+  // }).pipe(
+  //   Type.Relation({
+  //     typename: 'example.com/relation/WorksFor',
+  //     version: '0.1.0',
+  //   }),
+  // );
+
+  // {
+  //   const contact = db.add(create(Contact, { name: 'Test' }));
+  //   const organization = db.add(create(Organization, { name: 'DXOS' }));
+  //   db.add(create(WorksFor, { source: contact, target: organization }));
+  // }
+
+  export const WorksFor = Schema.Struct({
+    // id: Type.ObjectId,
+    role: Schema.String,
+  }).pipe(
+    // Type.Relation
+    Type.Obj({
+      typename: 'example.com/type/WorksFor',
+      version: '0.1.0',
+      // source: Person,
+      // target: Organization,
+    }),
+  );
+
+  export interface WorksFor extends Schema.Schema.Type<typeof WorksFor> {}
+
+  // TODO(burdon): Fix (Type.Obj currently removes TypeLiteral that implements the `make` function).
+  //  Property 'make' does not exist on type 'EchoObjectSchema<Struct<{ timestamp: PropertySignature<":", string, never, ":", string, true, never>; }>>'.ts(2339)
+  export const MessageStruct = Schema.Struct({
+    // TODO(burdon): Support S.Date; Custom Timestamp (with defaults).
+    // TODO(burdon): Support defaults (update create and create).
+    timestamp: Schema.String.pipe(
+      Schema.propertySignature,
+      Schema.withConstructorDefault(() => new Date().toISOString()),
+    ),
+  });
+
+  export const Message = MessageStruct.pipe(
+    Type.Obj({
+      typename: 'example.com/type/Message',
+      version: '0.1.0',
+    }),
+  );
+
+  export interface Message extends Schema.Schema.Type<typeof Message> {}
+}
+
+describe('Experimental API review', () => {
+  test('type checks', ({ expect }) => {
+    const contact = Obj.make(Testing.Person, { name: 'Test' });
+    const type: Schema.Schema<Testing.Person> = Obj.getSchema(contact) ?? raise(new Error('No schema found'));
+
+    expect(Type.getDXN(type)?.typename).to.eq(Testing.Person.typename);
+    expect(Type.getTypename(type)).to.eq('example.com/type/Person');
+    expect(Type.getVersion(type)).to.eq('0.1.0');
+    expect(Type.getMeta(type)).to.deep.eq({
+      kind: Type.Kind.Object,
+      typename: 'example.com/type/Person',
+      version: '0.1.0',
+    });
+  });
+
+  test('instance checks', ({ expect }) => {
+    const organization: Live<Testing.Organization> = Obj.make(Testing.Organization, { name: 'DXOS' });
+    const contact: Live<Testing.Person> = Obj.make(Testing.Person, {
+      name: 'Test',
+      organization: Ref.make(organization),
+    });
+
+    expect(Schema.is(Testing.Person)(contact)).to.be.true;
+    expect(Testing.Person.instanceOf(contact)).to.be.true;
+    expect(Obj.instanceOf(Testing.Person)(contact)).to.be.true;
+    expect(Obj.instanceOf(Testing.Organization)(organization)).to.be.true;
+  });
+
+  test('default props', ({ expect }) => {
+    const message = Obj.make(Testing.Message, Testing.MessageStruct.make({}));
+    expect(message.timestamp).to.exist;
+  });
+});

package/dist/types/src/Database.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"Database.d.ts","sourceRoot":"","sources":["../../../src/Database.ts"],"names":[],"mappings":"AAIA;;;;;GAKG;AACH,MAAM,CAAC,OAAO,WAAW,QAAQ,CAAC,GAAE"}

package/dist/types/src/Queue.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"Queue.d.ts","sourceRoot":"","sources":["../../../src/Queue.ts"],"names":[],"mappings":"AAIA;;;;;GAKG;AACH,MAAM,CAAC,OAAO,WAAW,KAAK,CAAC,GAAE"}

package/dist/types/src/Space.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"Space.d.ts","sourceRoot":"","sources":["../../../src/Space.ts"],"names":[],"mappings":"AAIA;;;;;GAKG;AACH,MAAM,CAAC,OAAO,WAAW,KAAK,CAAC,GAAE"}

package/src/api.test.ts

@@ -1,94 +0,0 @@
-//
-// Copyright 2025 DXOS.org
-//
-
-import { Schema as S } from 'effect';
-import { describe, test } from 'vitest';
-
-import { raise } from '@dxos/debug';
-import { FormatEnum, FormatAnnotation } from '@dxos/echo-schema';
-
-// Deliberately testing top-level import as if external consumer for @dxos/echo.
-import { Type } from '.';
-
-namespace Testing {
-  export const Org = S.Struct({
-    id: Type.ObjectId,
-    name: S.String,
-  }).pipe(
-    Type.def({
-      typename: 'example.com/type/Org',
-      version: '0.1.0',
-    }),
-  );
-
-  export interface Org extends S.Schema.Type<typeof Org> {}
-
-  export const Contact = S.Struct({
-    name: S.String,
-    dob: S.optional(S.String),
-    email: S.optional(S.String.pipe(FormatAnnotation.set(FormatEnum.Email))),
-    org: S.optional(Type.Ref(Org)),
-  }).pipe(
-    Type.def({
-      typename: 'example.com/type/Contact',
-      version: '0.1.0',
-    }),
-  );
-
-  export interface Contact extends S.Schema.Type<typeof Contact> {}
-
-  export const Message = S.Struct({
-    // TODO(burdon): Support S.Date; Custom Timestamp (with defaults).
-    // TODO(burdon): Support defaults (update create and createStatic).
-    timestamp: S.String.pipe(
-      S.propertySignature,
-      S.withConstructorDefault(() => new Date().toISOString()),
-    ),
-  });
-
-  // TODO(burdon): Fix (Type.def currently removes TypeLiteral that implements the `make` function)..
-  // }).pipe(
-  //   Type.def({
-  //     typename: 'example.com/type/Message',
-  //     version: '0.1.0',
-  //   }),
-  // );
-
-  export interface Message extends S.Schema.Type<typeof Message> {}
-}
-
-describe('Experimental API review', () => {
-  test('type checks', ({ expect }) => {
-    const contact = Type.create(Testing.Contact, { name: 'Test' });
-    const type: S.Schema<Testing.Contact> = Type.getSchema(contact) ?? raise(new Error('No schema found'));
-
-    expect(Type.getDXN(type)?.typename).to.eq(Testing.Contact.typename);
-    expect(Type.getTypename(type)).to.eq('example.com/type/Contact');
-    expect(Type.getVersion(type)).to.eq('0.1.0');
-    expect(Type.getMeta(type)).to.deep.eq({
-      kind: Type.Kind.Object,
-      typename: 'example.com/type/Contact',
-      version: '0.1.0',
-    });
-  });
-
-  test('instance checks', ({ expect }) => {
-    // TODO(burdon): Implement.
-    // const org = Org.create({ name: 'DXOS' });
-    const org = Type.create(Testing.Org, { name: 'DXOS' });
-    const contact = Type.create(Testing.Contact, { name: 'Test', org: Type.ref(org) });
-
-    expect(S.is(Testing.Contact)(contact)).to.be.true;
-    expect(Testing.Contact.instanceOf(contact)).to.be.true;
-    expect(Type.instanceOf(Testing.Contact, contact)).to.be.true;
-    expect(Type.instanceOf(Testing.Org, contact.org?.target)).to.be.true;
-  });
-
-  test('default props', ({ expect }) => {
-    // TODO(burdon): Doesn't work after pipe(Type.def).
-    // Property 'make' does not exist on type 'EchoObjectSchema<Struct<{ timestamp: PropertySignature<":", string, never, ":", string, true, never>; }>>'.ts(2339)
-    const message = Type.create(Testing.Message, Testing.Message.make({}));
-    expect(message.timestamp).to.exist;
-  });
-});