@dxos/echo-protocol 0.8.4-main.1da679c → 0.8.4-main.21d9917

package/package.json

@@ -1,13 +1,16 @@
 {
   "name": "@dxos/echo-protocol",
-  "version": "0.8.4-main.1da679c",
+  "version": "0.8.4-main.21d9917",
   "description": "Core ECHO APIs.",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
-  "repository": "github:dxos/dxos",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dxos/dxos"
+  },
   "license": "MIT",
   "author": "DXOS.org",
-  "sideEffects": true,
+  "sideEffects": false,
   "type": "module",
   "exports": {
     ".": {
@@ -26,12 +29,12 @@
     "src"
   ],
   "dependencies": {
-    "effect": "3.17.7",
-    "@dxos/crypto": "0.8.4-main.1da679c",
-    "@dxos/invariant": "0.8.4-main.1da679c",
-    "@dxos/keys": "0.8.4-main.1da679c",
-    "@dxos/protocols": "0.8.4-main.1da679c",
-    "@dxos/util": "0.8.4-main.1da679c"
+    "effect": "3.19.11",
+    "@dxos/crypto": "0.8.4-main.21d9917",
+    "@dxos/invariant": "0.8.4-main.21d9917",
+    "@dxos/keys": "0.8.4-main.21d9917",
+    "@dxos/protocols": "0.8.4-main.21d9917",
+    "@dxos/util": "0.8.4-main.21d9917"
   },
   "publishConfig": {
     "access": "public"

package/src/document-structure.ts

@@ -153,6 +153,10 @@ export const ObjectStructure = Object.freeze({
     return references;
   },
 
+  getTags: (object: ObjectStructure): string[] => {
+    return object.meta.tags ?? [];
+  },
+
   makeObject: ({
     type,
     data,
@@ -214,6 +218,14 @@ export type ObjectMeta = {
    * Foreign keys.
    */
   keys: ForeignKey[];
+
+  /**
+   * Tags.
+   * An array of DXNs of Tag objects within the space.
+   *
+   * NOTE: Optional for backwards compatibilty.
+   */
+  tags?: string[];
 };
 
 /**

package/src/foreign-key.ts

@@ -2,7 +2,8 @@
 // Copyright 2025 DXOS.org
 //
 
-import { Schema, SchemaAST } from 'effect';
+import * as Schema from 'effect/Schema';
+import * as SchemaAST from 'effect/SchemaAST';
 
 const ForeignKey_ = Schema.Struct({
   /**
@@ -15,8 +16,8 @@ const ForeignKey_ = Schema.Struct({
    * Id within the foreign database.
    */
   // TODO(wittjosiah): This annotation is currently used to ensure id field shows up in forms.
-  // TODO(dmaretskyi): `false` is not a valid value for the annotation.
-  id: Schema.String.annotations({ [SchemaAST.IdentifierAnnotationId]: false }),
+  // TODO(dmaretskyi): `false` is not a valid value for the annotation. Use a different annotation.
+  id: Schema.String.annotations({ [SchemaAST.IdentifierAnnotationId]: 'false' }),
 });
 
 export type ForeignKey = Schema.Schema.Type<typeof ForeignKey_>;

package/src/query/ast.ts

@@ -2,14 +2,15 @@
 // Copyright 2025 DXOS.org
 //
 
-import { Match, Schema } from 'effect';
+import * as Match from 'effect/Match';
+import * as Schema from 'effect/Schema';
 
 import { DXN, ObjectId } from '@dxos/keys';
 
 import { ForeignKey } from '../foreign-key';
 
 const TypenameSpecifier = Schema.Union(DXN.Schema, Schema.Null).annotations({
-  description: 'DXN or null. Null means any type will match',
+  description: 'DXN or null; null matches any type',
 });
 
 // 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.
@@ -46,6 +47,9 @@ const FilterObject_ = Schema.Struct({
 export interface FilterObject extends Schema.Schema.Type<typeof FilterObject_> {}
 export const FilterObject: Schema.Schema<FilterObject> = FilterObject_;
 
+/**
+ * Compare.
+ */
 const FilterCompare_ = Schema.Struct({
   type: Schema.Literal('compare'),
   operator: Schema.Literal('eq', 'neq', 'gt', 'gte', 'lt', 'lte'),
@@ -54,6 +58,9 @@ const FilterCompare_ = Schema.Struct({
 export interface FilterCompare extends Schema.Schema.Type<typeof FilterCompare_> {}
 export const FilterCompare: Schema.Schema<FilterCompare> = FilterCompare_;
 
+/**
+ * In.
+ */
 const FilterIn_ = Schema.Struct({
   type: Schema.Literal('in'),
   values: Schema.Array(Schema.Any),
@@ -61,65 +68,106 @@ const FilterIn_ = Schema.Struct({
 export interface FilterIn extends Schema.Schema.Type<typeof FilterIn_> {}
 export const FilterIn: Schema.Schema<FilterIn> = FilterIn_;
 
+/**
+ * Contains.
+ */
 const FilterContains_ = Schema.Struct({
   type: Schema.Literal('contains'),
   value: Schema.Any,
 });
+
 export interface FilterContains extends Schema.Schema.Type<typeof FilterContains_> {}
+
 /**
  * Predicate for an array property to contain the provided value.
  * Nested objects are matched using strict structural matching.
  */
 export const FilterContains: Schema.Schema<FilterContains> = FilterContains_;
 
+/**
+ * Filters objects that have certain tag.
+ */
+const FilterTag_ = Schema.Struct({
+  type: Schema.Literal('tag'),
+  tag: Schema.String, // TODO(burdon): Make OR-collection?
+});
+
+export interface FilterTag extends Schema.Schema.Type<typeof FilterTag_> {}
+export const FilterTag: Schema.Schema<FilterTag> = FilterTag_;
+
+/**
+ * Range.
+ */
 const FilterRange_ = Schema.Struct({
   type: Schema.Literal('range'),
   from: Schema.Any,
   to: Schema.Any,
 });
+
 export interface FilterRange extends Schema.Schema.Type<typeof FilterRange_> {}
 export const FilterRange: Schema.Schema<FilterRange> = FilterRange_;
 
+/**
+ * Text search.
+ */
 const FilterTextSearch_ = Schema.Struct({
   type: Schema.Literal('text-search'),
   text: Schema.String,
   searchKind: Schema.optional(Schema.Literal('full-text', 'vector')),
 });
+
 export interface FilterTextSearch extends Schema.Schema.Type<typeof FilterTextSearch_> {}
 export const FilterTextSearch: Schema.Schema<FilterTextSearch> = FilterTextSearch_;
 
+/**
+ * Not.
+ */
 const FilterNot_ = Schema.Struct({
   type: Schema.Literal('not'),
   filter: Schema.suspend(() => Filter),
 });
+
 export interface FilterNot extends Schema.Schema.Type<typeof FilterNot_> {}
 export const FilterNot: Schema.Schema<FilterNot> = FilterNot_;
 
+/**
+ * And.
+ */
 const FilterAnd_ = Schema.Struct({
   type: Schema.Literal('and'),
   filters: Schema.Array(Schema.suspend(() => Filter)),
 });
+
 export interface FilterAnd extends Schema.Schema.Type<typeof FilterAnd_> {}
 export const FilterAnd: Schema.Schema<FilterAnd> = FilterAnd_;
 
+/**
+ * Or.
+ */
 const FilterOr_ = Schema.Struct({
   type: Schema.Literal('or'),
   filters: Schema.Array(Schema.suspend(() => Filter)),
 });
+
 export interface FilterOr extends Schema.Schema.Type<typeof FilterOr_> {}
 export const FilterOr: Schema.Schema<FilterOr> = FilterOr_;
 
+/**
+ * Union of filters.
+ */
 export const Filter = Schema.Union(
   FilterObject,
-  FilterTextSearch,
   FilterCompare,
   FilterIn,
   FilterContains,
+  FilterTag,
   FilterRange,
+  FilterTextSearch,
   FilterNot,
   FilterAnd,
   FilterOr,
-);
+).annotations({ identifier: 'dxos.org/schema/Filter' });
+
 export type Filter = Schema.Schema.Type<typeof Filter>;
 
 /**
@@ -129,6 +177,7 @@ const QuerySelectClause_ = Schema.Struct({
   type: Schema.Literal('select'),
   filter: Schema.suspend(() => Filter),
 });
+
 export interface QuerySelectClause extends Schema.Schema.Type<typeof QuerySelectClause_> {}
 export const QuerySelectClause: Schema.Schema<QuerySelectClause> = QuerySelectClause_;
 
@@ -140,6 +189,7 @@ const QueryFilterClause_ = Schema.Struct({
   selection: Schema.suspend(() => Query),
   filter: Schema.suspend(() => Filter),
 });
+
 export interface QueryFilterClause extends Schema.Schema.Type<typeof QueryFilterClause_> {}
 export const QueryFilterClause: Schema.Schema<QueryFilterClause> = QueryFilterClause_;
 
@@ -151,6 +201,7 @@ const QueryReferenceTraversalClause_ = Schema.Struct({
   anchor: Schema.suspend(() => Query),
   property: Schema.String, // TODO(dmaretskyi): Change to EscapedPropPath.
 });
+
 export interface QueryReferenceTraversalClause extends Schema.Schema.Type<typeof QueryReferenceTraversalClause_> {}
 export const QueryReferenceTraversalClause: Schema.Schema<QueryReferenceTraversalClause> =
   QueryReferenceTraversalClause_;
@@ -161,9 +212,14 @@ export const QueryReferenceTraversalClause: Schema.Schema<QueryReferenceTraversa
 const QueryIncomingReferencesClause_ = Schema.Struct({
   type: Schema.Literal('incoming-references'),
   anchor: Schema.suspend(() => Query),
-  property: Schema.String,
+  /**
+   * Property path where the reference is located.
+   * If null, matches references from any property.
+   */
+  property: Schema.NullOr(Schema.String),
   typename: TypenameSpecifier,
 });
+
 export interface QueryIncomingReferencesClause extends Schema.Schema.Type<typeof QueryIncomingReferencesClause_> {}
 export const QueryIncomingReferencesClause: Schema.Schema<QueryIncomingReferencesClause> =
   QueryIncomingReferencesClause_;
@@ -182,6 +238,7 @@ const QueryRelationClause_ = Schema.Struct({
   direction: Schema.Literal('outgoing', 'incoming', 'both'),
   filter: Schema.optional(Schema.suspend(() => Filter)),
 });
+
 export interface QueryRelationClause extends Schema.Schema.Type<typeof QueryRelationClause_> {}
 export const QueryRelationClause: Schema.Schema<QueryRelationClause> = QueryRelationClause_;
 
@@ -193,6 +250,7 @@ const QueryRelationTraversalClause_ = Schema.Struct({
   anchor: Schema.suspend(() => Query),
   direction: Schema.Literal('source', 'target', 'both'),
 });
+
 export interface QueryRelationTraversalClause extends Schema.Schema.Type<typeof QueryRelationTraversalClause_> {}
 export const QueryRelationTraversalClause: Schema.Schema<QueryRelationTraversalClause> = QueryRelationTraversalClause_;
 
@@ -203,6 +261,7 @@ const QueryUnionClause_ = Schema.Struct({
   type: Schema.Literal('union'),
   queries: Schema.Array(Schema.suspend(() => Query)),
 });
+
 export interface QueryUnionClause extends Schema.Schema.Type<typeof QueryUnionClause_> {}
 export const QueryUnionClause: Schema.Schema<QueryUnionClause> = QueryUnionClause_;
 
@@ -214,6 +273,7 @@ const QuerySetDifferenceClause_ = Schema.Struct({
   source: Schema.suspend(() => Query),
   exclude: Schema.suspend(() => Query),
 });
+
 export interface QuerySetDifferenceClause extends Schema.Schema.Type<typeof QuerySetDifferenceClause_> {}
 export const QuerySetDifferenceClause: Schema.Schema<QuerySetDifferenceClause> = QuerySetDifferenceClause_;
 
@@ -230,7 +290,14 @@ const Order_ = Schema.Union(
     property: Schema.String,
     direction: OrderDirection,
   }),
+  Schema.Struct({
+    // Order by relevance rank (for FTS/vector search results).
+    // Default direction is 'desc' (higher rank = better match first).
+    kind: Schema.Literal('rank'),
+    direction: OrderDirection,
+  }),
 );
+
 export type Order = Schema.Schema.Type<typeof Order_>;
 export const Order: Schema.Schema<Order> = Order_;
 
@@ -243,6 +310,7 @@ const QueryOrderClause_ = Schema.Struct({
   query: Schema.suspend(() => Query),
   order: Schema.Array(Order),
 });
+
 export interface QueryOrderClause extends Schema.Schema.Type<typeof QueryOrderClause_> {}
 export const QueryOrderClause: Schema.Schema<QueryOrderClause> = QueryOrderClause_;
 
@@ -254,9 +322,22 @@ const QueryOptionsClause_ = Schema.Struct({
   query: Schema.suspend(() => Query),
   options: Schema.suspend(() => QueryOptions),
 });
+
 export interface QueryOptionsClause extends Schema.Schema.Type<typeof QueryOptionsClause_> {}
 export const QueryOptionsClause: Schema.Schema<QueryOptionsClause> = QueryOptionsClause_;
 
+/**
+ * Limit the number of results.
+ */
+const QueryLimitClause_ = Schema.Struct({
+  type: Schema.Literal('limit'),
+  query: Schema.suspend(() => Query),
+  limit: Schema.Number,
+});
+
+export interface QueryLimitClause extends Schema.Schema.Type<typeof QueryLimitClause_> {}
+export const QueryLimitClause: Schema.Schema<QueryLimitClause> = QueryLimitClause_;
+
 const Query_ = Schema.Union(
   QuerySelectClause,
   QueryFilterClause,
@@ -268,7 +349,8 @@ const Query_ = Schema.Union(
   QuerySetDifferenceClause,
   QueryOrderClause,
   QueryOptionsClause,
-);
+  QueryLimitClause,
+).annotations({ identifier: 'dxos.org/schema/Query' });
 
 export type Query = Schema.Schema.Type<typeof Query_>;
 export const Query: Schema.Schema<Query> = Query_;
@@ -281,6 +363,11 @@ export const QueryOptions = Schema.Struct({
    */
   spaceIds: Schema.optional(Schema.Array(Schema.String)),
 
+  /**
+   * If true, the nested select statements will select from all queues in the spaces specified by `spaceIds`.
+   */
+  allQueuesFromSpaces: Schema.optional(Schema.Boolean),
+
   /**
    * The nested select statemets will select from the given queues.
    *
@@ -293,6 +380,7 @@ export const QueryOptions = Schema.Struct({
    */
   deleted: Schema.optional(Schema.Literal('include', 'exclude', 'only')),
 });
+
 export interface QueryOptions extends Schema.Schema.Type<typeof QueryOptions> {}
 
 export const visit = (query: Query, visitor: (node: Query) => void) => {
@@ -311,6 +399,7 @@ export const visit = (query: Query, visitor: (node: Query) => void) => {
       visit(exclude, visitor);
     }),
     Match.when({ type: 'order' }, ({ query }) => visit(query, visitor)),
+    Match.when({ type: 'limit' }, ({ query }) => visit(query, visitor)),
     Match.when({ type: 'select' }, () => {}),
     Match.exhaustive,
   );
@@ -330,6 +419,7 @@ export const fold = <T>(query: Query, reducer: (node: Query) => T): T[] => {
       fold(source, reducer).concat(fold(exclude, reducer)),
     ),
     Match.when({ type: 'order' }, ({ query }) => fold(query, reducer)),
+    Match.when({ type: 'limit' }, ({ query }) => fold(query, reducer)),
     Match.when({ type: 'select' }, () => []),
     Match.exhaustive,
   );

package/src/reference.ts

@@ -177,6 +177,9 @@ export const EncodedReference = Object.freeze({
     return DXN.parse(EncodedReference.getReferenceString(value));
   },
   fromDXN: (dxn: DXN): EncodedReference => {
-    return encodeReference(Reference.fromDXN(dxn));
+    return { '/': dxn.toString() };
+  },
+  fromLegacyTypename: (typename: string): EncodedReference => {
+    return { '/': DXN.fromTypename(typename).toString() };
   },
 });