@dxos/echo 0.8.4-main.84f28bd → 0.8.4-main.937b3ca

package/dist/lib/node-esm/chunk-MOLNWFNL.mjs

@@ -0,0 +1,9 @@
+import { createRequire } from 'node:module';const require = createRequire(import.meta.url);
+
+// src/SchemaRegistry.ts
+var SchemaRegistry_exports = {};
+
+export {
+  SchemaRegistry_exports
+};
+//# sourceMappingURL=chunk-MOLNWFNL.mjs.map

package/dist/lib/node-esm/chunk-MOLNWFNL.mjs.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/SchemaRegistry.ts"],
+  "sourcesContent": ["//\n// Copyright 2025 DXOS.org\n//\n\nimport type * as Types from 'effect/Types';\n\nimport type * as JsonSchema from './JsonSchema';\nimport type * as Key from './Key';\nimport type * as QueryResult from './QueryResult';\nimport type * as Type from './Type';\n\n// TODO(wittjosiah): Replace w/ Query.Query.\nexport type Query = {\n  /**\n   * Filter by schema ID.\n   * Schema id is a DXN with `echo` or `type` kind.\n   */\n  id?: string | string[];\n\n  /**\n   * Id of the backing ECHO object.\n   */\n  backingObjectId?: Key.ObjectId | Key.ObjectId[];\n\n  /**\n   * One or more typenames to filter by.\n   */\n  typename?: string | string[];\n\n  /**\n   * [Semver Range](https://docs.npmjs.com/cli/v6/using-npm/semver#ranges) for the schema version.\n   */\n  version?: string;\n\n  /**\n   * Where to look for the schema.\n   *\n   * Database schema are stored in the database of the current space.\n   * Runtime schema are registered in the runtime.\n   *\n   * @default ['database']\n   */\n  location?: ('database' | 'runtime')[];\n\n  /**\n   * Include system schemas.\n   * @default false\n   *\n   * The system schema include but are not limited to:\n   *  - dxos.org/type/Schema\n   */\n  includeSystem?: boolean;\n};\n\n/**\n * Input for schema registration.\n * The typename, version and schema mutability metadata is read from the schema annotations.\n *\n * Accepts:\n * - Branded ECHO schemas created with Type.Obj() or Type.Relation()\n * - JSON schema with typename and version\n */\nexport type RegisterSchemaInput =\n  | Type.Entity.Any\n  | {\n      typename: string;\n      version: string;\n      jsonSchema: JsonSchema.JsonSchema;\n      /**\n       * Display name of the schema.\n       */\n      name?: string;\n    };\n\nexport type ExtractQueryResult<Query> = Query extends { location: ('database' | 'runtime')[] }\n  ? Type.Entity.Any\n  : Type.RuntimeType;\n\nexport interface SchemaRegistry {\n  /**\n   * Checks if the provided schema is registered.\n   */\n  // TODO(burdon): Type?\n  hasSchema(schema: Type.Entity.Any): boolean;\n\n  /**\n   * Registers the provided schema.\n   *\n   * @returns Mutable runtime instances of schemas that were registered.\n   *\n   * The behavior of this method depends on the state of the database.\n   * The general principle is that the schema will be upserted into the space.\n   * If an equivalent schema with the same name and version already exists, the method does nothing.\n   * If a different schema with the same name and version exists, the method throws an error.\n   * If no schema with the same name and version exists, a new schema will be inserted based on semantic versioning rules.\n   */\n  register(input: RegisterSchemaInput[]): Promise<Type.RuntimeType[]>;\n\n  /**\n   *\n   */\n  query<Q extends Types.NoExcessProperties<Query, Q>>(\n    query?: Q & Query,\n  ): QueryResult.QueryResult<ExtractQueryResult<Q>>;\n}\n"],
+  "mappings": ";;;AAAA;",
+  "names": []
+}

package/dist/lib/node-esm/chunk-MOWUEW5P.mjs

@@ -0,0 +1,15 @@
+import { createRequire } from 'node:module';const require = createRequire(import.meta.url);
+
+// src/index.ts
+import { QueryAST } from "@dxos/echo-protocol";
+import { DXN } from "@dxos/keys";
+
+// src/Hypergraph.ts
+var Hypergraph_exports = {};
+
+export {
+  Hypergraph_exports,
+  QueryAST,
+  DXN
+};
+//# sourceMappingURL=chunk-MOWUEW5P.mjs.map

package/dist/lib/node-esm/chunk-MOWUEW5P.mjs.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/index.ts", "../../../src/Hypergraph.ts"],
+  "sourcesContent": ["//\n// Copyright 2025 DXOS.org\n//\n\nexport { QueryAST } from '@dxos/echo-protocol';\n// TODO(wittjosiah): Refactor DXN to not use statics similar to Query.\nexport { DXN } from '@dxos/keys';\n\nexport * as Annotation from './Annotation';\nexport * as Database from './Database';\nexport * as Entity from './Entity';\nexport * as Err from './Err';\nexport * as Filter from './Filter';\nexport * as Format from './Format';\nexport * as Hypergraph from './Hypergraph';\nexport * as JsonSchema from './JsonSchema';\nexport * as Key from './Key';\nexport * as Obj from './Obj';\nexport * as Order from './Order';\nexport * as Query from './Query';\nexport * as QueryResult from './QueryResult';\nexport * as Ref from './Ref';\nexport * as Relation from './Relation';\nexport * as SchemaRegistry from './SchemaRegistry';\nexport * as Tag from './Tag';\nexport * as Type from './Type';\n", "//\n// Copyright 2025 DXOS.org\n//\n\nimport { type DXN } from '@dxos/keys';\n\nimport type * as Database from './Database';\nimport type * as Entity from './Entity';\nimport { type AnyProperties } from './internal';\nimport type * as Key from './Key';\nimport type * as Ref from './Ref';\nimport type * as SchemaRegistry from './SchemaRegistry';\n\n/**\n * Resolution context.\n * Affects how non-absolute DXNs are resolved.\n */\nexport interface RefResolutionContext {\n  /**\n   * Space that the resolution is happening from.\n   */\n  space?: Key.SpaceId;\n\n  /**\n   * Queue that the resolution is happening from.\n   * This queue will be searched first, and then the space it belongs to.\n   */\n  queue?: DXN;\n}\n\nexport interface RefResolverOptions {\n  /**\n   * Resolution context.\n   * Affects how non-absolute DXNs are resolved.\n   */\n  context?: RefResolutionContext;\n\n  /**\n   * Middleware to change the resolved object before returning it.\n   * @deprecated On track to be removed.\n   */\n  middleware?: (obj: AnyProperties) => AnyProperties;\n}\n\n/**\n *\n */\n// TODO(burdon): Comment required.\nexport interface Hypergraph extends Database.Queryable {\n  get schemaRegistry(): SchemaRegistry.SchemaRegistry;\n\n  /**\n   * Query objects.\n   */\n  query: Database.QueryFn;\n\n  /**\n   * Creates a reference to an existing object in the database.\n   *\n   * NOTE: The reference may be dangling if the object is not present in the database.\n   * NOTE: Difference from `Ref.fromDXN`\n   * `Ref.fromDXN(dxn)` returns an unhydrated reference. The `.load` and `.target` APIs will not work.\n   * `db.makeRef(dxn)` is preferable in cases with access to the database.\n   */\n  makeRef<T extends Entity.Unknown = Entity.Unknown>(dxn: DXN): Ref.Ref<T>;\n\n  /**\n   * @param hostDb Host database for reference resolution.\n   * @param middleware Called with the loaded object. The caller may change the object.\n   * @returns Result of `onLoad`.\n   */\n  // TODO(dmaretskyi): Restructure API: Remove middleware.\n  createRefResolver(options: RefResolverOptions): Ref.Resolver;\n}\n"],
+  "mappings": ";;;AAIA,SAASA,gBAAgB;AAEzB,SAASC,WAAW;;;ACNpB;",
+  "names": ["QueryAST", "DXN"]
+}

package/dist/lib/node-esm/chunk-NBWL7UCZ.mjs

@@ -0,0 +1,40 @@
+import { createRequire } from 'node:module';const require = createRequire(import.meta.url);
+import {
+  DescriptionAnnotation,
+  FormInputAnnotation,
+  GeneratorAnnotation,
+  LabelAnnotation,
+  ReferenceAnnotation,
+  SystemTypeAnnotation,
+  TypeAnnotation,
+  getDescriptionWithSchema,
+  getLabelWithSchema,
+  getTypeAnnotation,
+  setDescriptionWithSchema,
+  setLabelWithSchema
+} from "./chunk-YOLH5KS4.mjs";
+import {
+  __export
+} from "./chunk-HSLMI22Q.mjs";
+
+// src/Annotation.ts
+var Annotation_exports = {};
+__export(Annotation_exports, {
+  DescriptionAnnotation: () => DescriptionAnnotation,
+  FormInputAnnotation: () => FormInputAnnotation,
+  GeneratorAnnotation: () => GeneratorAnnotation,
+  LabelAnnotation: () => LabelAnnotation,
+  ReferenceAnnotation: () => ReferenceAnnotation,
+  SystemTypeAnnotation: () => SystemTypeAnnotation,
+  TypeAnnotation: () => TypeAnnotation,
+  getDescriptionWithSchema: () => getDescriptionWithSchema,
+  getLabelWithSchema: () => getLabelWithSchema,
+  getTypeAnnotation: () => getTypeAnnotation,
+  setDescriptionWithSchema: () => setDescriptionWithSchema,
+  setLabelWithSchema: () => setLabelWithSchema
+});
+
+export {
+  Annotation_exports
+};
+//# sourceMappingURL=chunk-NBWL7UCZ.mjs.map

package/dist/lib/node-esm/chunk-NBWL7UCZ.mjs.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/Annotation.ts"],
+  "sourcesContent": ["//\n// Copyright 2025 DXOS.org\n//\n\nexport {\n  DescriptionAnnotation,\n  FormInputAnnotation,\n  GeneratorAnnotation,\n  LabelAnnotation,\n  ReferenceAnnotation,\n  SystemTypeAnnotation,\n  TypeAnnotation,\n  getDescriptionWithSchema,\n  getLabelWithSchema,\n  getTypeAnnotation,\n  setDescriptionWithSchema,\n  setLabelWithSchema,\n} from './internal/annotations';\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;;;AAAA;;;;;;;;;;;;;;;",
+  "names": []
+}

package/dist/lib/node-esm/chunk-NRN3ZW2T.mjs

@@ -0,0 +1,143 @@
+import { createRequire } from 'node:module';const require = createRequire(import.meta.url);
+import {
+  EchoObjectSchema,
+  EchoRelationSchema,
+  EchoSchema,
+  PersistentSchema,
+  Ref,
+  isMutable,
+  toEffectSchema,
+  toJsonSchema
+} from "./chunk-LT3H4JOX.mjs";
+import {
+  getSchemaDXN,
+  getSchemaTypename,
+  getSchemaVersion,
+  getTypeAnnotation
+} from "./chunk-YOLH5KS4.mjs";
+import {
+  ANY_OBJECT_TYPENAME,
+  ANY_OBJECT_VERSION,
+  EntityKind,
+  SchemaKindId
+} from "./chunk-XHJRMQZD.mjs";
+import {
+  __export
+} from "./chunk-HSLMI22Q.mjs";
+
+// src/Type.ts
+var Type_exports = {};
+__export(Type_exports, {
+  Entity: () => Entity,
+  Obj: () => Obj,
+  PersistentType: () => PersistentType,
+  Ref: () => Ref2,
+  Relation: () => Relation,
+  RuntimeType: () => EchoSchema,
+  getDXN: () => getDXN,
+  getMeta: () => getMeta,
+  getTypename: () => getTypename,
+  getVersion: () => getVersion,
+  isMutable: () => isMutable2,
+  isObjectSchema: () => isObjectSchema,
+  isRelationSchema: () => isRelationSchema,
+  object: () => object,
+  relation: () => relation,
+  toEffectSchema: () => toEffectSchema,
+  toJsonSchema: () => toJsonSchema
+});
+import * as Schema from "effect/Schema";
+import { invariant } from "@dxos/invariant";
+var __dxlog_file = "/__w/dxos/dxos/packages/core/echo/echo/src/Type.ts";
+var ObjSchema = Schema.Struct({
+  id: Schema.String
+}).pipe(Schema.extend(Schema.Record({
+  key: Schema.String,
+  value: Schema.Unknown
+})), EchoObjectSchema({
+  typename: ANY_OBJECT_TYPENAME,
+  version: ANY_OBJECT_VERSION
+}));
+var Obj = Object.assign(ObjSchema, {
+  [SchemaKindId]: ObjSchema[SchemaKindId]
+});
+var object = EchoObjectSchema;
+var PersistentType = PersistentSchema;
+var RelationSchema = Schema.Struct({
+  id: Schema.String
+}).pipe(Schema.extend(Schema.Record({
+  key: Schema.String,
+  value: Schema.Unknown
+})), EchoRelationSchema({
+  typename: "dxos.org/schema/AnyRelation",
+  version: "0.0.0",
+  source: ObjSchema,
+  target: ObjSchema
+}));
+var Relation = Object.assign(RelationSchema, {
+  [SchemaKindId]: RelationSchema[SchemaKindId]
+});
+var relation = EchoRelationSchema;
+(function(Entity2) {
+  Entity2.Any = Schema.Union(Obj, Relation);
+})(Entity || (Entity = {}));
+var isObjectSchema = (schema) => {
+  return schema[SchemaKindId] === EntityKind.Object;
+};
+var isRelationSchema = (schema) => {
+  return schema[SchemaKindId] === EntityKind.Relation;
+};
+var Ref2 = Ref;
+var getDXN = (schema) => {
+  return getSchemaDXN(schema);
+};
+var getTypename = (schema) => {
+  const typename = getSchemaTypename(schema);
+  invariant(typeof typename === "string" && !typename.startsWith("dxn:"), "Invalid typename", {
+    F: __dxlog_file,
+    L: 463,
+    S: void 0,
+    A: [
+      "typeof typename === 'string' && !typename.startsWith('dxn:')",
+      "'Invalid typename'"
+    ]
+  });
+  return typename;
+};
+var getVersion = (schema) => {
+  const version = getSchemaVersion(schema);
+  invariant(typeof version === "string" && version.match(/^\d+\.\d+\.\d+$/), "Invalid version", {
+    F: __dxlog_file,
+    L: 473,
+    S: void 0,
+    A: [
+      "typeof version === 'string' && version.match(/^\\d+\\.\\d+\\.\\d+$/)",
+      "'Invalid version'"
+    ]
+  });
+  return version;
+};
+var isMutable2 = isMutable;
+var getMeta = (schema) => {
+  return getTypeAnnotation(schema);
+};
+var Entity;
+
+export {
+  Obj,
+  object,
+  PersistentType,
+  Relation,
+  relation,
+  isObjectSchema,
+  isRelationSchema,
+  Ref2 as Ref,
+  getDXN,
+  getTypename,
+  getVersion,
+  isMutable2 as isMutable,
+  getMeta,
+  Entity,
+  Type_exports
+};
+//# sourceMappingURL=chunk-NRN3ZW2T.mjs.map

package/dist/lib/node-esm/chunk-NRN3ZW2T.mjs.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/Type.ts"],
+  "sourcesContent": ["//\n// Copyright 2025 DXOS.org\n//\n\nimport * as Schema from 'effect/Schema';\n\nimport { type EncodedReference } from '@dxos/echo-protocol';\nimport { invariant } from '@dxos/invariant';\nimport { type DXN, type ObjectId } from '@dxos/keys';\nimport { type ToMutable } from '@dxos/util';\n\nimport type * as Entity$ from './Entity';\nimport {\n  ANY_OBJECT_TYPENAME,\n  ANY_OBJECT_VERSION,\n  type ATTR_RELATION_SOURCE,\n  type ATTR_RELATION_TARGET,\n  type AnyEntity,\n  type AnyProperties,\n  EchoObjectSchema,\n  EchoRelationSchema,\n  type EchoRelationSchemaOptions,\n  EchoSchema,\n  EntityKind,\n  PersistentSchema,\n  Ref as Ref$,\n  type RefFn,\n  type RefSchema,\n  SchemaKindId,\n  type TypeAnnotation,\n  type TypeMeta,\n  getSchemaDXN,\n  getSchemaTypename,\n  getSchemaVersion,\n  getTypeAnnotation,\n  isMutable as isMutable$,\n  toEffectSchema,\n  toJsonSchema,\n} from './internal';\nimport type * as Relation$ from './Relation';\n\n// TODO(burdon): Remove toEffectSchema, toJsonSchema (moved to JsonSchema export).\nexport { toEffectSchema, toJsonSchema };\n\n/**\n * Returns all properties of an object or relation except for the id and kind.\n */\nexport type Properties<T = any> = Omit<T, 'id' | Entity$.KindId | Relation$.Source | Relation$.Target>;\n\n//\n// Internal types (not exported)\n//\n\n/**\n * Type that marks a schema as an ECHO schema.\n * The value indicates the entity kind (Object or Relation).\n */\ntype EchoSchemaKind<K extends EntityKind = EntityKind> = {\n  readonly [SchemaKindId]: K;\n};\n\n/**\n * JSON-encoded properties for objects.\n */\ninterface ObjJsonProps {\n  id: string;\n}\n\n/**\n * JSON-encoded properties for relations.\n */\ninterface RelationJsonProps {\n  id: string;\n  [ATTR_RELATION_SOURCE]: string;\n  [ATTR_RELATION_TARGET]: string;\n}\n\n//\n// Obj - Runtime schema for any ECHO object\n//\n\n// Internal type for the Obj schema constant.\n// NOTE: The `any` in the type intersection is intentional - it makes this type bidirectionally\n//   assignable with specific object types (e.g., Type.Obj can be assigned to/from Meeting.Meeting).\n//   This is needed because operation schemas erase type information.\n// TODO(wittjosiah): Consider alternatives to the `any` intersection hack:\n//   - Generic operation schemas that preserve input type in output\n//   - Branded types that specific schemas also carry\n//   - Accept the limitation and require explicit type narrowing at call sites\ntype ObjSchemaType = Schema.Schema<\n  any & AnyEntity & Entity$.OfKind<typeof Entity$.Kind.Object> & AnyProperties,\n  { id: string } & AnyProperties\n> &\n  EchoSchemaKind<EntityKind.Object> &\n  TypeMeta;\n\n// Internal schema definition.\n// NOTE: The EchoObjectSchema annotation is required for Type.Ref(Type.Obj) to work.\n//   The typename/version only satisfy ECHO schema machinery for reference targets.\nconst ObjSchema = Schema.Struct({\n  id: Schema.String,\n}).pipe(\n  Schema.extend(Schema.Record({ key: Schema.String, value: Schema.Unknown })),\n  EchoObjectSchema({ typename: ANY_OBJECT_TYPENAME, version: ANY_OBJECT_VERSION }),\n);\n\n/**\n * Runtime Effect schema for any ECHO object.\n * Use for validation, parsing, or as a reference target for collections.\n *\n * NOTE: `Schema.is(Type.Obj)` does STRUCTURAL validation only (checks for `id` field).\n * Use `Obj.isObject()` for proper ECHO instance type guards that check the KindId brand.\n *\n * @example\n * ```ts\n * // Structural type guard (accepts any object with id field)\n * if (Schema.is(Type.Obj)(unknownValue)) { ... }\n *\n * // ECHO instance type guard (checks KindId brand)\n * if (Obj.isObject(unknownValue)) { ... }\n *\n * // Reference to any object type\n * const Collection = Schema.Struct({\n *   objects: Schema.Array(Type.Ref(Type.Obj)),\n * }).pipe(Type.object({ typename: 'Collection', version: '0.1.0' }));\n * ```\n */\n// TODO(wittjosiah): Investigate if Schema.filter can validate KindId on ECHO instances.\n//   Effect Schema normalizes proxy objects to plain objects before calling filter predicates.\n//   Possible approaches: custom Schema.declare, AST manipulation, or upstream contribution.\nexport const Obj: ObjSchemaType = Object.assign(ObjSchema, {\n  [SchemaKindId]: (ObjSchema as any)[SchemaKindId],\n}) as unknown as ObjSchemaType;\n\n/**\n * TypeScript type for an ECHO object schema.\n * `T` is the instance type produced by the schema.\n * `Fields` is the optional struct fields type for introspection.\n *\n * @example\n * ```ts\n * const PersonSchema: Type.Obj<Person> = Schema.Struct({\n *   name: Schema.String,\n * }).pipe(Type.object({ typename: 'Person', version: '0.1.0' }));\n *\n * // Access fields for introspection:\n * Object.keys(PersonSchema.fields); // ['name']\n * ```\n */\nexport interface Obj<T = any, Fields extends Schema.Struct.Fields = Schema.Struct.Fields>\n  extends TypeMeta,\n    EchoSchemaKind<EntityKind.Object>,\n    Schema.AnnotableClass<\n      Obj<T, Fields>,\n      Entity$.OfKind<typeof Entity$.Kind.Object> & T,\n      Schema.Simplify<ObjJsonProps & ToMutable<T>>,\n      never\n    > {\n  /**\n   * The fields defined in the original struct schema.\n   * Allows accessing field definitions for introspection.\n   */\n  readonly fields: Fields;\n}\n\n/**\n * Structural base type for any ECHO object schema.\n * Accepts both static schemas (created with Type.object()) and EchoSchema.\n * NOTE: Does not include the brand symbol to avoid TS4053 declaration portability issues.\n * Use Type.isObjectSchema() for runtime type guards.\n */\ntype ObjectSchemaBase = Schema.Schema.AnyNoContext & {\n  readonly typename: string;\n  readonly version: string;\n};\n\nexport namespace Obj {\n  /**\n   * Type that represents any ECHO object schema.\n   * Accepts both static schemas (Type.object()) and mutable schemas (EchoSchema).\n   */\n  export type Any = ObjectSchemaBase;\n}\n\n/**\n * Factory function to create an ECHO object schema.\n * Adds object metadata annotations to an Effect schema.\n *\n * @example\n * ```ts\n * const Person = Schema.Struct({\n *   name: Schema.String,\n * }).pipe(Type.object({ typename: 'example.com/type/Person', version: '0.1.0' }));\n * ```\n */\nexport const object: {\n  (opts: TypeMeta): <Self extends Schema.Schema.Any>(self: Self) => Obj<Schema.Schema.Type<Self>>;\n} = EchoObjectSchema as any;\n\n//\n// PersistentType (Schema stored in database)\n//\n\nexport const PersistentType: Obj<PersistentSchema> = PersistentSchema as any;\n\nexport interface PersistentType extends Schema.Schema.Type<typeof PersistentType> {}\n\nexport { EchoSchema as RuntimeType };\n\n//\n// Relation - Runtime schema for any ECHO relation\n//\n\n// Internal type for the Relation schema constant.\ntype RelationSchemaType = Schema.Schema<\n  { id: ObjectId } & Record<string, unknown>,\n  { id: string } & Record<string, unknown>\n> &\n  EchoSchemaKind<EntityKind.Relation> &\n  TypeMeta;\n\n// Internal schema definition.\n// NOTE: The EchoRelationSchema annotation is required for Type.Ref(Type.Relation) to work.\n//   The typename/version/source/target only satisfy ECHO schema machinery for reference targets.\nconst RelationSchema = Schema.Struct({\n  id: Schema.String,\n}).pipe(\n  Schema.extend(Schema.Record({ key: Schema.String, value: Schema.Unknown })),\n  EchoRelationSchema({\n    typename: 'dxos.org/schema/AnyRelation',\n    version: '0.0.0',\n    source: ObjSchema,\n    target: ObjSchema,\n  }),\n);\n\n/**\n * Runtime Effect schema for any ECHO relation.\n * Use for validation, parsing, or as a reference target for collections.\n * A relation has `id`, source, and target fields plus any additional properties.\n *\n * NOTE: `Schema.is(Type.Relation)` does STRUCTURAL validation only (checks for `id` field).\n * Use `Relation.isRelation()` for proper ECHO instance type guards that check the KindId brand.\n *\n * @example\n * ```ts\n * // Structural type guard (accepts any object with id field)\n * if (Schema.is(Type.Relation)(unknownValue)) { ... }\n *\n * // ECHO instance type guard (checks KindId brand)\n * if (Relation.isRelation(unknownValue)) { ... }\n * ```\n */\nexport const Relation: RelationSchemaType = Object.assign(RelationSchema, {\n  [SchemaKindId]: (RelationSchema as any)[SchemaKindId],\n}) as unknown as RelationSchemaType;\n\n/**\n * TypeScript type for an ECHO relation schema.\n * `T` is the instance type produced by the schema (excluding source/target).\n * `Source` and `Target` are the endpoint types.\n * `Fields` is the optional struct fields type for introspection.\n */\nexport interface Relation<\n  T = any,\n  Source = any,\n  Target = any,\n  Fields extends Schema.Struct.Fields = Schema.Struct.Fields,\n> extends TypeMeta,\n    EchoSchemaKind<EntityKind.Relation>,\n    Schema.AnnotableClass<\n      Relation<T, Source, Target, Fields>,\n      Entity$.OfKind<typeof Entity$.Kind.Relation> & Relation.Endpoints<Source, Target> & T,\n      Schema.Simplify<RelationJsonProps & ToMutable<T>>,\n      never\n    > {\n  /**\n   * The fields defined in the original struct schema.\n   * Allows accessing field definitions for introspection.\n   */\n  readonly fields: Fields;\n}\n\n/**\n * Structural base type for any ECHO relation schema.\n * Accepts static schemas (created with Type.relation()).\n * NOTE: Does not include the brand symbol to avoid TS4053 declaration portability issues.\n * Use Type.isRelationSchema() for runtime type guards.\n */\ntype RelationSchemaBase = Schema.Schema.AnyNoContext & {\n  readonly typename: string;\n  readonly version: string;\n};\n\nexport namespace Relation {\n  /**\n   * Type that represents any ECHO relation schema.\n   * Accepts static schemas (Type.relation()).\n   */\n  export type Any = RelationSchemaBase;\n\n  /**\n   * Get relation source type.\n   */\n  export type Source<A> = A extends Relation.Endpoints<infer S, infer _T> ? S : never;\n\n  /**\n   * Get relation target type.\n   */\n  export type Target<A> = A extends Relation.Endpoints<infer _S, infer T> ? T : never;\n\n  export type Endpoints<Source, Target> = {\n    [Relation$.Source]: Source;\n    [Relation$.Target]: Target;\n  };\n}\n\n/**\n * Factory function to create an ECHO relation schema.\n * Adds relation metadata annotations to an Effect schema.\n *\n * @example\n * ```ts\n * const WorksFor = Schema.Struct({\n *   role: Schema.String,\n * }).pipe(Type.relation({\n *   typename: 'example.com/type/WorksFor',\n *   version: '0.1.0',\n *   source: Person,\n *   target: Company,\n * }));\n * ```\n */\nexport const relation: {\n  <SourceSchema extends Schema.Schema.AnyNoContext, TargetSchema extends Schema.Schema.AnyNoContext>(\n    opts: EchoRelationSchemaOptions<SourceSchema, TargetSchema>,\n  ): <Self extends Schema.Schema.Any>(\n    self: Self,\n  ) => Relation<Schema.Schema.Type<Self>, Schema.Schema.Type<SourceSchema>, Schema.Schema.Type<TargetSchema>>;\n} = EchoRelationSchema as any;\n\n//\n// Entity - Entity schema types (union of Object | Relation)\n//\n\nexport namespace Entity {\n  /**\n   * Runtime Effect schema for any ECHO entity (object or relation).\n   * Use for validation, parsing, or type guards on unknown values.\n   *\n   * @example\n   * ```ts\n   * if (Schema.is(Type.Entity.Any)(unknownValue)) {\n   *   // unknownValue is an ECHO entity\n   * }\n   * ```\n   */\n  export const Any: Schema.Schema<\n    { id: ObjectId } & Record<string, unknown>,\n    { id: string } & Record<string, unknown>\n  > = Schema.Union(Obj, Relation);\n\n  /**\n   * Type alias for any ECHO entity schema (object or relation).\n   * Use this in type annotations for schema parameters.\n   */\n  export type Any = Obj.Any | Relation.Any;\n}\n\n/**\n * Type guard to check if a schema is an object schema.\n * NOTE: This checks SCHEMAS, not instances. Use Obj.isObject for instances.\n */\nexport const isObjectSchema = (schema: Entity.Any): schema is Obj.Any => {\n  return (schema as any)[SchemaKindId] === EntityKind.Object;\n};\n\n/**\n * Type guard to check if a schema is a relation schema.\n * NOTE: This checks SCHEMAS, not instances. Use Relation.isRelation for instances.\n */\nexport const isRelationSchema = (schema: Entity.Any): schema is Relation.Any => {\n  return (schema as any)[SchemaKindId] === EntityKind.Relation;\n};\n\n//\n// Ref\n//\n// NOTE: `Type.Ref` vs `Ref.Ref`:\n// - `Type.Ref<T>` is the SCHEMA type - a schema that produces `Ref.Ref<T>` instances.\n// - `Ref.Ref<T>` is the INSTANCE type - the actual runtime ref object.\n//\n// Example:\n//   const taskRef: Ref.Ref<Task> = Ref.make(task);  // Instance\n//   const schema: Type.Ref<Task> = Type.Ref(Task);  // Schema\n//\n\n/**\n * Return type of the `Ref` schema constructor.\n *\n * This typedef avoids `TS4023` error (name from external module cannot be used named).\n * See Effect's note on interface types.\n */\nexport interface ref<TargetSchema extends Schema.Schema.Any> extends RefSchema<Schema.Schema.Type<TargetSchema>> {}\n\n/**\n * Factory function to create a Ref schema for the given target schema.\n * Use this in schema definitions to declare reference fields.\n *\n * @example\n * ```ts\n * const Task = Schema.Struct({\n *   assignee: Type.Ref(Person),  // Creates a Ref schema\n * }).pipe(Type.object({ typename: 'Task', version: '0.1.0' }));\n * ```\n */\nexport const Ref: RefFn = Ref$;\n\n/**\n * TypeScript type for a Ref schema.\n * This is the type of the SCHEMA itself, not the runtime ref instance.\n * For the instance type, use `Ref.Ref<T>` from the Ref module.\n *\n * @example\n * ```ts\n * // Schema type annotation (rarely needed, usually inferred):\n * const refSchema: Type.Ref<Task> = Type.Ref(Task);\n *\n * // Instance type annotation (use Ref.Ref instead):\n * const refInstance: Ref.Ref<Task> = Ref.make(task);\n * ```\n */\nexport interface Ref<T> extends Schema.SchemaClass<Ref$<T>, EncodedReference> {}\n\nexport namespace Ref {\n  /**\n   * Type that represents any Ref schema (with unknown target type).\n   * This is a schema type, not an instance type.\n   */\n  export type Any = Schema.Schema<Ref$<any>, EncodedReference>;\n}\n\n//\n// Schema utility functions\n//\n\n/**\n * Gets the full DXN of the schema.\n * Will include the version if it's a `type` DXN.\n * @example \"dxn:example.com/type/Person:0.1.0\"\n * @example \"dxn:echo:SSSSSSSSSS:XXXXXXXXXXXXX\"\n */\nexport const getDXN = (schema: Entity.Any): DXN | undefined => {\n  return getSchemaDXN(schema);\n};\n\n/**\n * @param schema - Schema to get the typename from.\n * @returns The typename of the schema. Example: `example.com/type/Person`.\n */\nexport const getTypename = (schema: Entity.Any): string => {\n  const typename = getSchemaTypename(schema);\n  invariant(typeof typename === 'string' && !typename.startsWith('dxn:'), 'Invalid typename');\n  return typename;\n};\n\n/**\n * Gets the version of the schema.\n * @example 0.1.0\n */\nexport const getVersion = (schema: Entity.Any): string => {\n  const version = getSchemaVersion(schema);\n  invariant(typeof version === 'string' && version.match(/^\\d+\\.\\d+\\.\\d+$/), 'Invalid version');\n  return version;\n};\n\n/**\n * @returns True if the schema is mutable.\n */\nexport const isMutable = isMutable$;\n\n/**\n * ECHO type metadata.\n */\nexport type Meta = TypeAnnotation;\n\n/**\n * Gets the meta data of the schema.\n */\nexport const getMeta = (schema: Entity.Any): Meta | undefined => {\n  return getTypeAnnotation(schema);\n};\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;;;;;aAAAA;EAAA;;;;;;mBAAAC;EAAA;;;;;;;AAIA,YAAYC,YAAY;AAGxB,SAASC,iBAAiB;A;AA4F1B,IAAMC,YAAmBC,cAAO;EAC9BC,IAAWC;AACb,CAAA,EAAGC,KACMC,cAAcC,cAAO;EAAEC,KAAYJ;EAAQK,OAAcC;AAAQ,CAAA,CAAA,GACxEC,iBAAiB;EAAEC,UAAUC;EAAqBC,SAASC;AAAmB,CAAA,CAAA;AA2BzE,IAAMC,MAAqBC,OAAOC,OAAOjB,WAAW;EACzD,CAACkB,YAAAA,GAAgBlB,UAAkBkB,YAAAA;AACrC,CAAA;AA+DO,IAAMC,SAETT;AAMG,IAAMU,iBAAwCC;AAqBrD,IAAMC,iBAAwBC,cAAO;EACnCC,IAAWC;AACb,CAAA,EAAGC,KACMC,cAAcC,cAAO;EAAEC,KAAYJ;EAAQK,OAAcC;AAAQ,CAAA,CAAA,GACxEC,mBAAmB;EACjBC,UAAU;EACVC,SAAS;EACTC,QAAQC;EACRC,QAAQD;AACV,CAAA,CAAA;AAoBK,IAAME,WAA+BC,OAAOC,OAAOlB,gBAAgB;EACxE,CAACmB,YAAAA,GAAgBnB,eAAuBmB,YAAAA;AAC1C,CAAA;AA8EO,IAAMC,WAMTV;UAMaW,SAAAA;UAYFC,MAGFC,aAAMC,KAAKR,QAAAA;AAOxB,GAtBiBK,WAAAA,SAAAA,CAAAA,EAAAA;AA4BV,IAAMI,iBAAiB,CAACC,WAAAA;AAC7B,SAAQA,OAAeP,YAAAA,MAAkBQ,WAAWV;AACtD;AAMO,IAAMW,mBAAmB,CAACF,WAAAA;AAC/B,SAAQA,OAAeP,YAAAA,MAAkBQ,WAAWX;AACtD;AAiCO,IAAMa,OAAaC;AAoCnB,IAAMC,SAAS,CAACL,WAAAA;AACrB,SAAOM,aAAaN,MAAAA;AACtB;AAMO,IAAMO,cAAc,CAACP,WAAAA;AAC1B,QAAMf,WAAWuB,kBAAkBR,MAAAA;AACnCS,YAAU,OAAOxB,aAAa,YAAY,CAACA,SAASyB,WAAW,MAAA,GAAS,oBAAA;;;;;;;;;AACxE,SAAOzB;AACT;AAMO,IAAM0B,aAAa,CAACX,WAAAA;AACzB,QAAMd,UAAU0B,iBAAiBZ,MAAAA;AACjCS,YAAU,OAAOvB,YAAY,YAAYA,QAAQ2B,MAAM,iBAAA,GAAoB,mBAAA;;;;;;;;;AAC3E,SAAO3B;AACT;AAKO,IAAM4B,aAAYC;AAUlB,IAAMC,UAAU,CAAChB,WAAAA;AACtB,SAAOiB,kBAAkBjB,MAAAA;AAC3B;;",
+  "names": ["Ref", "isMutable", "Schema", "invariant", "ObjSchema", "Struct", "id", "String", "pipe", "extend", "Record", "key", "value", "Unknown", "EchoObjectSchema", "typename", "ANY_OBJECT_TYPENAME", "version", "ANY_OBJECT_VERSION", "Obj", "Object", "assign", "SchemaKindId", "object", "PersistentType", "PersistentSchema", "RelationSchema", "Struct", "id", "String", "pipe", "extend", "Record", "key", "value", "Unknown", "EchoRelationSchema", "typename", "version", "source", "ObjSchema", "target", "Relation", "Object", "assign", "SchemaKindId", "relation", "Entity", "Any", "Union", "Obj", "isObjectSchema", "schema", "EntityKind", "isRelationSchema", "Ref", "Ref$", "getDXN", "getSchemaDXN", "getTypename", "getSchemaTypename", "invariant", "startsWith", "getVersion", "getSchemaVersion", "match", "isMutable", "isMutable$", "getMeta", "getTypeAnnotation"]
+}

package/dist/lib/node-esm/chunk-QLI2EIJ2.mjs

@@ -0,0 +1,41 @@
+import { createRequire } from 'node:module';const require = createRequire(import.meta.url);
+import {
+  Ref,
+  RefArray,
+  getSchemaReference
+} from "./chunk-LT3H4JOX.mjs";
+import {
+  __export
+} from "./chunk-HSLMI22Q.mjs";
+
+// src/Ref.ts
+var Ref_exports = {};
+__export(Ref_exports, {
+  Array: () => Array,
+  fromDXN: () => fromDXN,
+  isRef: () => isRef,
+  isRefType: () => isRefType,
+  make: () => make
+});
+import * as Option from "effect/Option";
+import * as SchemaAST from "effect/SchemaAST";
+var Array = RefArray;
+var isRef = Ref.isRef;
+var make = Ref.make;
+var fromDXN = Ref.fromDXN;
+var isRefType = (ast) => {
+  return SchemaAST.getAnnotation(ast, SchemaAST.JSONSchemaAnnotationId).pipe(Option.flatMap((jsonSchema) => "$id" in jsonSchema ? Option.some(jsonSchema) : Option.none()), Option.flatMap((jsonSchema) => {
+    const { typename } = getSchemaReference(jsonSchema) ?? {};
+    return typename ? Option.some(true) : Option.some(false);
+  }), Option.getOrElse(() => false));
+};
+
+export {
+  Array,
+  isRef,
+  make,
+  fromDXN,
+  isRefType,
+  Ref_exports
+};
+//# sourceMappingURL=chunk-QLI2EIJ2.mjs.map

package/dist/lib/node-esm/chunk-QLI2EIJ2.mjs.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/Ref.ts"],
+  "sourcesContent": ["//\n// Copyright 2025 DXOS.org\n//\n\nimport * as Option from 'effect/Option';\nimport * as SchemaAST from 'effect/SchemaAST';\n\nimport { Ref as Ref$, RefArray, type RefResolver } from './internal';\nimport { getSchemaReference } from './internal';\nimport type * as JsonSchema from './JsonSchema';\nimport type * as Obj from './Obj';\n\nexport type Ref<T> = Ref$<T>;\nexport type Unknown = Ref$<Obj.Unknown>;\n\nexport const Array = RefArray;\n\n/**\n * Extract reference target.\n */\nexport type Target<R extends Unknown> = R extends Ref$<infer T> ? T : never;\n\n/**\n * Reference resolver.\n */\nexport type Resolver = RefResolver;\n\nexport const isRef: (value: unknown) => value is Unknown = Ref$.isRef;\n\nexport const make = Ref$.make;\n\n// TODO(dmaretskyi): Consider just allowing `make` to accept DXN.\nexport const fromDXN = Ref$.fromDXN;\n\n// TODO(wittjosiah): Factor out?\nexport const isRefType = (ast: SchemaAST.AST): boolean => {\n  return SchemaAST.getAnnotation<JsonSchema.JsonSchema>(ast, SchemaAST.JSONSchemaAnnotationId).pipe(\n    Option.flatMap((jsonSchema) => ('$id' in jsonSchema ? Option.some(jsonSchema) : Option.none())),\n    Option.flatMap((jsonSchema) => {\n      const { typename } = getSchemaReference(jsonSchema) ?? {};\n      return typename ? Option.some(true) : Option.some(false);\n    }),\n    Option.getOrElse(() => false),\n  );\n};\n"],
+  "mappings": ";;;;;;;;;;;AAAA;;;;;;;;AAIA,YAAYA,YAAY;AACxB,YAAYC,eAAe;AAUpB,IAAMC,QAAQC;AAYd,IAAMC,QAA8CC,IAAKD;AAEzD,IAAME,OAAOD,IAAKC;AAGlB,IAAMC,UAAUF,IAAKE;AAGrB,IAAMC,YAAY,CAACC,QAAAA;AACxB,SAAiBC,wBAAqCD,KAAeE,gCAAsB,EAAEC,KACpFC,eAAQ,CAACC,eAAgB,SAASA,aAAoBC,YAAKD,UAAAA,IAAqBE,YAAI,CAAA,GACpFH,eAAQ,CAACC,eAAAA;AACd,UAAM,EAAEG,SAAQ,IAAKC,mBAAmBJ,UAAAA,KAAe,CAAC;AACxD,WAAOG,WAAkBF,YAAK,IAAA,IAAeA,YAAK,KAAA;EACpD,CAAA,GACOI,iBAAU,MAAM,KAAA,CAAA;AAE3B;",
+  "names": ["Option", "SchemaAST", "Array", "RefArray", "isRef", "Ref$", "make", "fromDXN", "isRefType", "ast", "getAnnotation", "JSONSchemaAnnotationId", "pipe", "flatMap", "jsonSchema", "some", "none", "typename", "getSchemaReference", "getOrElse"]
+}

package/dist/lib/node-esm/chunk-QYR67VBV.mjs

@@ -0,0 +1,288 @@
+import { createRequire } from 'node:module';const require = createRequire(import.meta.url);
+import {
+  isRef
+} from "./chunk-QLI2EIJ2.mjs";
+import {
+  getTypeDXNFromSpecifier
+} from "./chunk-YOLH5KS4.mjs";
+import {
+  __export
+} from "./chunk-HSLMI22Q.mjs";
+
+// src/Filter.ts
+var Filter_exports = {};
+__export(Filter_exports, {
+  and: () => and,
+  between: () => between,
+  contains: () => contains,
+  eq: () => eq,
+  everything: () => everything,
+  foreignKeys: () => foreignKeys,
+  fromAst: () => fromAst,
+  gt: () => gt,
+  gte: () => gte,
+  id: () => id,
+  in: () => in$,
+  is: () => is,
+  lt: () => lt,
+  lte: () => lte,
+  neq: () => neq,
+  not: () => not,
+  nothing: () => nothing,
+  or: () => or,
+  props: () => props,
+  tag: () => tag,
+  text: () => text,
+  type: () => type,
+  typeDXN: () => typeDXN,
+  typename: () => typename
+});
+import * as Match from "effect/Match";
+import * as Schema from "effect/Schema";
+import { assertArgument } from "@dxos/invariant";
+import { DXN, ObjectId } from "@dxos/keys";
+var FilterClass = class _FilterClass {
+  ast;
+  static variance = {};
+  constructor(ast) {
+    this.ast = ast;
+  }
+  "~Filter" = _FilterClass.variance;
+};
+var is = (value2) => {
+  return typeof value2 === "object" && value2 !== null && "~Filter" in value2;
+};
+var fromAst = (ast) => {
+  return new FilterClass(ast);
+};
+var everything = () => {
+  return new FilterClass({
+    type: "object",
+    typename: null,
+    props: {}
+  });
+};
+var nothing = () => {
+  return new FilterClass({
+    type: "not",
+    filter: {
+      type: "object",
+      typename: null,
+      props: {}
+    }
+  });
+};
+var id = (...ids) => {
+  assertArgument(ids.every((id2) => ObjectId.isValid(id2)), "ids", "ids must be valid");
+  if (ids.length === 0) {
+    return nothing();
+  }
+  return new FilterClass({
+    type: "object",
+    typename: null,
+    id: ids,
+    props: {}
+  });
+};
+var type = (schema, props2) => {
+  const dxn = getTypeDXNFromSpecifier(schema);
+  return new FilterClass({
+    type: "object",
+    typename: dxn.toString(),
+    ...propsFilterToAst(props2 ?? {})
+  });
+};
+var typename = (typename2) => {
+  assertArgument(!typename2.startsWith("dxn:"), "typename", "Typename must no be qualified");
+  return new FilterClass({
+    type: "object",
+    typename: DXN.fromTypename(typename2).toString(),
+    props: {}
+  });
+};
+var typeDXN = (dxn) => {
+  return new FilterClass({
+    type: "object",
+    typename: dxn.toString(),
+    props: {}
+  });
+};
+var tag = (tag2) => {
+  return new FilterClass({
+    type: "tag",
+    tag: tag2
+  });
+};
+var props = (props2) => {
+  return new FilterClass({
+    type: "object",
+    typename: null,
+    ...propsFilterToAst(props2)
+  });
+};
+var text = (text2, options) => {
+  return new FilterClass({
+    type: "text-search",
+    text: text2,
+    searchKind: options?.type
+  });
+};
+var foreignKeys = (schema, keys) => {
+  const dxn = getTypeDXNFromSpecifier(schema);
+  return new FilterClass({
+    type: "object",
+    typename: dxn.toString(),
+    props: {},
+    foreignKeys: keys
+  });
+};
+var eq = (value2) => {
+  if (!isRef(value2) && typeof value2 === "object" && value2 !== null) {
+    throw new TypeError("Cannot use object as a value for eq filter");
+  }
+  return new FilterClass({
+    type: "compare",
+    operator: "eq",
+    value: isRef(value2) ? value2.noInline().encode() : value2
+  });
+};
+var neq = (value2) => {
+  return new FilterClass({
+    type: "compare",
+    operator: "neq",
+    value: value2
+  });
+};
+var gt = (value2) => {
+  return new FilterClass({
+    type: "compare",
+    operator: "gt",
+    value: value2
+  });
+};
+var gte = (value2) => {
+  return new FilterClass({
+    type: "compare",
+    operator: "gte",
+    value: value2
+  });
+};
+var lt = (value2) => {
+  return new FilterClass({
+    type: "compare",
+    operator: "lt",
+    value: value2
+  });
+};
+var lte = (value2) => {
+  return new FilterClass({
+    type: "compare",
+    operator: "lte",
+    value: value2
+  });
+};
+var in$ = (...values) => {
+  return new FilterClass({
+    type: "in",
+    values
+  });
+};
+var contains = (value2) => {
+  return new FilterClass({
+    type: "contains",
+    value: value2
+  });
+};
+var between = (from, to) => {
+  return new FilterClass({
+    type: "range",
+    from,
+    to
+  });
+};
+var not = (filter) => {
+  return new FilterClass({
+    type: "not",
+    filter: filter.ast
+  });
+};
+var and = (...filters) => {
+  return new FilterClass({
+    type: "and",
+    filters: filters.map((f) => f.ast)
+  });
+};
+var or = (...filters) => {
+  return new FilterClass({
+    type: "or",
+    filters: filters.map((f) => f.ast)
+  });
+};
+var propsFilterToAst = (predicates) => {
+  let idFilter;
+  if ("id" in predicates) {
+    assertArgument(typeof predicates.id === "string" || Array.isArray(predicates.id), "predicates.id", "invalid id filter");
+    idFilter = typeof predicates.id === "string" ? [
+      predicates.id
+    ] : predicates.id;
+    Schema.Array(ObjectId).pipe(Schema.validateSync)(idFilter);
+  }
+  return {
+    id: idFilter,
+    props: Object.fromEntries(Object.entries(predicates).filter(([prop, _value]) => prop !== "id").map(([prop, predicate]) => [
+      prop,
+      processPredicate(predicate)
+    ]))
+  };
+};
+var processPredicate = (predicate) => {
+  return Match.value(predicate).pipe(
+    Match.withReturnType(),
+    Match.when(is, (predicate2) => predicate2.ast),
+    // TODO(wittjosiah): Add support for array predicates.
+    Match.when(Array.isArray, (_predicate) => {
+      throw new Error("Array predicates are not yet supported.");
+    }),
+    Match.when((predicate2) => !isRef(predicate2) && typeof predicate2 === "object" && predicate2 !== null, (predicate2) => {
+      const nestedProps = Object.fromEntries(Object.entries(predicate2).map(([key, value2]) => [
+        key,
+        processPredicate(value2)
+      ]));
+      return {
+        type: "object",
+        typename: null,
+        props: nestedProps
+      };
+    }),
+    Match.orElse((value2) => eq(value2).ast)
+  );
+};
+
+export {
+  is,
+  fromAst,
+  everything,
+  nothing,
+  id,
+  type,
+  typename,
+  typeDXN,
+  tag,
+  props,
+  text,
+  foreignKeys,
+  eq,
+  neq,
+  gt,
+  gte,
+  lt,
+  lte,
+  in$,
+  contains,
+  between,
+  not,
+  and,
+  or,
+  Filter_exports
+};
+//# sourceMappingURL=chunk-QYR67VBV.mjs.map