@dxos/echo 0.8.1 → 0.8.2-main.10c050d

package/dist/types/src/experimental/queue.d.ts.map

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

package/dist/types/src/{Space.d.ts → experimental/space.d.ts}

@@ -5,4 +5,4 @@
  * @since 0.9.0
  */
 export declare namespace Space { }
-//# sourceMappingURL=Space.d.ts.map
+//# sourceMappingURL=space.d.ts.map

package/dist/types/src/experimental/space.d.ts.map

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

package/dist/types/src/index.d.ts

@@ -1,7 +1,7 @@
-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';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/index.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,GAAG,EAAE,MAAM,YAAY,CAAC;AAEjC,OAAO,EAAE,GAAG,EAAE,CAAC;AAEf,OAAO,KAAK,QAAQ,MAAM,YAAY,CAAC;AACvC,OAAO,KAAK,KAAK,MAAM,SAAS,CAAC;AACjC,OAAO,KAAK,KAAK,MAAM,SAAS,CAAC;AACjC,OAAO,KAAK,IAAI,MAAM,QAAQ,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/index.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,IAAI,MAAM,QAAQ,CAAC;AAC/B,OAAO,KAAK,GAAG,MAAM,OAAO,CAAC;AAC7B,OAAO,KAAK,QAAQ,MAAM,YAAY,CAAC;AACvC,OAAO,KAAK,GAAG,MAAM,OAAO,CAAC;AAE7B,OAAO,EAAE,KAAK,IAAI,EAAE,MAAM,mBAAmB,CAAC;AAC9C,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/types/src/{api.test.d.ts.map → test/api.test.d.ts.map}

@@ -1 +1 @@
-{"version":3,"file":"api.test.d.ts","sourceRoot":"","sources":["../../../src/api.test.ts"],"names":[],"mappings":""}
+{"version":3,"file":"api.test.d.ts","sourceRoot":"","sources":["../../../../src/test/api.test.ts"],"names":[],"mappings":""}

package/dist/types/tsconfig.tsbuildinfo

@@ -1 +1 @@
-{"version":"5.7.3"}
+{"version":"5.8.3"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dxos/echo",
-  "version": "0.8.1",
+  "version": "0.8.2-main.10c050d",
   "description": "ECHO API",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
@@ -21,20 +21,19 @@
     "src"
   ],
   "dependencies": {
-    "@preact/signals-core": "^1.6.0",
-    "effect": "3.13.3",
-    "@dxos/debug": "0.8.1",
-    "@dxos/echo-db": "0.8.1",
-    "@dxos/echo-protocol": "0.8.1",
-    "@dxos/effect": "0.8.1",
-    "@dxos/echo-signals": "0.8.1",
-    "@dxos/echo-schema": "0.8.1",
-    "@dxos/invariant": "0.8.1",
-    "@dxos/keys": "0.8.1",
-    "@dxos/live-object": "0.8.1",
-    "@dxos/node-std": "0.8.1",
-    "@dxos/log": "0.8.1",
-    "@dxos/util": "0.8.1"
+    "@preact/signals-core": "^1.9.0",
+    "effect": "3.14.21",
+    "@dxos/debug": "0.8.2-main.10c050d",
+    "@dxos/echo-protocol": "0.8.2-main.10c050d",
+    "@dxos/echo-signals": "0.8.2-main.10c050d",
+    "@dxos/invariant": "0.8.2-main.10c050d",
+    "@dxos/effect": "0.8.2-main.10c050d",
+    "@dxos/echo-schema": "0.8.2-main.10c050d",
+    "@dxos/live-object": "0.8.2-main.10c050d",
+    "@dxos/log": "0.8.2-main.10c050d",
+    "@dxos/keys": "0.8.2-main.10c050d",
+    "@dxos/util": "0.8.2-main.10c050d",
+    "@dxos/node-std": "0.8.2-main.10c050d"
   },
   "publishConfig": {
     "access": "public"

package/src/Obj.ts

@@ -0,0 +1,86 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { Schema } from 'effect';
+
+import * as EchoSchema from '@dxos/echo-schema';
+import { assertArgument, invariant } from '@dxos/invariant';
+import type { DXN } from '@dxos/keys';
+import * as LiveObject from '@dxos/live-object';
+
+import type * as Type from './Type';
+
+export type Any = EchoSchema.AnyEchoObject;
+
+export const make = LiveObject.live;
+
+// TODO(dmaretskyi): Currently broken
+export const isObject = (obj: unknown): obj is Any => {
+  return LiveObject.isLiveObject(obj);
+};
+
+/**
+ * Check that object or relation is an instance of a schema.
+ * @example
+ * ```ts
+ * const person = Obj.make(Person, { name: 'John' });
+ * const isPerson = Obj.instanceOf(Person);
+ * isPerson(person); // true
+ * ```
+ */
+export const instanceOf: {
+  <S extends Type.Relation.Any | Type.Obj.Any>(schema: S): (value: unknown) => value is S;
+  <S extends Type.Relation.Any | Type.Obj.Any>(schema: S, value: unknown): value is S;
+} = ((...args: any[]) => {
+  if (args.length === 1) {
+    return (obj: unknown) => EchoSchema.isInstanceOf(args[0], obj);
+  }
+
+  return EchoSchema.isInstanceOf(args[0], args[1]);
+}) as any;
+
+export const getSchema = EchoSchema.getSchema;
+
+export const getDXN = (obj: Any): DXN => {
+  assertArgument(!Schema.isSchema(obj), 'Object should not be a schema.');
+  const dxn = EchoSchema.getDXN(obj);
+  invariant(dxn != null, 'Invalid object.');
+  return dxn;
+};
+
+/**
+ * @returns The DXN of the object's type.
+ * @example dxn:example.com/type/Contact:1.0.0
+ */
+export const getSchemaDXN = (obj: Any): DXN => {
+  const type = EchoSchema.getType(obj);
+  invariant(type != null, 'Invalid object.');
+  return type;
+};
+
+/**
+ * @returns The typename of the object's type.
+ * @example `example.com/type/Contact`
+ */
+export const getTypename = (obj: Any): string | undefined => {
+  const schema = getSchema(obj);
+  if (schema == null) {
+    // Try to extract typename from DXN.
+    return getSchemaDXN(obj)?.asTypeDXN()?.type;
+  }
+
+  return EchoSchema.getTypename(schema);
+};
+
+export const getMeta = (obj: Any): EchoSchema.ObjectMeta => {
+  const meta = EchoSchema.getMeta(obj);
+  invariant(meta != null, 'Invalid object.');
+  return meta;
+};
+
+export const isDeleted = (obj: Any): boolean => {
+  const deleted = EchoSchema.isDeleted(obj);
+  invariant(typeof deleted === 'boolean', 'Invalid object.');
+  return deleted;
+};

package/src/Ref.ts

@@ -0,0 +1,21 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as EchoSchema from '@dxos/echo-schema';
+
+import type * as Obj from './Obj';
+
+export type Any = EchoSchema.Ref<Obj.Any>;
+
+export const make = EchoSchema.Ref.make;
+
+export const isRef: (value: unknown) => value is Any = EchoSchema.Ref.isRef;
+
+// TODO(dmaretskyi): Consider just allowing `make` to accept DXN.
+export const fromDXN = EchoSchema.Ref.fromDXN;
+
+/**
+ * Extract reference target.
+ */
+export type Target<R extends Any> = R extends EchoSchema.Ref<infer T> ? T : never;

package/src/Relation.ts

@@ -0,0 +1,45 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as EchoSchema from '@dxos/echo-schema';
+import { invariant } from '@dxos/invariant';
+import * as LiveObject from '@dxos/live-object';
+
+export type Any = EchoSchema.AnyEchoObject & EchoSchema.RelationSourceTargetRefs;
+
+export const make = LiveObject.live;
+
+export const isRelation = (value: unknown): value is Any => {
+  if (typeof value !== 'object' || value === null) {
+    return false;
+  }
+  if (EchoSchema.ATTR_RELATION_SOURCE in value || EchoSchema.ATTR_RELATION_TARGET in value) {
+    return true;
+  }
+
+  const kind = (value as any)[EchoSchema.EntityKindPropertyId];
+  return kind === EchoSchema.EntityKind.Relation;
+};
+
+/**
+ * @returns Relation source.
+ * @throws If the object is not a relation.
+ */
+export const getSource = <T extends Any>(relation: T): EchoSchema.RelationSource<T> => {
+  invariant(isRelation(relation));
+  const obj = relation[EchoSchema.RelationSourceId];
+  invariant(obj !== undefined, `Invalid source: ${relation.id}`);
+  return obj;
+};
+
+/**
+ * @returns Relation target.
+ * @throws If the object is not a relation.
+ */
+export const getTarget = <T extends Any>(relation: T): EchoSchema.RelationTarget<T> => {
+  invariant(isRelation(relation));
+  const obj = relation[EchoSchema.RelationTargetId];
+  invariant(obj !== undefined, `Invalid target: ${relation.id}`);
+  return obj;
+};

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"}