@dxos/echo 0.8.4-main.a4bbb77 → 0.8.4-main.abd8ff62ef

package/src/Ref.ts

@@ -2,28 +2,97 @@
 // Copyright 2025 DXOS.org
 //
 
-import * as EchoSchema from '@dxos/echo-schema';
+// @import-as-namespace
 
+import * as Option from 'effect/Option';
+import type * as Schema from 'effect/Schema';
+import * as SchemaAST from 'effect/SchemaAST';
+
+import type * as Entity from './Entity';
+import * as refInternal from './internal/Ref';
+import type * as JsonSchema from './JsonSchema';
 import type * as Obj from './Obj';
 
-export type Ref<T> = EchoSchema.Ref<T>;
-export type Any = EchoSchema.Ref<Obj.Any>;
+/**
+ * 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>;
+
+/**
+ * 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.object({ typename: 'Task', version: '0.1.0' }));
+ * ```
+ */
+export const Ref: <S extends Schema.Schema.Any>(schema: S) => RefSchema<Schema.Schema.Type<S>> = refInternal.Ref;
+
+export const Array = refInternal.RefArray;
 
-export const Array = EchoSchema.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 Any = EchoSchema.Ref.isRef;
+export const isRef: (value: unknown) => value is Unknown = refInternal.Ref.isRef;
 
-export const make = EchoSchema.Ref.make;
+export const make = refInternal.Ref.make;
 
 // TODO(dmaretskyi): Consider just allowing `make` to accept DXN.
-export const fromDXN = EchoSchema.Ref.fromDXN;
+export const fromDXN = refInternal.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);
+
+      // getSourceDXN - works with both.
+      expect(Relation.getSourceDXN(rel)).toBeDefined();
+      expect(Relation.getSourceDXN(snapshot)).toBeDefined();
+
+      // getTargetDXN - works with both.
+      expect(Relation.getTargetDXN(rel)).toBeDefined();
+      expect(Relation.getTargetDXN(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.getDXN(rel)).toBeDefined();
+      expect(Relation.getDXN(snapshot)).toBeDefined();
+
+      // getTypename - works with both.
+      expect(Relation.getTypename(rel)).toBe('com.example.type.has-manager');
+      expect(Relation.getTypename(snapshot)).toBe('com.example.type.has-manager');
+
+      // 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();
+    });
+  });
+});