@dxos/echo 0.8.4-main.ead640a → 0.8.4-main.effb148878

package/src/Ref.ts

@@ -2,27 +2,115 @@
 // Copyright 2025 DXOS.org
 //
 
-import * as EchoSchema from './internal';
+// @import-as-namespace
+
+import * as Option from 'effect/Option';
+import type * as Schema from 'effect/Schema';
+import * as SchemaAST from 'effect/SchemaAST';
+
+import { type URI } from '@dxos/keys';
+
+import type * as Entity from './Entity';
+import type * as internal from './internal';
+import * as refInternal from './internal/Ref';
+import type * as JsonSchema from './JsonSchema';
 import type * as Obj from './Obj';
+// eslint-disable-next-line @dxos/rules/import-as-namespace
+import type * as TypeNs from './Type';
+
+/**
+ * Instance type for a reference.
+ *
+ * Reference can point to any object or relation.
+ * References are lazy loaded.
+ *
+ * `ref.dxn` is the DXN of the referenced object.
+ *
+ * @example
+ * ```ts
+ * const taskRef: Ref<Task> = Ref.make(task);
+ *
+ * await taskRef.load(); // Returns Promise<Task>
+ * yield* Database.load(taskRef); // Effectful version.
+ *
+ * database.makeRef(dxn); // Create a ref from a DXN.
+ * ```
+ */
+export type Ref<T> = refInternal.Ref<T>;
+export type Unknown = refInternal.Ref<Obj.Unknown>;
 
-export type Ref<T> = EchoSchema.Ref<T>;
-export type Any = EchoSchema.Ref<Obj.Any>;
+/**
+ * Factory function to create a Ref schema for the given target schema.
+ * Use this in schema definitions to declare reference fields.
+ *
+ * @example
+ * ```ts
+ * const Task = Schema.Struct({
+ *   assignee: Ref.Ref(Person),  // Creates a Ref schema
+ * }).pipe(Type.makeObject(DXN.make('com.example.type.task', '0.1.0')));
+ * ```
+ */
+export const Ref: {
+  <S extends TypeNs.AnyObj | TypeNs.AnyRelation>(type: S): RefSchema<TypeNs.InstanceType<S> & Obj.Unknown>;
 
-export const Array = EchoSchema.RefArray;
+  // `Type.Type` entities (the meta-schema kind) can be referenced too — e.g. a
+  // trigger that points to a stored function/workflow definition.
+  <T extends TypeNs.Type<any>>(type: T): RefSchema<TypeNs.InstanceType<T>>;
+
+  // Schema-side overload for the well-known "any object" / "any relation" schemas.
+  // Other raw `Schema.Schema` values are intentionally rejected — callers should
+  // pass a `Type.Type` entity instead.
+  <S extends internal.UnknownTypeSchema<any, any>>(schema: S): RefSchema<Schema.Schema.Type<S> & Obj.Unknown>;
+} = refInternal.Ref as any;
+
+export const Array = refInternal.RefArray;
+
+/**
+ * TypeScript type for a Ref schema.
+ * This is the type of the SCHEMA itself, not the runtime ref instance.
+ * For the instance type, use `Ref.Ref<T>` from the Ref module.
+ *
+ * @example
+ * ```ts
+ * // Schema type annotation (rarely needed, usually inferred):
+ * const refSchema: Ref.RefSchema<typeof Task> = Ref.Ref(Task);
+ *
+ * // Instance type annotation (use Ref.Ref instead):
+ * const refInstance: Ref.Ref<Task> = Ref.make(task);
+ * ```
+ */
+// TODO(dmaretskyi): Investigate if we can remove this type.
+//                   Post DX-836 it will become just `Schema.Schema<Ref.Ref<T>>`.
+//                   NOTE: This could be Type.Ref<T> instead, but since it going to be removed, it's better to keep it here, self-contained.
+export interface RefSchema<T extends Entity.Unknown> extends refInternal.RefSchema<T> {}
 
 /**
  * Extract reference target.
  */
-export type Target<R extends Any> = R extends EchoSchema.Ref<infer T> ? T : never;
+export type Target<R extends Unknown> = R extends refInternal.Ref<infer T> ? T : never;
 
 /**
  * Reference resolver.
  */
-export type Resolver = EchoSchema.RefResolver;
+export type Resolver = refInternal.RefResolver;
+
+export const isRef: (value: unknown) => value is Unknown = refInternal.Ref.isRef;
+
+export const make = refInternal.Ref.make;
 
-export const isRef: (value: unknown) => value is Any = EchoSchema.Ref.isRef;
+// TODO(dmaretskyi): Consider just allowing `make` to accept URI.
+export const fromURI = (uri: URI.URI): refInternal.Ref<any> => refInternal.Ref.fromURI(uri);
 
-export const make = EchoSchema.Ref.make;
+export const hasObjectId = refInternal.Ref.hasObjectId;
 
-// TODO(dmaretskyi): Consider just allowing `make` to accept DXN.
-export const fromDXN = EchoSchema.Ref.fromDXN;
+// TODO(wittjosiah): Factor out?
+export const isRefType = (ast: SchemaAST.AST): boolean => {
+  return SchemaAST.getAnnotation<JsonSchema.JsonSchema>(ast, SchemaAST.JSONSchemaAnnotationId).pipe(
+    Option.flatMap((jsonSchema) => ('$id' in jsonSchema ? Option.some(jsonSchema) : Option.none())),
+    Option.flatMap((jsonSchema) => {
+      const { typename } = refInternal.getSchemaReference(jsonSchema) ?? {};
+      return typename ? Option.some(true) : Option.some(false);
+    }),
+    Option.getOrElse(() => false),
+  );
+};

package/src/Relation.test.ts

@@ -0,0 +1,88 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, test } from 'vitest';
+
+import * as Entity from './Entity';
+import { SnapshotKindId } from './internal';
+import * as Obj from './Obj';
+import * as Relation from './Relation';
+import { TestSchema } from './testing';
+
+describe('Relation', () => {
+  describe('Snapshot', () => {
+    test('getSnapshot returns an immutable snapshot with SnapshotKindId', ({ expect }) => {
+      const obj1 = Obj.make(TestSchema.Person, { name: 'Alice' });
+      const obj2 = Obj.make(TestSchema.Person, { name: 'Bob' });
+      const rel = Relation.make(TestSchema.HasManager, {
+        [Relation.Source]: obj1,
+        [Relation.Target]: obj2,
+      });
+      const snapshot = Relation.getSnapshot(rel);
+
+      // Snapshot has SnapshotKindId, not KindId.
+      expect(snapshot[SnapshotKindId]).toBe(Entity.Kind.Relation);
+      expect((snapshot as any)[Entity.KindId]).toBeUndefined();
+
+      expect(Relation.isSnapshot(snapshot)).toBe(true);
+      expect(Obj.isSnapshot(snapshot)).toBe(false);
+
+      expect(Relation.getSource(snapshot)).toEqual(obj1);
+      expect(Relation.getTarget(snapshot)).toEqual(obj2);
+
+      // Snapshot has same id.
+      expect(snapshot.id).toBe(rel.id);
+    });
+
+    test('read-only helpers work with both reactive and snapshot', ({ expect }) => {
+      const obj1 = Obj.make(TestSchema.Person, { name: 'Alice' });
+      const obj2 = Obj.make(TestSchema.Person, { name: 'Bob' });
+      const rel = Relation.make(TestSchema.HasManager, {
+        [Relation.Source]: obj1,
+        [Relation.Target]: obj2,
+      });
+      const snapshot = Relation.getSnapshot(rel);
+
+      // getSourceURI - works with both.
+      expect(Relation.getSourceURI(rel)).toBeDefined();
+      expect(Relation.getSourceURI(snapshot)).toBeDefined();
+
+      // getTargetURI - works with both.
+      expect(Relation.getTargetURI(rel)).toBeDefined();
+      expect(Relation.getTargetURI(snapshot)).toBeDefined();
+
+      // getSource - works with both.
+      expect(Relation.getSource(rel)).toBeDefined();
+      expect(Relation.getSource(snapshot)).toBeDefined();
+
+      // getTarget - works with both.
+      expect(Relation.getTarget(rel)).toBeDefined();
+      expect(Relation.getTarget(snapshot)).toBeDefined();
+
+      // getDXN - works with both.
+      expect(Relation.getURI(rel)).toBeDefined();
+      expect(Relation.getURI(snapshot)).toBeDefined();
+
+      // getTypename - works with both.
+      expect(Relation.getTypename(rel)).toBe('com.example.type.hasManager');
+      expect(Relation.getTypename(snapshot)).toBe('com.example.type.hasManager');
+
+      // getMeta - works with both.
+      expect(Relation.getMeta(rel)).toBeDefined();
+      expect(Relation.getMeta(snapshot)).toBeDefined();
+
+      // isDeleted - works with both.
+      expect(Relation.isDeleted(rel)).toBe(false);
+      expect(Relation.isDeleted(snapshot)).toBe(false);
+
+      // version - works with both.
+      expect(Relation.version(rel)).toBeDefined();
+      expect(Relation.version(snapshot)).toBeDefined();
+
+      // toJSON - works with both.
+      expect(Relation.toJSON(rel)).toBeDefined();
+      expect(Relation.toJSON(snapshot)).toBeDefined();
+    });
+  });
+});