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

package/src/internal/Entity/type-kind.ts

@@ -0,0 +1,67 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+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, makeTypeJsonSchemaAnnotation } from '../Annotation';
+import { EntityKind } from '../common/types';
+import { toJsonSchema } from '../JsonSchema';
+import { type EchoTypeSchema, makeEchoTypeSchema } from './entity';
+
+/**
+ * Type-kind schema marker — produced by {@link EchoTypeKindSchema}.
+ *
+ * Distinguishes meta-schemas (entities of `EntityKind.Type`, such as the
+ * built-in `Type.Type` TypeSchema) from object and relation types.
+ */
+export type EchoTypeKindSchema<
+  Self extends Schema.Schema.Any,
+  Fields extends Schema.Struct.Fields = Schema.Struct.Fields,
+> = EchoTypeSchema<Self, {}, EntityKind.Type, Fields>;
+
+/**
+ * Pipeable that brands a schema as a type-kind ECHO entity. Mirrors
+ * {@link EchoObjectSchema} / {@link EchoRelationSchema}, but stamps the
+ * resulting entity with `[SchemaKindId]: EntityKind.Type` and a matching
+ * `TypeAnnotation.kind = 'type'` so meta-schemas surface uniformly through
+ * `Type.isTypeKindSchema`, `Filter.type`, etc.
+ */
+export const EchoTypeKindSchema: {
+  (
+    dxn: DXN.DXN,
+  ): <Self extends Schema.Schema.Any, Fields extends Schema.Struct.Fields = Schema.Struct.Fields>(
+    self: Self & { fields?: Fields },
+  ) => EchoTypeKindSchema<Self, Fields>;
+} = (dxn) => {
+  const typename = DXN.getName(dxn);
+  const version = DXN.getVersion(dxn);
+  invariant(version, `Type-kind schemas require a versioned DXN: ${dxn}`);
+
+  return <Self extends Schema.Schema.Any, Fields extends Schema.Struct.Fields = Schema.Struct.Fields>(
+    self: Self & { fields?: Fields },
+  ): EchoTypeKindSchema<Self, Fields> => {
+    invariant(SchemaAST.isTypeLiteral(self.ast), 'Schema must be a TypeLiteral.');
+
+    const fields = ((self as any).fields ?? {}) as Fields;
+
+    const schemaWithId = Schema.extend(self, Schema.Struct({ id: Schema.String }));
+    const ast = SchemaAST.annotations(schemaWithId.ast, {
+      ...self.ast.annotations,
+      [TypeAnnotationId]: { kind: EntityKind.Type, typename, version } satisfies TypeAnnotation,
+      [SchemaAST.JSONSchemaAnnotationId]: makeTypeJsonSchemaAnnotation({
+        kind: EntityKind.Type,
+        typename,
+        version,
+      }),
+    });
+
+    return makeEchoTypeSchema<Self, EntityKind.Type, Fields>(fields, ast, typename, version, EntityKind.Type, () =>
+      toJsonSchema(Schema.make(ast)),
+    );
+  };
+};

package/src/internal/Entity/type-uri.ts

@@ -0,0 +1,87 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+
+import { raise } from '@dxos/debug';
+import { assertArgument } from '@dxos/invariant';
+import { DXN, URI } from '@dxos/keys';
+
+import { getSchemaURI, getTypename } from '../Annotation';
+import { type AnyEntity, InstancePhantomId, KindId, TypeId, getStaticTypeSchema } from '../common/types';
+import { getUri as getUriFromEntity } from './api';
+
+/**
+ * @param input schema, `Type.Type` entity, or a typename string.
+ * @return type identifier URI — see {@link getSchemaURI}. For a typename string,
+ * always a DXN. For a `Type.Type` entity, the URI of the schema it declares,
+ * symmetric with what `Obj.make(typeEntity, ...)` stamps on `system.type`: a
+ * static declaration resolves to its typename DXN, a persisted entity to its
+ * local `echo:/<objectId>`.
+ */
+export const getTypeURIFromSpecifier = (input: Schema.Schema.All | AnyEntity | string): URI.URI => {
+  if (Schema.isSchema(input)) {
+    return getSchemaURI(input) ?? raise(new TypeError('Schema has no URI'));
+  }
+  if (typeof input === 'object' && input !== null && KindId in input) {
+    // `Type.Type` entity. Both in-memory and persisted forms expose the schema
+    // they declare via `StaticTypeSchemaSlot`, whose URI is exactly what
+    // `Obj.make` stamps on `system.type` — a static declaration carries
+    // `TypeAnnotation` (→ typename DXN), a persisted entity's rebuilt schema
+    // carries `TypeIdentifierAnnotation` (→ local `echo:/<objectId>`).
+    const schema = getStaticTypeSchema(input);
+    if (schema != null) {
+      return getSchemaURI(schema) ?? raise(new TypeError('Type entity has no URI'));
+    }
+    return getUriFromEntity(input as AnyEntity);
+  }
+  assertArgument(typeof input === 'string', 'input');
+  assertArgument(!input.startsWith('dxn:'), 'input');
+  return DXN.make(input);
+};
+
+/**
+ * Checks if the object is an instance of the schema.
+ * Only typename is compared, the schema version is ignored.
+ *
+ * The following cases are considered to mean that the object is an instance of the schema:
+ *  - Object was created with this exact schema.
+ *  - Object was created with a different version of this schema.
+ *  - Object was created with a different schema (maybe dynamic) that has the same typename.
+ */
+// TODO(burdon): Can we use `Schema.is`?
+export const isInstanceOf = <S>(
+  schemaOrType: S extends Schema.Schema.AnyNoContext ? S : Schema.Schema.AnyNoContext | AnyEntity,
+  object: any,
+): object is S extends Schema.Schema.AnyNoContext
+  ? Schema.Schema.Type<S>
+  : S extends { readonly [InstancePhantomId]?: infer A }
+    ? A
+    : unknown => {
+  if (object == null) {
+    return false;
+  }
+
+  const schemaURI = getTypeURIFromSpecifier(schemaOrType);
+
+  // `object` is arbitrary input — read TypeId directly (it may be missing on
+  // non-entities) rather than via `getTypeURI` which asserts the URI is set.
+  const type = (object as any)[TypeId];
+  if (URI.isURI(type) && type === schemaURI) {
+    return true;
+  }
+
+  const typename = getTypename(object);
+  if (!typename) {
+    return false;
+  }
+
+  if (!DXN.isDXN(schemaURI)) {
+    // EchoURI-based schema URI — no typename match possible.
+    return false;
+  }
+
+  const parsed = DXN.tryMake(schemaURI);
+  return parsed != null && DXN.getName(parsed) === typename;
+};

package/src/internal/Entity/util.ts

@@ -0,0 +1,34 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+
+import { assertArgument, invariant } from '@dxos/invariant';
+import { EchoURI, ObjectId } from '@dxos/keys';
+import { assumeType } from '@dxos/util';
+
+import { type InternalObjectProps, SelfURIId } from './model';
+
+/**
+ * Returns the EchoURI of an object.
+ * Normalizes any legacy `dxn:echo:` / `dxn:queue:` form stored in `SelfURIId`.
+ *
+ * @internal
+ */
+export const getObjectEchoUri = (object: any): EchoURI.EchoURI | undefined => {
+  invariant(!Schema.isSchema(object), 'schema not allowed in this function');
+  assertArgument(typeof object === 'object' && object != null, 'object', 'expected object');
+  assumeType<InternalObjectProps>(object);
+
+  if (object[SelfURIId]) {
+    invariant(EchoURI.isEchoURI(object[SelfURIId]), 'Invalid object model: invalid self dxn');
+    return EchoURI.parse(object[SelfURIId]);
+  }
+
+  if (!ObjectId.isValid(object.id)) {
+    throw new TypeError('Object id is not valid.');
+  }
+
+  return EchoURI.make({ objectId: object.id });
+};

package/src/internal/{api → Entity}/version.ts

@@ -4,8 +4,8 @@
 
 import { assertArgument } from '@dxos/invariant';
 
-import { ObjectVersionId } from '../entities';
-import { type AnyEntity, VersionTypeId } from '../types';
+import { type AnyEntity, VersionTypeId } from '../common/types';
+import { ObjectVersionId } from './model';
 
 /**
  * Represent entity version.

package/src/internal/{formats → Format}/date.test.ts

@@ -7,8 +7,7 @@ import { describe, expect, test } from 'vitest';
 
 import { log } from '@dxos/log';
 
-import { toJsonSchema } from '../json-schema';
-
+import { toJsonSchema } from '../JsonSchema';
 import {
   DateOnly,
   DateTime,

package/src/internal/{formats → Format}/date.ts

@@ -104,7 +104,6 @@ export const DateOnly = /* Schema.transformOrFail(Schema.String, SimpleDate, {
 }) */ Schema.String.pipe(
   FormatAnnotation.set(TypeFormat.Date),
   Schema.annotations({
-    title: 'Date',
     description: 'Valid date in ISO format',
   }),
 );
@@ -134,7 +133,6 @@ export const TimeOnly = /* Schema.transformOrFail(Schema.String, SimpleTime, {
 }) */ Schema.String.pipe(
   FormatAnnotation.set(TypeFormat.Time),
   Schema.annotations({
-    title: 'Time',
     description: 'Valid time in ISO format',
   }),
 );
@@ -179,7 +177,6 @@ export const DateTime = /* Schema.transformOrFail(Schema.String, SimpleDateTime,
 }) */ Schema.String.pipe(
   FormatAnnotation.set(TypeFormat.DateTime),
   Schema.annotations({
-    title: 'DateTime',
     description: 'Valid date and time in ISO format',
   }),
 );
@@ -191,7 +188,6 @@ export const DateTime = /* Schema.transformOrFail(Schema.String, SimpleDateTime,
 export const Duration = Schema.String.pipe(
   FormatAnnotation.set(TypeFormat.Duration),
   Schema.annotations({
-    title: 'Duration',
     description: 'Duration in ISO 8601 format',
     [SchemaAST.ExamplesAnnotationId]: ['1h', '3D'],
   }),

package/src/internal/{formats → Format}/format.test.ts

@@ -5,8 +5,7 @@
 import * as Schema from 'effect/Schema';
 import { describe, test } from 'vitest';
 
-import { toJsonSchema } from '../json-schema';
-
+import { toJsonSchema } from '../JsonSchema';
 import { Format } from './format';
 import { TypeEnum, TypeFormat, getTypeEnum } from './types';
 

package/src/internal/{formats → Format}/index.ts

@@ -2,11 +2,10 @@
 // Copyright 2025 DXOS.org
 //
 
-export type { SimpleDate, SimpleDateTime, SimpleTime } from './date';
+export * from './date';
+export * from './format';
 export { CurrencyAnnotationId, DecimalPrecision, Currency } from './number';
 export { GeoPoint, GeoLocation } from './object';
-
-export * from './format';
 export * from './select';
 export * from './string';
 export * from './types';

package/src/internal/{formats → Format}/types.ts

@@ -7,8 +7,8 @@ import type * as JSONSchema from 'effect/JSONSchema';
 import * as Option from 'effect/Option';
 import * as SchemaAST from 'effect/SchemaAST';
 
-import { createAnnotationHelper } from '../annotations';
-import { type JsonSchemaType } from '../json-schema';
+import { createAnnotationHelper } from '../Annotation';
+import { type JsonSchemaType } from '../JsonSchema';
 
 // TODO(burdon): Rename PropertyType.
 export type ScalarType =

package/src/internal/{json-schema → JsonSchema}/annotations.ts

@@ -4,9 +4,9 @@
 
 import * as SchemaAST from 'effect/SchemaAST';
 
-import { GeneratorAnnotationId, LabelAnnotationId, PropertyMetaAnnotationId } from '../annotations';
-import { CurrencyAnnotationId, FormatAnnotationId } from '../formats';
-import { type JsonSchemaEchoAnnotations, type JsonSchemaType } from '../json-schema';
+import { GeneratorAnnotationId, LabelAnnotationId, PropertyMetaAnnotationId } from '../Annotation';
+import { CurrencyAnnotationId, FormatAnnotationId } from '../Format';
+import { type JsonSchemaEchoAnnotations, type JsonSchemaType } from '../JsonSchema';
 
 //
 // This file configures annotations for JSON encoding/decoding.

package/src/internal/{json-schema → JsonSchema}/json-schema-type.ts

@@ -6,9 +6,9 @@ import * as Schema from 'effect/Schema';
 
 import { JsonPath, type JsonProp } from '@dxos/effect';
 
-import { FormatAnnotation, TypeFormat } from '../formats';
-import { type Mutable } from '../proxy';
-import { EntityKindSchema } from '../types';
+import { type Mutable } from '../common/proxy';
+import { EntityKindSchema } from '../common/types';
+import { FormatAnnotation, TypeFormat } from '../Format';
 
 //
 // JSON Schema
@@ -119,7 +119,7 @@ const _JsonSchemaType = Schema.Struct({
    * Typename of this schema.
    * Only on schema representing an ECHO object.
    *
-   * @example 'example.com/type/MyType'
+   * @example 'com.example.type.my-type'
    */
   typename: Schema.optional(Schema.String),