@dxos/echo 0.9.0 → 0.9.1-staging.ee54ba693a

package/src/internal/Filter/match.ts

@@ -0,0 +1,284 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as semver from 'semver';
+
+import { EncodedReference, type QueryAST, isEncodedReference } from '@dxos/echo-protocol';
+import { DXN, EID } from '@dxos/keys';
+
+import { getTypeURI } from '../Annotation/annotations';
+import { getMetaChecked } from '../common/api/meta';
+import { type AnyEntity } from '../common/types';
+import { objectToJSON } from '../Obj/json-serializer';
+
+/**
+ * Matches a tag filter against an object's stored tags. Tags may be stored as encoded references or
+ * (in legacy data) bare URI strings, and those URIs may be in legacy DXN form. Both sides are
+ * normalized to the canonical EID before comparing.
+ */
+export const matchesTag = (tags: readonly unknown[], filterTag: string): boolean => {
+  const canonical = (uri: string): string => {
+    const eid = EID.tryParse(uri);
+    return (eid && EID.getEntityId(eid)) || uri;
+  };
+  const normalize = (tag: unknown): string =>
+    canonical(isEncodedReference(tag) ? EncodedReference.toURI(tag) : (tag as string));
+  const target = canonical(filterTag);
+  return tags.some((tag) => normalize(tag) === target);
+};
+
+/**
+ * Matches a meta `key` / `version` constraint against an object's meta `key` and `version`.
+ */
+export const matchMetaKey = (
+  key: string,
+  versionRange: string | undefined,
+  objKey: string | undefined,
+  objVersion: string | undefined,
+): boolean => {
+  if (objKey !== key) {
+    return false;
+  }
+  if (versionRange === undefined) {
+    return true;
+  }
+  if (objVersion === undefined || semver.valid(objVersion) === null) {
+    return false;
+  }
+  if (semver.validRange(versionRange) === null) {
+    return false;
+  }
+  return semver.satisfies(objVersion, versionRange, { includePrerelease: true });
+};
+
+/**
+ * Compares a filter's type discriminator against the value stored on an object's `system.type`.
+ */
+export const compareTypenameStrings = (expectedStr: string, actualStr: string): boolean => {
+  const expectedEid = EID.tryParse(expectedStr);
+  if (expectedEid) {
+    const actualEid = EID.tryParse(actualStr);
+    if (!actualEid) {
+      return false;
+    }
+    if (EID.getEntityId(expectedEid) !== EID.getEntityId(actualEid)) {
+      return false;
+    }
+    const expectedSpaceId = EID.getSpaceId(expectedEid);
+    const actualSpaceId = EID.getSpaceId(actualEid);
+    return expectedSpaceId === undefined || actualSpaceId === undefined || expectedSpaceId === actualSpaceId;
+  }
+
+  const expectedDxn = DXN.tryMake(expectedStr);
+  if (expectedDxn) {
+    const actualDxn = DXN.tryMake(actualStr);
+    if (!actualDxn) {
+      return false;
+    }
+    if (DXN.getName(expectedDxn) !== DXN.getName(actualDxn)) {
+      return false;
+    }
+    const expectedVersion = DXN.getVersion(expectedDxn);
+    const actualVersion = DXN.getVersion(actualDxn);
+    return expectedVersion === undefined || actualVersion === undefined || expectedVersion === actualVersion;
+  }
+
+  return expectedStr === actualStr;
+};
+
+const structuralMatch = (filterObj: any, targetObj: any, strict = true): boolean => {
+  if (typeof filterObj !== 'object' || filterObj === null) {
+    return filterObj === targetObj;
+  }
+
+  if (typeof targetObj !== 'object' || targetObj === null) {
+    return false;
+  }
+
+  const filterKeys = Object.keys(filterObj);
+  const targetKeys = Object.keys(targetObj);
+  if (strict && filterKeys.length !== targetKeys.length) {
+    return false;
+  }
+
+  return filterKeys.every((key) => {
+    if (!(key in targetObj)) {
+      return false;
+    }
+    const filterValue = filterObj[key];
+    const targetValue = targetObj[key];
+
+    if (typeof filterValue === 'object' && filterValue !== null) {
+      return structuralMatch(filterValue, targetValue);
+    }
+
+    return filterValue === targetValue;
+  });
+};
+
+export const filterMatchValue = (filter: QueryAST.Filter, value: unknown): boolean => {
+  switch (filter.type) {
+    case 'compare': {
+      const compareValue = filter.value as any;
+      switch (filter.operator) {
+        case 'eq':
+          if (isEncodedReference(compareValue)) {
+            if (!isEncodedReference(value)) {
+              return false;
+            }
+            return EncodedReference.toURI(value) === EncodedReference.toURI(compareValue);
+          }
+          return value === compareValue;
+        case 'neq':
+          return value !== compareValue;
+        case 'gt':
+          return (value as any) > compareValue;
+        case 'gte':
+          return (value as any) >= compareValue;
+        case 'lt':
+          return (value as any) < compareValue;
+        case 'lte':
+          return (value as any) <= compareValue;
+        default:
+          return false;
+      }
+    }
+    case 'object': {
+      if (typeof value !== 'object' || value === null) {
+        return false;
+      }
+
+      if (filter.props) {
+        for (const [key, valueFilter] of Object.entries(filter.props)) {
+          const nestedValue = (value as any)[key];
+          if (!filterMatchValue(valueFilter, nestedValue)) {
+            return false;
+          }
+        }
+      }
+
+      return true;
+    }
+    case 'in': {
+      return filter.values.includes(value);
+    }
+    case 'contains': {
+      if (!Array.isArray(value)) {
+        return false;
+      }
+
+      return value.some((element) => {
+        if (typeof filter.value === 'object' && filter.value !== null && !Array.isArray(filter.value)) {
+          return structuralMatch(filter.value, element);
+        }
+
+        return element === filter.value;
+      });
+    }
+    case 'range': {
+      return (value as any) >= filter.from && (value as any) <= filter.to;
+    }
+    case 'not': {
+      return !filterMatchValue(filter.filter, value);
+    }
+    case 'and': {
+      return filter.filters.every((f) => filterMatchValue(f, value));
+    }
+    case 'or': {
+      return filter.filters.some((f) => filterMatchValue(f, value));
+    }
+    default:
+      return false;
+  }
+};
+
+/**
+ * Matches a filter against an entity proxy without full JSON serialization when possible.
+ */
+export const filterMatchEntity = (filter: QueryAST.Filter, entity: AnyEntity): boolean => {
+  switch (filter.type) {
+    case 'object': {
+      if (filter.typename !== null) {
+        const typeURI = getTypeURI(entity);
+        if (!typeURI || !compareTypenameStrings(filter.typename, typeURI)) {
+          return false;
+        }
+      }
+
+      if (filter.id && filter.id.length > 0 && !filter.id.includes(entity.id)) {
+        return false;
+      }
+
+      if (filter.props) {
+        let json: ReturnType<typeof objectToJSON> | null = null;
+        try {
+          json = objectToJSON(entity);
+        } catch {
+          // Serialization of complex static-type entities may throw.
+        }
+        if (json === null) {
+          return false;
+        }
+        for (const [key, valueFilter] of Object.entries(filter.props)) {
+          if (key.startsWith('@')) {
+            continue;
+          }
+          if (!filterMatchValue(valueFilter, (json as any)[key])) {
+            return false;
+          }
+        }
+      }
+
+      const meta = getMetaChecked(entity);
+
+      if (filter.foreignKeys && filter.foreignKeys.length > 0) {
+        const hasKey = filter.foreignKeys.some((fk) => meta.keys.some((k) => k.source === fk.source && k.id === fk.id));
+        if (!hasKey) {
+          return false;
+        }
+      }
+
+      if (filter.metaKey !== undefined) {
+        if (!matchMetaKey(filter.metaKey, filter.metaVersion, meta.key, meta.version)) {
+          return false;
+        }
+      }
+
+      return true;
+    }
+
+    case 'tag': {
+      const rawTags = getMetaChecked(entity).tags;
+      const tags = rawTags.map((tag: any) => (typeof tag?.encode === 'function' ? tag.encode() : tag));
+      return matchesTag(tags, filter.tag);
+    }
+
+    case 'text-search': {
+      return false;
+    }
+
+    case 'timestamp': {
+      throw new Error('Timestamp filters must be handled at the index level, not in-memory matching.');
+    }
+
+    case 'child-of': {
+      throw new Error('child-of filters must be handled at the executor level, not in-memory matching.');
+    }
+
+    case 'not': {
+      return !filterMatchEntity(filter.filter, entity);
+    }
+
+    case 'and': {
+      return filter.filters.every((f) => filterMatchEntity(f, entity));
+    }
+
+    case 'or': {
+      return filter.filters.some((f) => filterMatchEntity(f, entity));
+    }
+
+    default:
+      return false;
+  }
+};

package/src/internal/Format/format.ts

@@ -29,8 +29,6 @@ export namespace Format {
   export const Email = StringUtil.Email;
   export const Formula = StringUtil.Formula;
   export const Hostname = StringUtil.Hostname;
-  export const JSON = StringUtil.JSON;
-  export const Markdown = StringUtil.Markdown;
   export const Regex = StringUtil.Regex;
   export const URL = StringUtil.URL;
   export const UUID = Schema.UUID;

package/src/internal/Format/index.ts

@@ -4,8 +4,8 @@
 
 export * from './date';
 export * from './format';
-export { CurrencyAnnotationId, DecimalPrecision, Currency } from './number';
-export { GeoPoint, GeoLocation } from './object';
+export { Currency, CurrencyAnnotationId, DecimalPrecision } from './number';
+export { GeoLocation, GeoPoint } from './object';
 export * from './select';
 export * from './string';
 export * from './types';

package/src/internal/Format/string.ts

@@ -32,18 +32,6 @@ export const Formula = Schema.String.pipe(FormatAnnotation.set(TypeFormat.Formul
 // TODO(burdon): Implement.
 export const Hostname = Schema.String.pipe(FormatAnnotation.set(TypeFormat.Hostname));
 
-/**
- *
- */
-// TODO(burdon): Implement.
-export const JSON = Schema.String.pipe(FormatAnnotation.set(TypeFormat.JSON));
-
-/**
- *
- */
-// TODO(burdon): Implement.
-export const Markdown = Schema.String.pipe(FormatAnnotation.set(TypeFormat.Markdown));
-
 /**
  * Regex
  * https://json-schema.org/understanding-json-schema/reference/regular_expressions

package/src/internal/Format/types.ts

@@ -7,7 +7,7 @@ import type * as JSONSchema from 'effect/JSONSchema';
 import * as Option from 'effect/Option';
 import * as SchemaAST from 'effect/SchemaAST';
 
-import { createAnnotationHelper } from '../Annotation/util';
+import { createAnnotationHelper } from '../Annotation';
 import { type JsonSchemaType } from '../JsonSchema';
 
 // TODO(burdon): Rename PropertyType.
@@ -79,10 +79,11 @@ export enum TypeFormat {
   DID = 'did', // Users, etc.
   DXN = 'dxn',
   Email = 'email',
-  Formula = 'formula', // Spreadsheet formula.
+  Formula = 'formula', // Spreadsheet (Excel, Google Sheets, etc.) formula.
   Hostname = 'hostname',
   JSON = 'json',
   Markdown = 'markdown',
+  Password = 'password',
   Regex = 'regex',
   SingleSelect = 'single-select',
   Text = 'text',
@@ -149,6 +150,7 @@ export const formatToType: Record<TypeFormat, TypeEnum> = {
   [TypeFormat.Hostname]: TypeEnum.String,
   [TypeFormat.JSON]: TypeEnum.String,
   [TypeFormat.Markdown]: TypeEnum.String,
+  [TypeFormat.Password]: TypeEnum.String,
   [TypeFormat.Regex]: TypeEnum.String,
   [TypeFormat.URL]: TypeEnum.String,
   [TypeFormat.UUID]: TypeEnum.String,

package/src/internal/JsonSchema/json-schema.test.ts

@@ -33,9 +33,7 @@ const EXAMPLE_NAMESPACE = '@example';
 
 describe('effect-to-json', () => {
   test('type annotation', () => {
-    const Test = Schema.Struct({ name: Schema.String }).pipe(
-      Type.makeObject(DXN.make('com.example.type.test', '0.1.0')),
-    );
+    const Test = Type.makeObject(DXN.make('com.example.type.test', '0.1.0'))(Schema.Struct({ name: Schema.String }));
     const jsonSchema = toJsonSchema(Test);
     expect(jsonSchema.$id).toEqual('dxn:com.example.type.test:0.1.0');
     expect(jsonSchema.version).toEqual('0.1.0');
@@ -43,20 +41,26 @@ describe('effect-to-json', () => {
 
   test('property meta annotation', () => {
     const meta = { maxLength: 0 };
-    const Test = Schema.Struct({
-      name: Schema.String.pipe(PropertyMeta(EXAMPLE_NAMESPACE, meta)),
-    }).pipe(Type.makeObject(DXN.make('com.example.type.test', '0.1.0')));
+    const Test = Type.makeObject(DXN.make('com.example.type.test', '0.1.0'))(
+      Schema.Struct({
+        name: Schema.String.pipe(PropertyMeta(EXAMPLE_NAMESPACE, meta)),
+      }),
+    );
     const jsonSchema = toJsonSchema(Test);
     expect(getNormalizedEchoAnnotations(jsonSchema.properties!.name!)!.meta![EXAMPLE_NAMESPACE]).to.deep.eq(meta);
   });
 
   test('reference annotation', () => {
-    const Nested = Schema.Struct({
-      name: Schema.String,
-    }).pipe(Type.makeObject(DXN.make('com.example.type.testNested', '0.1.0')));
-    const Test = Schema.Struct({
-      name: Ref(Nested),
-    }).pipe(Type.makeObject(DXN.make('com.example.type.test', '0.1.0')));
+    const Nested = Type.makeObject(DXN.make('com.example.type.testNested', '0.1.0'))(
+      Schema.Struct({
+        name: Schema.String,
+      }),
+    );
+    const Test = Type.makeObject(DXN.make('com.example.type.test', '0.1.0'))(
+      Schema.Struct({
+        name: Ref(Nested),
+      }),
+    );
     const jsonSchema = toJsonSchema(Test);
     // log.info('schema', { jsonSchema });
     const nested = jsonSchema.properties!.name;
@@ -66,12 +70,16 @@ describe('effect-to-json', () => {
   // TODO(ZaymonFC): @dmaretskyi we still need to fix this.
   // TODO(dmaretskyi): Remove FieldLookupAnnotationId.
   test.skip('reference annotation with lookup property', () => {
-    const Nested = Schema.Struct({
-      name: Schema.String,
-    }).pipe(Type.makeObject(DXN.make('com.example.type.testNested', '0.1.0')));
-    const Test = Schema.Struct({
-      name: Ref(Nested).annotations({ [FieldLookupAnnotationId]: 'name' }),
-    }).pipe(Type.makeObject(DXN.make('com.example.type.test', '0.1.0')));
+    const Nested = Type.makeObject(DXN.make('com.example.type.testNested', '0.1.0'))(
+      Schema.Struct({
+        name: Schema.String,
+      }),
+    );
+    const Test = Type.makeObject(DXN.make('com.example.type.test', '0.1.0'))(
+      Schema.Struct({
+        name: Ref(Nested).annotations({ [FieldLookupAnnotationId]: 'name' }),
+      }),
+    );
     const jsonSchema = toJsonSchema(Test);
     const effectSchema = toEffectSchema(jsonSchema);
 
@@ -80,24 +88,32 @@ describe('effect-to-json', () => {
   });
 
   test('array of references', () => {
-    const Nested = Schema.Struct({
-      name: Schema.String,
-    }).pipe(Type.makeObject(DXN.make('com.example.type.testNested', '0.1.0')));
-    const Test = Schema.Struct({
-      name: Schema.Array(Ref(Nested)),
-    }).pipe(Type.makeObject(DXN.make('com.example.type.test', '0.1.0')));
+    const Nested = Type.makeObject(DXN.make('com.example.type.testNested', '0.1.0'))(
+      Schema.Struct({
+        name: Schema.String,
+      }),
+    );
+    const Test = Type.makeObject(DXN.make('com.example.type.test', '0.1.0'))(
+      Schema.Struct({
+        name: Schema.Array(Ref(Nested)),
+      }),
+    );
 
     const jsonSchema = toJsonSchema(Test);
     expectReferenceAnnotation((jsonSchema.properties!.name as any).items);
   });
 
   test('optional references', () => {
-    const Nested = Schema.Struct({
-      name: Schema.String,
-    }).pipe(Type.makeObject(DXN.make('com.example.type.testNested', '0.1.0')));
-    const Test = Schema.Struct({
-      name: Schema.optional(Ref(Nested)),
-    }).pipe(Type.makeObject(DXN.make('com.example.type.test', '0.1.0')));
+    const Nested = Type.makeObject(DXN.make('com.example.type.testNested', '0.1.0'))(
+      Schema.Struct({
+        name: Schema.String,
+      }),
+    );
+    const Test = Type.makeObject(DXN.make('com.example.type.test', '0.1.0'))(
+      Schema.Struct({
+        name: Schema.optional(Ref(Nested)),
+      }),
+    );
     const jsonSchema = toJsonSchema(Test);
     expectReferenceAnnotation(jsonSchema.properties!.name);
   });
@@ -110,12 +126,14 @@ describe('effect-to-json', () => {
   });
 
   test('annotations', () => {
-    const TempSchema = Schema.Struct({
-      name: Schema.String.annotations({ description: 'Person name', title: 'Name' }),
-      email: Schema.String.pipe(FormatAnnotation.set(TypeFormat.Email)).annotations({
-        description: 'Email address',
+    const TempSchema = Type.makeObject(DXN.make('com.example.type.person', '0.1.0'))(
+      Schema.Struct({
+        name: Schema.String.annotations({ description: 'Person name', title: 'Name' }),
+        email: Schema.String.pipe(FormatAnnotation.set(TypeFormat.Email)).annotations({
+          description: 'Email address',
+        }),
       }),
-    }).pipe(Type.makeObject(DXN.make('com.example.type.person', '0.1.0')));
+    );
 
     const jsonSchema = toJsonSchema(TempSchema);
     expect(jsonSchema).to.deep.eq({
@@ -159,14 +177,18 @@ describe('effect-to-json', () => {
   });
 
   test('reference property by ref', () => {
-    const Organization = Schema.Struct({
-      field: Schema.String,
-    }).pipe(Type.makeObject(DXN.make('com.example.type.organization', '0.1.0')));
+    const Organization = Type.makeObject(DXN.make('com.example.type.organization', '0.1.0'))(
+      Schema.Struct({
+        field: Schema.String,
+      }),
+    );
 
-    const Contact = Schema.Struct({
-      name: Schema.String,
-      organization: Ref(Organization).annotations({ description: 'Contact organization' }),
-    }).pipe(Type.makeObject(DXN.make('com.example.type.person', '0.1.0')));
+    const Contact = Type.makeObject(DXN.make('com.example.type.person', '0.1.0'))(
+      Schema.Struct({
+        name: Schema.String,
+        organization: Ref(Organization).annotations({ description: 'Contact organization' }),
+      }),
+    );
 
     // log.info('Contact', { ast: Contact.ast });
 
@@ -211,14 +233,18 @@ describe('effect-to-json', () => {
   });
 
   test('add reference property', () => {
-    const Organization = Schema.Struct({
-      field: Schema.String,
-    }).pipe(Type.makeObject(DXN.make('com.example.type.organization', '0.1.0')));
+    const Organization = Type.makeObject(DXN.make('com.example.type.organization', '0.1.0'))(
+      Schema.Struct({
+        field: Schema.String,
+      }),
+    );
 
-    const Contact = Schema.Struct({
-      name: Schema.String,
-      organization: Ref(Organization).annotations({ description: 'Contact organization' }),
-    }).pipe(Type.makeObject(DXN.make('com.example.type.person', '0.1.0')));
+    const Contact = Type.makeObject(DXN.make('com.example.type.person', '0.1.0'))(
+      Schema.Struct({
+        name: Schema.String,
+        organization: Ref(Organization).annotations({ description: 'Contact organization' }),
+      }),
+    );
 
     const jsonSchema = toJsonSchema(Contact);
     setSchemaProperty(
@@ -418,9 +444,11 @@ describe('json-to-effect', () => {
 
   for (const partial of [false, true]) {
     test(`deserialized equals original ${partial ? 'with partial' : ''}`, () => {
-      const Organization = Schema.Struct({
-        field: Schema.String,
-      }).pipe(Type.makeObject(DXN.make('com.example.type.organization', '0.1.0')));
+      const Organization = Type.makeObject(DXN.make('com.example.type.organization', '0.1.0'))(
+        Schema.Struct({
+          field: Schema.String,
+        }),
+      );
 
       const fields = {
         string: Schema.String,
@@ -436,8 +464,8 @@ describe('json-to-effect', () => {
         null: Schema.Null,
       } as const;
 
-      const Test = (partial ? Schema.partial(Schema.Struct(fields)) : Schema.Struct(fields)).pipe(
-        Type.makeObject(DXN.make('com.example.type.test', '0.1.0')),
+      const Test = Type.makeObject(DXN.make('com.example.type.test', '0.1.0'))(
+        partial ? Schema.partial(Schema.Struct(fields)) : Schema.Struct(fields),
       );
 
       const jsonSchema = toJsonSchema(Test);