@dxos/echo 0.8.4-staging.ac66bdf99f → 0.9.1-main.c7dcc2e112

package/src/internal/Ref/utils.ts

@@ -0,0 +1,45 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import type * as Atom from '@effect-atom/atom/Atom';
+
+import type { Ref } from './ref';
+
+/**
+ * Internal helper for loading ref targets in atoms.
+ * Handles the common pattern of checking for loaded target and triggering async load.
+ */
+export const loadRefTarget = <T, R>(
+  ref: Ref<T>,
+  get: Atom.Context,
+  onTargetAvailable: (target: T) => R,
+): R | undefined => {
+  // Accessing `ref.target` registers a resolution callback when the target is
+  // not yet loaded, so resolution can be observed via `ref.onResolved` below.
+  const currentTarget = ref.target;
+  if (currentTarget) {
+    return onTargetAvailable(currentTarget);
+  }
+
+  // Subscribe to the ref's resolution event in case the target loads later.
+  const unsubscribe = ref.onResolved(() => {
+    const target = ref.target;
+    if (target) {
+      get.setSelf(onTargetAvailable(target));
+    }
+  });
+  get.addFinalizer(unsubscribe);
+
+  // Also try async load (e.g. for objects that need disk loading).
+  void ref
+    .load()
+    .then((loadedTarget) => {
+      get.setSelf(onTargetAvailable(loadedTarget));
+    })
+    .catch(() => {
+      // Loading failed; the resolution subscription above will pick up cross-client updates.
+    });
+
+  return undefined;
+};

package/src/internal/Type/compose.test.ts

@@ -5,6 +5,8 @@
 import * as Schema from 'effect/Schema';
 import { describe, test } from 'vitest';
 
+import { DXN } from '@dxos/keys';
+
 import { FieldPath } from '../Annotation';
 import { EchoObjectSchema } from '../Entity';
 import { FormatAnnotation, TypeFormat } from '../Format';
@@ -16,7 +18,7 @@ describe('schema composition', () => {
     const BaseType = Schema.Struct({
       name: Schema.String,
       email: Schema.String,
-    }).pipe(EchoObjectSchema({ typename: 'com.example.person', version: '0.1.0' }));
+    }).pipe(EchoObjectSchema(DXN.make('com.example.person', '0.1.0')));
 
     const OverlaySchema = Schema.Struct({
       email: Schema.String.pipe(FieldPath('$.email'), FormatAnnotation.set(TypeFormat.Email)),

package/src/internal/Type/index.ts

@@ -2,6 +2,5 @@
 // Copyright 2024 DXOS.org
 //
 
-export * from './echo-schema';
 export * from './manipulation';
-export * from './persistent-schema';
+export * from './type-schema';

package/src/internal/Type/manipulation.ts

@@ -6,9 +6,6 @@ import * as Schema from 'effect/Schema';
 import * as SchemaAST from 'effect/SchemaAST';
 
 import { invariant } from '@dxos/invariant';
-import { DXN } from '@dxos/keys';
-
-import { type TypeAnnotation, TypeAnnotationId, TypeIdentifierAnnotationId } from '../Annotation';
 
 // TODO(ZaymonFC): Do this one at a time. This might be dangerous.
 export const addFieldsToSchema = (
@@ -68,25 +65,3 @@ export const updateFieldNameInSchema = (
     ),
   );
 };
-
-export const setTypenameInSchema = (
-  schema: Schema.Schema.AnyNoContext,
-  typename: string,
-): Schema.Schema.AnyNoContext => {
-  const existingAnnotation = schema.ast.annotations[TypeAnnotationId] as TypeAnnotation;
-  invariant(existingAnnotation, `Missing ${String(TypeAnnotationId)}`);
-
-  return schema.annotations({
-    ...schema.ast.annotations,
-    [TypeAnnotationId]: {
-      kind: existingAnnotation.kind,
-      typename,
-      version: existingAnnotation.version,
-    } satisfies TypeAnnotation,
-    [SchemaAST.JSONSchemaAnnotationId]: {
-      ...(schema.ast.annotations[SchemaAST.JSONSchemaAnnotationId] ?? {}),
-      $id: schema.ast.annotations[TypeIdentifierAnnotationId] ?? DXN.fromTypename(typename).toString(),
-      typename,
-    },
-  });
-};

package/src/internal/Type/type-schema.ts

@@ -0,0 +1,60 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+
+import { IconAnnotation, LabelAnnotation } from '../Annotation';
+import { EntityKind, KindId, SchemaKindId, StaticTypeSchemaSlot } from '../common/types';
+import { EchoTypeKindSchema, TypeMetaSchemaDXN } from '../Entity';
+import { JsonSchemaType } from '../JsonSchema';
+
+/**
+ * Raw struct backing {@link TypeSchema}. Exposed only so `TypeSchema`
+ * (the TS type) can derive its data fields via `Schema.Schema.Type<typeof ...>`;
+ * runtime callers should use {@link TypeSchema} (the piped, branded entity).
+ *
+ * `typename` and `version` are NOT data fields — they live in `EntityMeta.key` /
+ * `EntityMeta.version` (the canonical registry-provenance pair, queryable via
+ * `Filter.key(...)`). The same `jsonSchema` payload also embeds them so a
+ * standalone JSON-Schema export remains self-describing, but the schema-registry
+ * reads/writes them through meta.
+ */
+const TypeSchemaStruct = Schema.Struct({
+  name: Schema.optional(Schema.String),
+  jsonSchema: JsonSchemaType,
+});
+
+/**
+ * Persistent representation of a schema.
+ */
+export const TypeSchema = TypeSchemaStruct.pipe(
+  LabelAnnotation.set(['name']),
+  IconAnnotation.set({
+    icon: 'ph--database--regular',
+    hue: 'green',
+  }),
+  EchoTypeKindSchema(TypeMetaSchemaDXN),
+);
+
+/**
+ * Persistent representation of a schema — the runtime shape that
+ * `db.addType(Type.makeObjectFromJsonSchema(...))` produces
+ * and `Filter.type(Type.Type).run()` returns.
+ *
+ * Structurally identical to a static `Type.Type` entity: the entity-handler's
+ * `get` trap exposes `[SchemaKindId]` (derived from `system.kind` and
+ * `data.jsonSchema.entityKind`) and rebuilds `[StaticTypeSchemaSlot]` lazily
+ * from `jsonSchema`, so a persisted instance satisfies the public `Type<A>`
+ * interface without casting.
+ */
+export type TypeSchema = Schema.Schema.Type<typeof TypeSchemaStruct> & {
+  /** Object identifier — injected by `EchoTypeKindSchema` and stamped at construction. */
+  readonly id: string;
+  /** Entity-kind discriminator (object/relation/type) carried on every entity instance. */
+  readonly [KindId]: EntityKind.Type;
+  /** Kind of schema described by this meta-instance — always `EntityKind.Type` for `Type.Type` itself. */
+  readonly [SchemaKindId]: EntityKind.Type;
+  /** Effect Schema rebuilt lazily from `jsonSchema`; satisfies `Type.getSchema(...)` without an extra cast. */
+  readonly [StaticTypeSchemaSlot]: Schema.Schema.AnyNoContext;
+};

package/src/internal/common/README.md

@@ -7,7 +7,7 @@
 - [x] Unify FOUR different nests of test schema.
 - [x] Remove @deprecated from internal methods and mark @internal (e.g., getSchemaDXN).
   - NOTE: Internal methods should not use the import \* from Obj/Type APIs.
-- [x] import ObjectId => @dxos/keys
+- [x] import EntityId => @dxos/keys
 - [x] Entity.Any = Obj.Any | Relation.Any
   - NOTE: Relation does not extend (in not polymorphic with) Obj.
 - [x] import LabelAnnotation => Annotation.LabelAnnotation
@@ -99,4 +99,4 @@
 - [ ] ReactiveObject should specify id property? Reconcile AnyProperties, ReactiveObject, HasId, WithId, etc.
 - [ ] Can we us S.is(MyType) to detect objects with our types system? (Branding?)
 - [ ] Type.Expando doesn't work with AtomQuery result type (have to use Obj.Any instead).
-- [ ] Obj.Any doesn't work with Obj.change callback types (have to use `any` for the mutable parameter).
+- [ ] Obj.Any doesn't work with Obj.update callback types (have to use `any` for the mutable parameter).

package/src/internal/common/api/meta.ts

@@ -6,18 +6,21 @@ import type { ForeignKey } from '@dxos/echo-protocol';
 import { assertArgument, invariant } from '@dxos/invariant';
 import type { DeepReadonly } from '@dxos/util';
 
+import type * as Tag from '../../../Tag';
+import type { Ref } from '../../Ref/ref';
 import { type Mutable } from '../proxy';
-import { type AnyProperties, type ObjectMeta, getMeta as getMeta$ } from '../types';
+import { type AnyProperties } from '../types';
+import { type EntityMeta, getMeta as getMeta$ } from '../types/meta';
 
 /**
- * Deeply read-only version of ObjectMeta.
+ * Deeply read-only version of EntityMeta.
  */
-export type ReadonlyMeta = DeepReadonly<ObjectMeta>;
+export type ReadonlyMeta = DeepReadonly<EntityMeta>;
 
 /**
  * Mutable meta type received in meta mutation callbacks.
  */
-export type Meta = Mutable<ObjectMeta>;
+export type Meta = Mutable<EntityMeta>;
 
 /**
  * Get the metadata for an entity with validation.
@@ -48,7 +51,7 @@ export const getKeys = (entity: AnyProperties, source: string): ForeignKey[] =>
 
 /**
  * Delete all keys from the entity for the specified source.
- * Must be called within an Obj.change or Relation.change callback.
+ * Must be called within an Obj.update or Relation.update callback.
  */
 export const deleteKeys = (entity: Mutable<AnyProperties>, source: string) => {
   const meta = getMetaChecked(entity);
@@ -61,26 +64,25 @@ export const deleteKeys = (entity: Mutable<AnyProperties>, source: string) => {
 };
 
 /**
- * Add a tag to the entity.
- * Must be called within an Obj.change or Relation.change callback.
+ * Add a tag (a reference to a {@link Tag} object) to the entity. Idempotent.
+ * Must be called within an Obj.update or Relation.update callback.
  */
-export const addTag = (entity: Mutable<AnyProperties>, tag: string) => {
+export const addTag = (entity: Mutable<AnyProperties>, tag: Ref<Tag.Tag>) => {
   const meta = getMetaChecked(entity);
-  meta.tags ??= [];
-  meta.tags.push(tag);
+  // Two refs to the same target are not `===`; dedupe by URI.
+  if (!meta.tags.some((existing) => existing.uri === tag.uri)) {
+    meta.tags.push(tag);
+  }
 };
 
 /**
- * Remove a tag from the entity.
- * Must be called within an Obj.change or Relation.change callback.
+ * Remove a tag (a reference to a {@link Tag} object) from the entity. No-op when not present.
+ * Must be called within an Obj.update or Relation.update callback.
  */
-export const removeTag = (entity: Mutable<AnyProperties>, tag: string) => {
+export const removeTag = (entity: Mutable<AnyProperties>, tag: Ref<Tag.Tag>) => {
   const meta = getMetaChecked(entity);
-  if (!meta.tags) {
-    return;
-  }
   for (let i = 0; i < meta.tags.length; i++) {
-    if (meta.tags[i] === tag) {
+    if (meta.tags[i].uri === tag.uri) {
       meta.tags.splice(i, 1);
       i--;
     }

package/src/internal/common/proxy/change-context.ts

@@ -35,7 +35,7 @@ const pendingOwnerNotifications = new Set<object>();
 /**
  * Enter a change context for the given key.
  * While in a change context, mutations are allowed on the associated object.
- * Nested Obj.change calls are not supported.
+ * Nested Obj.update calls are not supported.
  *
  * @param key - The key to enter the change context for (target object or ObjectCore).
  * @returns A cleanup function that exits the change context.