@dxos/echo 0.8.4-main.fffef41 → 0.8.4-staging.60fe92afc8

package/src/internal/Annotation/entity-dictionary.ts

@@ -0,0 +1,74 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Option from 'effect/Option';
+
+import { deepMapValues } from '@dxos/util';
+
+import type * as Annotation from '../../Annotation';
+import type * as Entity from '../../Entity';
+import { getMetaChecked } from '../common/api/meta';
+import { type Mutable } from '../common/proxy/reactive';
+import { getDatabase } from '../Entity/api';
+import { isEntity, isSnapshot } from '../Entity/guard';
+import { Ref, getRefSavedTarget } from '../Ref';
+import { getDictionary, setDictionary } from './dictionary';
+
+/**
+ * Get the value of an annotation from an entity instance or snapshot.
+ */
+export const get = <T>(
+  target: Entity.Unknown | Entity.Snapshot,
+  annotation: Annotation.Annotation<T>,
+): Option.Option<T> => {
+  if (isEntity(target) || isSnapshot(target)) {
+    const meta = getMetaChecked(target);
+    return getDictionary(meta.annotations, annotation);
+  } else {
+    throw new TypeError('Target is not an annotation target.');
+  }
+};
+
+/**
+ * Set the value of an annotation on an entity instance.
+ * Must be called with a mutable entity — i.e. inside an `Obj.update` callback.
+ */
+export const set = <T>(target: Mutable<Entity.Unknown>, annotation: Annotation.Annotation<T>, value: T): void => {
+  if (isEntity(target)) {
+    const meta = getMetaChecked(target);
+    // Persist any unsaved Ref targets in the value into the entity's database so
+    // the encoded DXN resolves on read. This mirrors normal property assignment,
+    // where the reactive proxy links unsaved ref targets via `createRef` →
+    // `database.add`. `setDictionary` pre-encodes the value (`Schema.encodeSync`),
+    // so the live Ref never reaches the proxy's link handling and would otherwise
+    // be stored as a dangling reference.
+    persistRefTargets(target, value);
+    setDictionary(meta.annotations, annotation, value);
+  } else {
+    throw new TypeError('Target is not an annotation target.');
+  }
+};
+
+/**
+ * Add any unsaved Ref targets found in `value` to the host entity's database, matching the
+ * auto-persistence applied to refs assigned to ordinary entity properties. Refs whose target
+ * already lives in a database (the host's or a foreign one) are left untouched.
+ */
+const persistRefTargets = (host: Entity.Unknown, value: unknown): void => {
+  const database = getDatabase(host);
+  if (database == null) {
+    return;
+  }
+
+  deepMapValues(value, (current, recurse) => {
+    if (Ref.isRef(current)) {
+      const refTarget = getRefSavedTarget(current);
+      if (refTarget != null && isEntity(refTarget) && getDatabase(refTarget) == null) {
+        database.add(refTarget);
+      }
+      return current;
+    }
+    return recurse(current);
+  });
+};

package/src/internal/Annotation/index.ts

@@ -0,0 +1,9 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+export * from './dictionary';
+export * from './util';
+export * from './sorting';
+export * from './annotations';
+export * from './entity-dictionary';

package/src/internal/Annotation/sorting.ts

@@ -0,0 +1,51 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import type { AnyEntity } from '../common/types';
+import { getLabel, getTypename } from './annotations';
+
+/**
+ * String comparison helper for sorting.
+ */
+export const compare = (a?: string, b?: string): number => {
+  if (a == null) {
+    return b == null ? 0 : 1;
+  }
+  if (b == null) {
+    return -1;
+  }
+  return a.localeCompare(b);
+};
+
+/**
+ * Comparator function type for sorting entities.
+ * Accepts both reactive entities and snapshots.
+ */
+export type Comparator<T extends AnyEntity = AnyEntity> = (a: T, b: T) => number;
+
+/**
+ * Sort entities by label.
+ */
+export const sortByLabel: Comparator = (a: AnyEntity, b: AnyEntity) => compare(getLabel(a), getLabel(b));
+
+/**
+ * Sort entities by typename.
+ */
+export const sortByTypename: Comparator = (a: AnyEntity, b: AnyEntity) => compare(getTypename(a), getTypename(b));
+
+/**
+ * Compose multiple comparators into one.
+ * Applies comparators in order until one returns non-zero.
+ */
+export const sort = <T extends AnyEntity>(...comparators: Comparator<T>[]): Comparator<T> => {
+  return (a: T, b: T) => {
+    for (const comparator of comparators) {
+      const result = comparator(a, b);
+      if (result !== 0) {
+        return result;
+      }
+    }
+    return 0;
+  };
+};

package/src/internal/Annotation/util.ts

@@ -0,0 +1,94 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Option from 'effect/Option';
+import type * as Schema from 'effect/Schema';
+import * as SchemaAST from 'effect/SchemaAST';
+
+import { assertArgument } from '@dxos/invariant';
+import { DXN } from '@dxos/keys';
+
+import { EntityKind } from '../common/types';
+
+export interface AnnotationHelper<T> {
+  /**
+   * Get the annotation value from an Effect schema.
+   *
+   * Only accepts `Schema.Schema.Any` — to read an annotation off a `Type.Type`
+   * entity, unwrap it first with `Type.getSchema(entity)`. This keeps the
+   * annotation pipeline single-shaped and forces annotations to live on the
+   * source schema, not on the post-construction Type entity.
+   */
+  get: (schema: Schema.Schema.Any) => Option.Option<T>;
+  /**
+   * Get the annotation value from the AST.
+   */
+  getFromAst: (ast: SchemaAST.AST) => Option.Option<T>;
+  /**
+   * Set the annotation on an Effect schema.
+   *
+   * Only accepts `Schema.Schema.Any` — annotations must be applied to the
+   * source schema BEFORE wrapping it with `Type.makeObject` / `Type.makeRelation`.
+   * In a pipe, place every `Annotation.X.set(...)` before the `Type.make...` step.
+   */
+  set: (value: T) => <S extends Schema.Schema.Any>(schema: S) => S;
+}
+
+/**
+ * Note: only for system annotations.
+ */
+// TODO(dmaretskyi): Rename to createSystemAnnotationHelper.
+// TODO(dmaretskyi): REconcile with Annotation.make.
+export const createAnnotationHelper = <T>(id: symbol): AnnotationHelper<T> => {
+  return {
+    get: (schema) => SchemaAST.getAnnotation(schema.ast, id),
+    getFromAst: (ast) => SchemaAST.getAnnotation(ast, id),
+    set:
+      (value) =>
+      <S extends Schema.Schema.Any>(schema: S): S =>
+        schema.annotations({ [id]: value }) as S,
+  };
+};
+
+/**
+ * If property is optional returns the nested property, otherwise returns the property.
+ */
+// TODO(wittjosiah): Is there a way to do this as a generic?
+export const unwrapOptional = (property: SchemaAST.PropertySignature) => {
+  if (!property.isOptional || !SchemaAST.isUnion(property.type)) {
+    return property;
+  }
+
+  return property.type.types[0];
+};
+
+/**
+ * @see JSONSchemaAnnotationId
+ * @returns JSON-schema annotation so that the schema can be serialized with correct parameters.
+ */
+// TODO(burdon): Required type.
+export const makeTypeJsonSchemaAnnotation = (options: {
+  identifier?: string;
+  kind: EntityKind;
+  typename: string;
+  version: string;
+  relationSource?: string;
+  relationTarget?: string;
+}) => {
+  assertArgument(!!options.relationSource === (options.kind === EntityKind.Relation), 'relationSource');
+  assertArgument(!!options.relationTarget === (options.kind === EntityKind.Relation), 'relationTarget');
+
+  const obj: Record<string, unknown> = {
+    $id: options.identifier ?? DXN.make(options.typename, options.version),
+    entityKind: options.kind,
+    version: options.version,
+    typename: options.typename,
+  };
+  if (options.kind === EntityKind.Relation) {
+    obj.relationSource = { $ref: options.relationSource };
+    obj.relationTarget = { $ref: options.relationTarget };
+  }
+
+  return obj;
+};

package/src/internal/Entity/api.ts

@@ -0,0 +1,77 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { invariant } from '@dxos/invariant';
+import { DXN, EID, URI, type SpaceId } from '@dxos/keys';
+import { assumeType } from '@dxos/util';
+
+import type { AnyEntity } from '../common/types';
+import { MetaId } from '../common/types/model-symbols';
+import { type InternalObjectProps, ObjectDatabaseId } from './model';
+import { getObjectEchoUri } from './util';
+
+/**
+ * Controls the URI form returned by `getUri` and the public `*.getURI` helpers.
+ *
+ * - `'named'`    — Registry key URI (`dxn:<meta.key>`) when the entity has a key in its meta;
+ *                  falls back to the default EID.
+ * - `'absolute'` — Fully-qualified EID with space id (`echo://<spaceId>/<entityId>`);
+ *                  falls back when no space is available.
+ * - `'relative'` — Local EID without space id (`echo:/<entityId>`).
+ *
+ * Omitting `prefer` preserves the existing behaviour.
+ */
+export type GetURIOptions = {
+  prefer?: 'named' | 'absolute' | 'relative';
+};
+
+/**
+ * Get the URI of an entity.
+ * Accepts both reactive entities and snapshots.
+ */
+export const getUri = (entity: AnyEntity, options?: GetURIOptions): URI.URI => {
+  const prefer = options?.prefer;
+
+  if (prefer === 'named') {
+    const key = (entity as any)[MetaId]?.key;
+    if (key) {
+      return (DXN.tryMake(`dxn:${key}`) ?? URI.make(key)) as URI.URI;
+    }
+    const uri = getObjectEchoUri(entity);
+    invariant(uri != null, 'Invalid entity.');
+    return uri;
+  }
+
+  if (prefer === 'relative') {
+    const eid = getObjectEchoUri(entity);
+    invariant(eid != null, 'Invalid entity.');
+    const entityId = EID.getEntityId(eid);
+    return entityId ? EID.make({ entityId }) : eid;
+  }
+
+  if (prefer === 'absolute') {
+    const eid = getObjectEchoUri(entity);
+    invariant(eid != null, 'Invalid entity.');
+    const entityId = EID.getEntityId(eid);
+    if (!entityId) {
+      return eid;
+    }
+    assumeType<InternalObjectProps>(entity);
+    const spaceId: SpaceId | undefined = entity[ObjectDatabaseId]?.spaceId ?? EID.getSpaceId(eid);
+    return spaceId ? EID.make({ spaceId, entityId }) : eid;
+  }
+
+  const uri = getObjectEchoUri(entity);
+  invariant(uri != null, 'Invalid entity.');
+  return uri;
+};
+
+/**
+ * Get the database the entity belongs to.
+ * Accepts both reactive entities and snapshots.
+ */
+export const getDatabase = (entity: AnyEntity): any | undefined => {
+  assumeType<InternalObjectProps>(entity);
+  return entity[ObjectDatabaseId];
+};

package/src/internal/Entity/entity.ts

@@ -0,0 +1,277 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+import * as SchemaAST from 'effect/SchemaAST';
+import type * as Types from 'effect/Types';
+
+import { DXN, EntityId } from '@dxos/keys';
+import { type ToMutable } from '@dxos/util';
+
+import { type TypeAnnotation, TypeAnnotationId } from '../Annotation/annotations';
+import { makeTypeJsonSchemaAnnotation } from '../Annotation/util';
+import { defineHiddenProperty } from '../common/proxy/define-hidden-property';
+import { makeObject } from '../common/proxy/make-object';
+import { getProxyTarget } from '../common/proxy/proxy-utils';
+import {
+  type AnyEntity,
+  EntityKind,
+  InstancePhantomId,
+  KindId,
+  SchemaKindId,
+  StaticTypeSchemaSlot,
+} from '../common/types';
+import { type EntityMeta } from '../common/types/meta';
+import { JsonSchemaType } from '../JsonSchema/json-schema-type';
+
+// TODO(burdon): Define Schema type for `typename` and use consistently for all DXN-like properties.
+
+// type RequiredKeys<T> = { [K in keyof T]-?: {} extends Pick<T, K> ? never : K }[keyof T];
+export type EchoTypeSchemaProps<T, ExtraFields = {}> = Types.Simplify<AnyEntity & ToMutable<T> & ExtraFields>;
+
+/**
+ * Options accepted by every `Type.makeObject` / `Type.makeRelation` / type-kind
+ * factory. Defaults are derived from `(typename, version)` so callers normally
+ * pass nothing.
+ */
+export type EchoTypeOptions = {
+  /**
+   * Override the entity id stamped on the in-memory `Type.Type` value.
+   *
+   * Defaults to `EntityId.deterministic(typename, version)` — stable across processes
+   * and workerd-safe (no `crypto.getRandomValues()` at module-evaluation time).
+   * Pass an explicit id (typically `EntityId.random()`) to opt out of the
+   * deterministic default.
+   */
+  id?: EntityId;
+};
+
+/**
+ * In-memory `Type.Type` entity shape produced by `Type.makeObject(dxn)` /
+ * `Type.makeRelation({...})`. A live reactive `TypeSchema` instance —
+ * identical to a persisted `Type.Type` except for database attachment.
+ *
+ * NOT a `Schema.Schema`. The underlying Effect Schema is cached on the hidden
+ * `StaticTypeSchemaSlot` slot — retrieve it via `Type.getSchema(...)`.
+ */
+// TODO(burdon): Rename EchoEntitySchema.
+export interface EchoTypeSchema<
+  Self extends Schema.Schema.Any,
+  ExtraFields = {},
+  K extends EntityKind = EntityKind,
+  Fields extends Schema.Struct.Fields = Schema.Struct.Fields,
+> {
+  /**
+   * Entity-kind brand. Type entities are their own kind (`Type`) regardless of
+   * the kind of instance they describe — `[SchemaKindId]` carries the latter.
+   * This lets predicates like `Obj.isObject` / `Relation.isRelation` cleanly
+   * reject type entities without also having to inspect `[SchemaKindId]`.
+   */
+  readonly [KindId]: EntityKind.Type;
+
+  /** Schema-kind brand indicating what kind of instance this type describes. */
+  readonly [SchemaKindId]: K;
+
+  /**
+   * Entity id. Always present — stamped at construction — but NOT the type's
+   * identity while in-memory: an unattached type resolves its URI to the typename
+   * DXN, switching to `echo:/<id>` only once attached to a database (see
+   * `getTypeURIFromSpecifier`, which discriminates by database attachment).
+   */
+  readonly id: EntityId;
+
+  /** Source Effect Schema (kept on a hidden slot for `Type.getSchema`). */
+  readonly [StaticTypeSchemaSlot]: Schema.Schema.AnyNoContext;
+
+  // NOTE: `typename` / `version` are intentionally NOT fields. They live in
+  // `EntityMeta` (`key` / `version`); read via `Type.getTypename(self)` /
+  // `Type.getVersion(self)`.
+  readonly jsonSchema: JsonSchemaType;
+
+  /** Struct fields for introspection. */
+  readonly fields: Fields;
+
+  /** Phantom — instance type produced by `Obj.make(self, ...)`. */
+  readonly _instance?: EchoTypeSchemaProps<Schema.Schema.Type<Self>, ExtraFields>;
+
+  /**
+   * Phantom slot mirroring `Type<A>` so internal helpers (`makeObject`,
+   * `createObject`, `Ref.make`) infer the instance type uniformly whether
+   * the caller passes an `EchoTypeSchema` or a top-level `Type.Type` entity.
+   *
+   * Includes the instance-kind brand (`[KindId]`) so the phantom is assignable
+   * to the matching public-side interface in `Type.ts` (`Type.Obj` /
+   * `Type.Relation` / `Type.Type`). Each kind projects identity: instances of
+   * an object-kind schema are object-kind entities, type-kind schemas produce
+   * type-kind (persisted Type.Type) entities — the latter additionally carry
+   * the `[SchemaKindId]` / `[StaticTypeSchemaSlot]` brands the echo-handler
+   * proxy exposes on persisted Type entities.
+   */
+  readonly [InstancePhantomId]?: EchoTypeSchemaProps<Schema.Schema.Type<Self>, ExtraFields> & {
+    readonly [KindId]: K;
+  } & (K extends EntityKind.Type
+      ? {
+          readonly [SchemaKindId]: EntityKind.Type;
+          readonly [StaticTypeSchemaSlot]: Schema.Schema.AnyNoContext;
+        }
+      : {});
+}
+
+// type MakeProps =
+//   | boolean
+//   | {
+//       readonly disableValidation?: boolean;
+//     };
+
+// NOTE: Utils copied from Effect `Schema.ts`.
+// const _ownKeys = (o: object): Array<PropertyKey> =>
+//   (Object.keys(o) as Array<PropertyKey>).concat(Object.getOwnPropertySymbols(o));
+
+// const _lazilyMergeDefaults = (
+//   fields: Schema.Struct.Fields,
+//   out: Record<PropertyKey, unknown>,
+// ): { [x: string | symbol]: unknown } => {
+//   const ownKeys = _ownKeys(fields);
+//   for (const key of ownKeys) {
+//     const field = fields[key];
+//     if (out[key] === undefined && Schema.isPropertySignature(field)) {
+//       const ast = field.ast;
+//       const defaultValue = ast._tag === 'PropertySignatureDeclaration' ? ast.defaultValue : ast.to.defaultValue;
+//       if (defaultValue !== undefined) {
+//         out[key] = defaultValue();
+//       }
+//     }
+//   }
+//   return out;
+// };
+
+// const _getDisableValidationMakeOption = (options: MakeProps | undefined): boolean =>
+//   Predicate.isBoolean(options) ? options : options?.disableValidation ?? false;
+
+/**
+ * Identity (typename + version) of the type meta-schema — the `Type.Type` that
+ * every ECHO type entity is itself an instance of. Shared by the materialisation
+ * vehicle ({@link persistentEntitySchema}) and `TypeSchema` so the two cannot
+ * drift on identity.
+ */
+export const TypeMetaSchemaDXN = DXN.make('org.dxos.type.schema', '0.1.0');
+
+/**
+ * Effect Schema that every `Type.Type` entity is an instance of: the meta-schema
+ * struct `{ name?, jsonSchema, id }` branded as a type-kind ECHO entity. This is
+ * the materialisation vehicle for `makeObject` below — the canonical user-facing
+ * entity is `Type/type-schema.ts`'s `TypeSchema`, which carries the same shape
+ * plus UI annotations.
+ *
+ * Kept self-contained (no import of `TypeSchema`) to avoid a bootstrap cycle:
+ * `TypeSchema` is itself produced via `makeEchoTypeSchema`, so this builder must
+ * not depend on it. `jsonSchema` is declared optional here (only on the
+ * materialisation vehicle — the canonical `TypeSchema` keeps it required) so the
+ * construction-time `Schema.asserts` does not force the field before it is
+ * attached; it is populated immediately after via a lazy accessor (see
+ * `makeEchoTypeSchema`).
+ */
+// TODO(wittjosiah): Reconcile with `TypeSchema` (`Type/type-schema.ts`).
+//   Both describe the same `org.dxos.type.schema` shape.
+const persistentEntitySchema: Schema.Schema.AnyNoContext = (() => {
+  const typename = DXN.getName(TypeMetaSchemaDXN);
+  const version = DXN.getVersion(TypeMetaSchemaDXN)!;
+  const struct = Schema.Struct({
+    name: Schema.optional(Schema.String),
+    jsonSchema: JsonSchemaType.pipe(Schema.optional),
+    id: EntityId,
+  });
+  const ast = SchemaAST.annotations(struct.ast, {
+    [TypeAnnotationId]: { kind: EntityKind.Type, typename, version } satisfies TypeAnnotation,
+    [SchemaAST.JSONSchemaAnnotationId]: makeTypeJsonSchemaAnnotation({ kind: EntityKind.Type, typename, version }),
+  });
+  return Schema.make(ast);
+})();
+
+/**
+ * @internal
+ *
+ * Build an in-memory `Type.Type` entity (the value returned by `Type.makeObject`
+ * / `Type.makeRelation`). The result is a LIVE reactive `TypeSchema`
+ * instance — identical in every respect to a persisted `Type.Type` except that
+ * it is not yet attached to a database. It is mutable via `Type.update`, can be
+ * passed to `db.add(...)` (which keeps the same proxy and swaps the handler),
+ * and round-trips through `jsonSchema`.
+ *
+ * The source Effect Schema describing the user's type is cached on
+ * `[StaticTypeSchemaSlot]` so `Type.getSchema(...)` returns it without a
+ * jsonSchema round-trip; the cache is invalidated by the proxy set-trap when
+ * `jsonSchema` is mutated (see `typed-handler.ts`).
+ */
+export const makeEchoTypeSchema = <
+  Self extends Schema.Schema.Any,
+  K extends EntityKind = EntityKind,
+  // TODO(wittjosiah): Can this be inferred from the schema?
+  Fields extends Schema.Struct.Fields = Schema.Struct.Fields,
+>(
+  fields: Fields,
+  ast: SchemaAST.AST,
+  typename: string,
+  version: string,
+  kind: K,
+  computeJsonSchema: () => JsonSchemaType,
+  explicitId?: EntityId,
+): EchoTypeSchema<Self, {}, K, Fields> => {
+  // Source Effect Schema describing the user's type — cached for `Type.getSchema`.
+  const sourceSchema = Schema.make<
+    EchoTypeSchemaProps<Schema.Schema.Type<Self>>,
+    EchoTypeSchemaProps<Schema.Schema.Encoded<Self>>,
+    Schema.Schema.Context<Self>
+  >(ast);
+
+  // `typename` / `version` route through `EntityMeta` (`key` / `version`) — the
+  // canonical registry-provenance pair — not data fields. `keys` is empty for
+  // in-memory declarations until persisted.
+  const meta: Partial<EntityMeta> = { keys: [], key: typename, version };
+
+  // Default to a deterministic id derived from `(typename, version)` so that
+  // constructing a `Type.Type` entity never reaches `crypto.getRandomValues()`.
+  // Cloudflare workerd forbids RNG calls in global scope, and the ~hundreds of
+  // `Type.makeObject(...)` call sites across the monorepo execute at module top.
+  // `setIdOnTarget` (see `proxy/make-object.ts`) short-circuits on a pre-supplied
+  // valid id, so this also bypasses the `EntityId.random()` path inside `makeObject`.
+  // Callers can override via `Type.makeObject(dxn, { id })` when they want a fresh
+  // random id (e.g. inside a request handler where workerd does allow RNG).
+  const id = explicitId ?? EntityId.deterministic(typename, version);
+
+  // Materialise as a live reactive meta-schema instance. `jsonSchema` is attached
+  // below as a getter (not passed here as data) for two reasons; see that accessor.
+  const entity = makeObject(persistentEntitySchema, { id } as any, meta);
+
+  const target = getProxyTarget(entity)!;
+  // `jsonSchema` is always available, but computed once on first read rather than at
+  // construction: serializing the AST walks `Schema.suspend(...)` thunks, and for a
+  // self-referential type (`Schema.suspend(() => Self)`) that thunk hits `Self`'s TDZ
+  // while we're still inside its `const` initializer. A getter also lets reads return
+  // the raw object instead of a child reactive proxy.
+  let memoizedJsonSchema: JsonSchemaType | undefined;
+  Object.defineProperty(target, 'jsonSchema', {
+    configurable: true,
+    enumerable: true,
+    get() {
+      return (memoizedJsonSchema ??= computeJsonSchema());
+    },
+    set(value: JsonSchemaType) {
+      memoizedJsonSchema = value;
+    },
+  });
+  // Cache the source Effect Schema (read by `Type.getSchema` via the proxy's
+  // `[StaticTypeSchemaSlot]` get-trap; invalidated on `jsonSchema` mutation).
+  defineHiddenProperty(target, StaticTypeSchemaSlot, sourceSchema);
+  // Schema-kind brand: what kind of instance this type describes. There is no
+  // database handler to derive it for in-memory entities, so stamp it directly.
+  defineHiddenProperty(target, SchemaKindId, kind);
+  // Struct fields for introspection. A getter (not a data property) so reads return
+  // the raw fields object rather than a child reactive proxy.
+  Object.defineProperty(target, 'fields', { configurable: true, enumerable: false, get: () => fields });
+
+  return entity as unknown as EchoTypeSchema<Self, {}, K, Fields>;
+};
+
+export { isEntity } from './guard';

package/src/internal/Entity/guard.ts

@@ -0,0 +1,26 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import type * as Entity from '../../Entity';
+import { KindId, SnapshotKindId } from '../common/types';
+
+/**
+ * Returns true if the value is an ECHO entity instance (object or relation).
+ */
+export const isEntity = (value: unknown): value is Entity.Unknown => {
+  if (typeof value !== 'object' || value === null) {
+    return false;
+  }
+  return (value as any)[KindId] !== undefined;
+};
+
+/**
+ * Returns true if the value is an ECHO entity snapshot.
+ */
+export const isSnapshot = (value: unknown): value is Entity.Snapshot => {
+  if (typeof value !== 'object' || value === null) {
+    return false;
+  }
+  return (value as any)[SnapshotKindId] !== undefined;
+};

package/src/internal/Entity/index.ts

@@ -0,0 +1,13 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+export * from './api';
+export * from './entity';
+export * from './model'; // TODO(burdon): Rename.
+export * from './object';
+export * from './relation';
+export * from './type-kind';
+export * from './type-uri';
+export * from './util';
+export * from './version';