@dxos/echo-protocol 0.8.4-main.d05539e30a → 0.8.4-main.d9fc60f731

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dxos/echo-protocol",
-  "version": "0.8.4-main.d05539e30a",
+  "version": "0.8.4-main.d9fc60f731",
   "description": "Core ECHO APIs.",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
@@ -25,12 +25,12 @@
     "src"
   ],
   "dependencies": {
-    "effect": "3.20.0",
-    "@dxos/crypto": "0.8.4-main.d05539e30a",
-    "@dxos/keys": "0.8.4-main.d05539e30a",
-    "@dxos/util": "0.8.4-main.d05539e30a",
-    "@dxos/protocols": "0.8.4-main.d05539e30a",
-    "@dxos/invariant": "0.8.4-main.d05539e30a"
+    "effect": "3.21.2",
+    "@dxos/crypto": "0.8.4-main.d9fc60f731",
+    "@dxos/invariant": "0.8.4-main.d9fc60f731",
+    "@dxos/protocols": "0.8.4-main.d9fc60f731",
+    "@dxos/keys": "0.8.4-main.d9fc60f731",
+    "@dxos/util": "0.8.4-main.d9fc60f731"
   },
   "publishConfig": {
     "access": "public"

package/src/document-structure.ts

@@ -3,7 +3,7 @@
 //
 
 import { invariant } from '@dxos/invariant';
-import type { DXN, ObjectId } from '@dxos/keys';
+import type { EntityId, URI } from '@dxos/keys';
 import { visitValues } from '@dxos/util';
 
 import { type RawString } from './automerge';
@@ -19,8 +19,8 @@ export type SpaceState = {
 /**
  * Array indexes get converted to strings.
  */
-export type ObjectProp = string;
-export type ObjectPropPath = ObjectProp[];
+export type EntityProp = string;
+export type EntityPropPath = EntityProp[];
 
 /**
  * Link to all documents that hold objects in the space.
@@ -35,13 +35,13 @@ export interface DatabaseDirectory {
    * Objects inlined in the current document.
    */
   objects?: {
-    [id: string]: ObjectStructure;
+    [id: string]: EntityStructure;
   };
   /**
    * Object id points to an automerge doc url where the object is embedded.
    */
   links?: {
-    [echoId: string]: string | RawString;
+    [echoUri: string]: string | RawString;
   };
 
   /**
@@ -67,11 +67,11 @@ export const DatabaseDirectory = Object.freeze({
     return rawKey;
   },
 
-  getInlineObject: (doc: DatabaseDirectory, id: ObjectId): ObjectStructure | undefined => {
+  getInlineObject: (doc: DatabaseDirectory, id: EntityId): EntityStructure | undefined => {
     return doc.objects?.[id];
   },
 
-  getLink: (doc: DatabaseDirectory, id: ObjectId): string | undefined => {
+  getLink: (doc: DatabaseDirectory, id: EntityId): string | undefined => {
     return doc.links?.[id]?.toString();
   },
 
@@ -81,7 +81,7 @@ export const DatabaseDirectory = Object.freeze({
     links,
   }: {
     spaceKey: string;
-    objects?: Record<string, ObjectStructure>;
+    objects?: Record<string, EntityStructure>;
     links?: Record<string, RawString>;
   }): DatabaseDirectory => ({
     access: {
@@ -95,11 +95,11 @@ export const DatabaseDirectory = Object.freeze({
 /**
  * Representation of an ECHO object in an AM document.
  */
-export type ObjectStructure = {
+export type EntityStructure = {
   // TODO(dmaretskyi): Missing in some cases.
-  system?: ObjectSystem;
+  system?: EntitySystem;
 
-  meta: ObjectMeta;
+  meta: EntityMeta;
   /**
    * User-defined data.
    * Adheres to schema in `system.type`
@@ -107,46 +107,46 @@ export type ObjectStructure = {
   data: Record<string, any>;
 };
 
-// Helper methods to interact with the {@link ObjectStructure}.
-export const ObjectStructure = Object.freeze({
+// Helper methods to interact with the {@link EntityStructure}.
+export const EntityStructure = Object.freeze({
   /**
    * @throws On invalid object structure.
    */
-  getTypeReference: (object: ObjectStructure): EncodedReference | undefined => {
+  getTypeReference: (object: EntityStructure): EncodedReference | undefined => {
     return object.system?.type;
   },
 
   /**
    * @throws On invalid object structure.
    */
-  getEntityKind: (object: ObjectStructure): 'object' | 'relation' => {
+  getEntityKind: (object: EntityStructure): 'object' | 'relation' | 'type' => {
     const kind = object.system?.kind ?? 'object';
-    invariant(kind === 'object' || kind === 'relation', 'Invalid kind');
+    invariant(kind === 'object' || kind === 'relation' || kind === 'type', 'Invalid kind');
     return kind;
   },
 
-  isDeleted: (object: ObjectStructure): boolean => {
+  isDeleted: (object: EntityStructure): boolean => {
     return object.system?.deleted ?? false;
   },
 
-  getRelationSource: (object: ObjectStructure): EncodedReference | undefined => {
+  getRelationSource: (object: EntityStructure): EncodedReference | undefined => {
     return object.system?.source;
   },
 
-  getRelationTarget: (object: ObjectStructure): EncodedReference | undefined => {
+  getRelationTarget: (object: EntityStructure): EncodedReference | undefined => {
     return object.system?.target;
   },
 
-  getParent: (object: ObjectStructure): EncodedReference | undefined => {
+  getParent: (object: EntityStructure): EncodedReference | undefined => {
     return object.system?.parent;
   },
 
   /**
    * @returns All references in the data section of the object.
    */
-  getAllOutgoingReferences: (object: ObjectStructure): { path: ObjectPropPath; reference: EncodedReference }[] => {
-    const references: { path: ObjectPropPath; reference: EncodedReference }[] = [];
-    const visit = (path: ObjectPropPath, value: unknown) => {
+  getAllOutgoingReferences: (object: EntityStructure): { path: EntityPropPath; reference: EncodedReference }[] => {
+    const references: { path: EntityPropPath; reference: EncodedReference }[] = [];
+    const visit = (path: EntityPropPath, value: unknown) => {
       if (isEncodedReference(value)) {
         references.push({ path, reference: value });
       } else {
@@ -157,7 +157,7 @@ export const ObjectStructure = Object.freeze({
     return references;
   },
 
-  getTags: (object: ObjectStructure): string[] => {
+  getTags: (object: EntityStructure): (EncodedReference | string)[] => {
     return object.meta.tags ?? [];
   },
 
@@ -166,11 +166,11 @@ export const ObjectStructure = Object.freeze({
     data,
     keys,
   }: {
-    type: DXN.String;
+    type: URI.URI;
     deleted?: boolean;
     keys?: ForeignKey[];
     data?: unknown;
-  }): ObjectStructure => {
+  }): EntityStructure => {
     return {
       system: {
         kind: 'object',
@@ -191,13 +191,13 @@ export const ObjectStructure = Object.freeze({
     keys,
     data,
   }: {
-    type: DXN.String;
+    type: URI.URI;
     source: EncodedReference;
     target: EncodedReference;
     deleted?: boolean;
     keys?: ForeignKey[];
     data?: unknown;
-  }): ObjectStructure => {
+  }): EntityStructure => {
     return {
       system: {
         kind: 'relation',
@@ -212,12 +212,25 @@ export const ObjectStructure = Object.freeze({
       data: data ?? {},
     };
   },
+
+  makeType: ({ type, keys, data }: { type: URI.URI; keys?: ForeignKey[]; data?: unknown }): EntityStructure => {
+    return {
+      system: {
+        kind: 'type',
+        type: { '/': type },
+      },
+      meta: {
+        keys: keys ?? [],
+      },
+      data: data ?? {},
+    };
+  },
 });
 
 /**
  * Echo object metadata.
  */
-export type ObjectMeta = {
+export type EntityMeta = {
   /**
    * Foreign keys.
    */
@@ -225,11 +238,12 @@ export type ObjectMeta = {
 
   /**
    * Tags.
-   * An array of DXNs of Tag objects within the space.
+   * Encoded references to Tag objects within the space.
    *
-   * NOTE: Optional for backwards compatibilty.
+   * NOTE: Optional for backwards compatibility; legacy data may store bare DXN strings, which are
+   * upgraded to encoded references on read (see `object-core.ts`).
    */
-  tags?: string[];
+  tags?: (EncodedReference | string)[];
 
   /**
    * Fully-qualified registry key for the object (FQN format, e.g. `org.example.type.foo`).
@@ -242,20 +256,38 @@ export type ObjectMeta = {
    * Must be a valid semver string (e.g. `1.2.3`).
    */
   version?: string;
+
+  /**
+   * Dictionary of annotations to this entity.
+   *
+   * NOTE: Optional for backwards compatibility. Values are arbitrary decoded automerge primitives;
+   * typed as `any` so `EntityStructure` stays assignable to `DecodedAutomergePrimaryValue`.
+   */
+  annotations?: { readonly [key: string]: any };
 };
 
 /**
  * Automerge object system properties.
  * (Is automerge specific.)
  */
-export type ObjectSystem = {
+export type EntitySystem = {
   /**
-   * Entity kind.
+   * Entity kind. `'type'` covers persisted ECHO type definitions (instances of
+   * the `Type.Type` meta-schema); `'object'` / `'relation'` cover regular ECHO
+   * instances.
    */
-  kind?: 'object' | 'relation';
+  kind?: 'object' | 'relation' | 'type';
 
   /**
-   * Object reference ('protobuf' protocol) type.
+   * Object reference ('protobuf' protocol) type — DXN of the schema this
+   * entity instantiates.
+   *
+   * - For `kind === 'object'` / `'relation'` instances, this is the URI of the
+   *   user-defined schema the entity was created from (e.g. `dxn:type:org.example.Person:1.0.0`).
+   * - For `kind === 'type'` entities (persisted Type.Type meta-instances) this
+   *   is always the URI of the `TypeSchema` meta-schema itself
+   *   (`dxn:org.dxos.type.schema:0.1.0`). The kind that the meta-instance
+   *   _describes_ (object/relation/type) lives in `data.jsonSchema.entityKind`.
    */
   type?: EncodedReference;
 
@@ -288,6 +320,6 @@ export const PROPERTY_ID = 'id';
 
 /**
  * Data namespace.
- * The key on {@link ObjectStructure} that contains the user-defined data.
+ * The key on {@link EntityStructure} that contains the user-defined data.
  */
 export const DATA_NAMESPACE = 'data';

package/src/query/ast.ts

@@ -5,13 +5,14 @@
 import * as Match from 'effect/Match';
 import * as Schema from 'effect/Schema';
 
-import { DXN, ObjectId } from '@dxos/keys';
+import { EID, EntityId, URI } from '@dxos/keys';
 
 import { ForeignKey } from '../foreign-key';
 
-const TypenameSpecifier = Schema.Union(DXN.Schema, Schema.Null).annotations({
-  description: 'DXN or null; null matches any type',
-});
+// Type identifier URI — either a DXN (typename) or an EID (stored-schema-as-object).
+// Matches the URI written into an object's `system.type` (see `getSchemaURI`). Null
+// matches any type.
+const TypenameSpecifier = Schema.Union(URI.Schema, Schema.Null);
 
 // NOTE: This pattern with 3 definitions per schema is need to make the types opaque, and circular references in AST to not cause compiler errors.
 
@@ -26,7 +27,7 @@ const FilterObject_ = Schema.Struct({
 
   typename: TypenameSpecifier,
 
-  id: Schema.optional(Schema.Array(ObjectId)),
+  id: Schema.optional(Schema.Array(EntityId)),
 
   /**
    * Filter by property.
@@ -184,7 +185,7 @@ export const FilterOr: Schema.Schema<FilterOr> = FilterOr_;
 const FilterChildOf_ = Schema.Struct({
   type: Schema.Literal('child-of'),
   /** Parent DXNs to match children of. */
-  parents: Schema.Array(DXN.Schema),
+  parents: Schema.Array(EID.Schema),
   /** Whether to match transitively (grandchildren, etc.). Defaults to true. */
   transitive: Schema.Boolean,
 });
@@ -402,7 +403,7 @@ export const QueryFromClause_ = Schema.Struct({
   query: Schema.suspend(() => Query),
   from: Schema.Union(
     Schema.TaggedStruct('scope', {
-      scope: Schema.suspend(() => Scope),
+      scopes: Schema.Array(Schema.suspend(() => Scope)),
     }),
     Schema.TaggedStruct('query', {
       query: Schema.suspend(() => Query),
@@ -446,29 +447,45 @@ export const QueryOptions = Schema.Struct({
 export interface QueryOptions extends Schema.Schema.Type<typeof QueryOptions> {}
 
 /**
- * Specifies the scope of the data to query from.
+ * Selects from a space (automerge documents).
+ * When `spaceId` is omitted, targets the owning space — i.e. the space of whichever
+ * database executes the query. This lets callers reference "this space" without
+ * having to look up its id.
+ * When `includeAllFeeds` is true, also selects from all feeds belonging to that space.
  */
-export const Scope = Schema.Struct({
-  /**
-   * The nested select statemets will select from the given spaces.
-   *
-   * NOTE: Spaces and feeds are unioned together if both are specified.
-   */
-  spaceIds: Schema.optional(Schema.Array(Schema.String)),
+export const SpaceScope = Schema.TaggedStruct('space', {
+  spaceId: Schema.optional(Schema.String),
+  includeAllFeeds: Schema.optional(Schema.Boolean),
+});
+export interface SpaceScope extends Schema.Schema.Type<typeof SpaceScope> {}
 
-  /**
-   * If true, the nested select statements will select from all feeds in the spaces specified by `spaceIds`.
-   */
-  allFeedsFromSpaces: Schema.optional(Schema.Boolean),
+/**
+ * Selects from a specific feed (by its underlying queue DXN).
+ */
+export const FeedScope = Schema.TaggedStruct('feed', {
+  feedUri: Schema.String,
+});
+export interface FeedScope extends Schema.Schema.Type<typeof FeedScope> {}
 
-  /**
-   * The nested select statemets will select from the given feeds (by underlying queue DXN).
-   *
-   * NOTE: Spaces and feeds are unioned together if both are specified.
-   */
-  feeds: Schema.optional(Schema.Array(DXN.Schema)),
+/**
+ * Selects from a code-shipped object registry.
+ *
+ * - `'local'`  — the in-process registry attached to the hypergraph.
+ * - `'remote'` — a future remote registry service (not yet implemented).
+ *
+ * To include both, add two separate `RegistryScope` entries to the `scopes` array.
+ */
+export const RegistryScope = Schema.TaggedStruct('registry', {
+  location: Schema.Literal('local', 'remote'),
 });
-export interface Scope extends Schema.Schema.Type<typeof Scope> {}
+export interface RegistryScope extends Schema.Schema.Type<typeof RegistryScope> {}
+
+/**
+ * Specifies the scope of the data to query from.
+ * A `from` clause may carry multiple scopes; results are unioned across them.
+ */
+export const Scope = Schema.Union(SpaceScope, FeedScope, RegistryScope);
+export type Scope = Schema.Schema.Type<typeof Scope>;
 
 export const visit = (query: Query, visitor: (node: Query) => void) => {
   visitor(query);

package/src/reference.ts

@@ -3,126 +3,7 @@
 //
 
 import { assertArgument } from '@dxos/invariant';
-import { DXN, LOCAL_SPACE_TAG, type PublicKey } from '@dxos/keys';
-import { type ObjectId } from '@dxos/protocols';
-import { type Reference as ReferenceProto } from '@dxos/protocols/proto/dxos/echo/model/document';
-
-/**
- * Runtime representation of an reference in ECHO.
- * Implemented as a DXN, but we might extend it to other URIs in the future.
- * @deprecated Use `EncodedReference` instead.
- */
-export class Reference {
-  /**
-   * Protocol references to runtime registered types.
-   * @deprecated
-   */
-  static TYPE_PROTOCOL = 'protobuf';
-
-  static fromDXN(dxn: DXN): Reference {
-    switch (dxn.kind) {
-      case DXN.kind.TYPE:
-        return new Reference(dxn.parts[0], Reference.TYPE_PROTOCOL, 'dxos.org', dxn);
-      case DXN.kind.ECHO:
-        if (dxn.parts[0] === LOCAL_SPACE_TAG) {
-          return new Reference(dxn.parts[1], undefined, undefined, dxn);
-        } else {
-          return new Reference(dxn.parts[1], undefined, dxn.parts[0], dxn);
-        }
-      default:
-        return new Reference(dxn.parts[0], undefined, dxn.parts[0], dxn);
-    }
-  }
-
-  static fromValue(value: ReferenceProto): Reference {
-    return new Reference(value.objectId, value.protocol, value.host);
-  }
-
-  /**
-   * Reference an object in the local space.
-   */
-  static localObjectReference(objectId: ObjectId): Reference {
-    return new Reference(objectId);
-  }
-
-  /**
-   * @deprecated
-   */
-  // TODO(dmaretskyi): Remove.
-  static fromLegacyTypename(type: string): Reference {
-    return new Reference(type, Reference.TYPE_PROTOCOL, 'dxos.org');
-  }
-
-  /**
-   * @deprecated
-   */
-  // TODO(dmaretskyi): Remove
-  static fromObjectIdAndSpaceKey(objectId: ObjectId, spaceKey: PublicKey): Reference {
-    // TODO(dmaretskyi): FIX ME! This should be a space ID not a space key.
-    return new Reference(objectId, undefined, spaceKey.toHex());
-  }
-
-  // prettier-ignore
-  private constructor(
-    // TODO(dmaretskyi): Remove and just leave DXN.
-    private readonly _objectId: ObjectId,
-    private readonly _protocol?: string,
-    private readonly _host?: string,
-    private readonly _dxn?: DXN,
-  ) {}
-
-  get dxn(): DXN | undefined {
-    return this._dxn;
-  }
-
-  /**
-   * @deprecated
-   */
-  // TODO(dmaretskyi): Remove.
-  get objectId(): ObjectId {
-    return this._objectId;
-  }
-
-  /**
-   * @deprecated
-   */
-  // TODO(dmaretskyi): Remove.
-  get protocol(): string | undefined {
-    return this._protocol;
-  }
-
-  /**
-   * @deprecated
-   */
-  // TODO(dmaretskyi): Remove.
-  get host(): string | undefined {
-    return this._host;
-  }
-
-  encode(): ReferenceProto {
-    return { objectId: this.objectId, host: this.host, protocol: this.protocol };
-  }
-
-  // TODO(dmaretskyi): Remove in favor of `reference.dxn`.
-  toDXN(): DXN {
-    if (this._dxn) {
-      return this._dxn;
-    }
-
-    if (this.protocol === Reference.TYPE_PROTOCOL) {
-      return new DXN(DXN.kind.TYPE, [this.objectId]);
-    } else {
-      if (this.host) {
-        // Host is assumed to be the space key.
-        // The DXN should actually have the space ID.
-        // TODO(dmaretskyi): Migrate to space id.
-        return new DXN(DXN.kind.ECHO, [this.host, this.objectId]);
-      } else {
-        return new DXN(DXN.kind.ECHO, [LOCAL_SPACE_TAG, this.objectId]);
-      }
-    }
-  }
-}
+import { URI } from '@dxos/keys';
 
 // TODO(dmaretskyi): Is this used anywhere?
 export const REFERENCE_TYPE_TAG = 'dxos.echo.model.document.Reference';
@@ -131,55 +12,26 @@ export const REFERENCE_TYPE_TAG = 'dxos.echo.model.document.Reference';
  * Reference as it is stored in Automerge document.
  */
 export type EncodedReference = {
-  '/': string;
-};
-
-/**
- * @deprecated Use `EncodedReference.fromDXN` instead.
- */
-export const encodeReference = (reference: Reference): EncodedReference => ({
-  '/': reference.toDXN().toString(),
-});
-
-/**
- * @deprecated Use `EncodedReference.toDXN` instead.
- */
-export const decodeReference = (value: any) => {
-  if (typeof value !== 'object' || value === null || typeof value['/'] !== 'string') {
-    throw new Error('Invalid reference');
-  }
-  const dxnString = value['/'];
-
-  if (
-    dxnString.length % 2 === 0 &&
-    dxnString.slice(0, dxnString.length / 2) === dxnString.slice(dxnString.length / 2) &&
-    dxnString.includes('dxn:echo')
-  ) {
-    throw new Error('Automerge bug detected!');
-  }
-
-  return Reference.fromDXN(DXN.parse(dxnString));
+  '/': URI.URI;
 };
 
-/**
- * @deprecated Use `EncodedReference.isEncodedReference` instead.
- */
 export const isEncodedReference = (value: any): value is EncodedReference =>
   typeof value === 'object' && value !== null && Object.keys(value).length === 1 && typeof value['/'] === 'string';
 
 export const EncodedReference = Object.freeze({
   isEncodedReference,
-  getReferenceString: (value: EncodedReference): string => {
+  /**
+   * Returns the opaque URI stored in the encoded reference (any scheme: `echo:` or `dxn:`).
+   * Consumers can narrow with `EID.isEID(uri)` / `DXN.isDXN(uri)`.
+   */
+  toURI: (value: EncodedReference): URI.URI => {
     assertArgument(isEncodedReference(value), 'value', 'invalid reference');
     return value['/'];
   },
-  toDXN: (value: EncodedReference): DXN => {
-    return DXN.parse(EncodedReference.getReferenceString(value));
-  },
-  fromDXN: (dxn: DXN): EncodedReference => {
-    return { '/': dxn.toString() };
-  },
-  fromLegacyTypename: (typename: string): EncodedReference => {
-    return { '/': DXN.fromTypename(typename).toString() };
+  /**
+   * Creates an encoded reference from an opaque URI.
+   */
+  fromURI: (uri: URI.URI): EncodedReference => {
+    return { '/': uri };
   },
 });