@dxos/echo 0.10.0 → 0.11.0

package/dist/lib/chunk-ref.mjs

@@ -0,0 +1,590 @@
+import { g as getStaticTypeSchema } from "./chunk-util.mjs";
+import { Jt as ObjectDeletedId, bt as getTypeAnnotation, et as ReferenceAnnotationId, r as Service, vt as getSchemaURI, xt as getTypeIdentifierAnnotation } from "./chunk-Database.mjs";
+import { EncodedReference } from "@dxos/echo-protocol";
+import { DXN, EID, EntityId } from "@dxos/keys";
+import * as Option from "effect/Option";
+import * as Schema from "effect/Schema";
+import * as SchemaAST from "effect/SchemaAST";
+import { assertArgument, invariant } from "@dxos/invariant";
+import * as Effect from "effect/Effect";
+import * as Equal from "effect/Equal";
+import * as Hash from "effect/Hash";
+import * as ParseResult from "effect/ParseResult";
+import * as Pipeable from "effect/Pipeable";
+import { Event } from "@dxos/async";
+import { inspectCustom } from "@dxos/debug";
+import * as Atom from "@effect-atom/atom/Atom";
+//#region src/internal/common/proxy/proxy-utils.ts
+var __dxlog_file$1 = "/__w/dxos/dxos/packages/core/echo/echo/src/internal/common/proxy/proxy-utils.ts";
+var symbolIsProxy = Symbol.for("@dxos/schema/Proxy");
+/**
+* Marker placed on a reactive-object behaviour prototype (e.g. the typed handler's
+* `TypedObject` prototype). A record target whose prototype chain carries this marker
+* is a reactive data record — equivalent, for the purposes of the "plain object" gates
+* below, to one rooted directly at `Object.prototype`. This lets a handler move its
+* per-object metadata onto an intermediate prototype without those gates mistaking the
+* record for a foreign class instance.
+*/
+var symbolReactivePrototype = Symbol.for("@dxos/echo/ReactivePrototype");
+/**
+* Internal api.
+*/
+var isProxy = (value) => !!value?.[symbolIsProxy];
+/**
+* True if `value` is a plain data record — either rooted at `Object.prototype` or carrying
+* a reactive behaviour prototype (see {@link symbolReactivePrototype}).
+*/
+var isReactiveRecord = (value) => {
+	const proto = Object.getPrototypeOf(value);
+	return proto === Object.prototype || proto != null && !!proto[symbolReactivePrototype];
+};
+var isValidProxyTarget = (value) => {
+	if (value == null || value[symbolIsProxy]) return false;
+	if (Array.isArray(value)) return true;
+	return typeof value === "object" && isReactiveRecord(value);
+};
+/**
+* @deprecated
+*/
+var getProxySlot = (proxy) => {
+	const value = proxy[symbolIsProxy];
+	invariant(value instanceof ProxyHandlerSlot, void 0, {
+		"~LogMeta": "~LogMeta",
+		F: __dxlog_file$1,
+		L: 51,
+		S: void 0,
+		A: ["value instanceof ProxyHandlerSlot", ""]
+	});
+	return value;
+};
+var getProxyTarget = (proxy) => {
+	return getProxySlot(proxy).target;
+};
+var getProxyHandler = (proxy) => {
+	return getProxySlot(proxy).handler;
+};
+/**
+* Clamp a splice range to `Array.prototype.splice` semantics for a string of the given `length`:
+* a negative `start` counts from the end, a `start` past the end appends, and `deleteCount` is bounded
+* to the remaining characters. Shared by both reactive handlers so the string CRDT API behaves
+* identically across the in-memory and Automerge backends (Automerge's `splice` otherwise throws on
+* out-of-range indices).
+*/
+var normalizeSpliceRange = (length, start, deleteCount) => {
+	const safeStart = start < 0 ? Math.max(length + start, 0) : Math.min(start, length);
+	return {
+		start: safeStart,
+		deleteCount: Math.max(0, Math.min(deleteCount, length - safeStart))
+	};
+};
+/**
+* Unsafe method to override id for debugging/testing and migration purposes.
+* @deprecated
+*/
+var dangerouslySetProxyId = (obj, id) => {
+	getProxySlot(obj).target.id = id;
+};
+/**
+* Create a reactive proxy object.
+* https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy
+*
+* @param target Object or array. Passing in array will enable array methods.
+* @param handler ReactiveHandler instance.
+*/
+var createProxy = (target, handler) => {
+	const existingProxy = handler._proxyMap.get(target);
+	if (existingProxy) return existingProxy;
+	const proxy = new Proxy(target, new ProxyHandlerSlot(target, handler));
+	handler.init(target);
+	handler._proxyMap.set(target, proxy);
+	return proxy;
+};
+/**
+* Passed as the handler to the Proxy constructor.
+* Maintains a mutable slot for the actual handler.
+*/
+var ProxyHandlerSlot = class {
+	target;
+	_handler;
+	/**
+	* @param target Original object.
+	* @param _handler Handles intercepted operations.
+	*/
+	constructor(target, _handler) {
+		this.target = target;
+		this._handler = _handler;
+	}
+	get handler() {
+		invariant(this._handler, void 0, {
+			"~LogMeta": "~LogMeta",
+			F: __dxlog_file$1,
+			L: 127,
+			S: this,
+			A: ["this._handler", ""]
+		});
+		return this._handler;
+	}
+	setHandler(handler) {
+		this._handler = handler;
+	}
+	/**
+	* Get value.
+	*/
+	get(target, prop, receiver) {
+		if (prop === symbolIsProxy) return this;
+		if (!this._handler || !this._handler.get) return Reflect.get(target, prop, receiver);
+		return this._handler.get(target, prop, receiver);
+	}
+	static {
+		for (const trap of [
+			"apply",
+			"construct",
+			"defineProperty",
+			"deleteProperty",
+			"get",
+			"getOwnPropertyDescriptor",
+			"getPrototypeOf",
+			"has",
+			"isExtensible",
+			"ownKeys",
+			"preventExtensions",
+			"set",
+			"setPrototypeOf"
+		]) {
+			if (trap === "get") continue;
+			Object.defineProperty(this.prototype, trap, {
+				enumerable: false,
+				value: function(...args) {
+					if (!this._handler || !this._handler[trap]) return Reflect[trap](...args);
+					return this._handler[trap].apply(this._handler, args);
+				}
+			});
+		}
+	}
+};
+//#endregion
+//#region src/internal/common/proxy/symbols.ts
+var EventId = Symbol.for("@dxos/live-object/EventId");
+var ChangeId = Symbol.for("@dxos/live-object/ChangeId");
+//#endregion
+//#region src/internal/common/proxy/reactive.ts
+/**
+* Subscribe to changes on a reactive object.
+* @param obj - The reactive object to subscribe to.
+* @param callback - Called when the object changes.
+* @returns Unsubscribe function.
+*/
+var subscribe = (obj, callback) => {
+	if (!isProxy(obj)) return () => {};
+	const target = getProxyTarget(obj);
+	if (target && EventId in target) return target[EventId].on(callback);
+	return () => {};
+};
+/**
+* Perform mutations on a reactive object within a change context.
+*
+* If the object has a change handler (via ChangeId), it will be called with the callback.
+* This allows handlers to implement features like:
+* - Readonly enforcement (mutations only allowed within change context)
+* - Batched notifications (single notification for all mutations in the callback)
+* - Transaction semantics
+*
+* If the object doesn't have a change handler, the callback is called directly.
+*
+* @param obj - The reactive object to mutate.
+* @param callback - Callback that receives a mutable view of the object.
+*/
+var change = (obj, callback) => {
+	const changeFn = obj[ChangeId];
+	if (changeFn) changeFn(callback);
+	else callback(obj);
+};
+//#endregion
+//#region src/internal/Ref/utils.ts
+/**
+* Internal helper for loading ref targets in atoms.
+* Handles the common pattern of checking for loaded target and triggering async load.
+*/
+var loadRefTarget = (ref, get, onTargetAvailable) => {
+	const currentTarget = ref.target;
+	if (currentTarget) return onTargetAvailable(currentTarget);
+	const unsubscribe = ref.onResolved(() => {
+		const target = ref.target;
+		if (target) get.setSelf(onTargetAvailable(target));
+	});
+	get.addFinalizer(unsubscribe);
+	ref.load().then((loadedTarget) => {
+		get.setSelf(onTargetAvailable(loadedTarget));
+	}).catch(() => {});
+};
+//#endregion
+//#region src/internal/Ref/atoms.ts
+/**
+* Atom family for ECHO refs.
+* Uses ref reference as key — same ref returns same atom.
+* Subscribes to target object changes and resolves to undefined when the target is deleted.
+*/
+var refSimpleFamily = Atom.family((ref) => {
+	return Atom.make((get) => {
+		let unsubscribeTarget;
+		const setupSubscription = (target) => {
+			unsubscribeTarget?.();
+			unsubscribeTarget = subscribe(target, () => {
+				const deleted = !!target[ObjectDeletedId];
+				get.setSelf(deleted ? void 0 : target);
+			});
+			return !!target[ObjectDeletedId] ? void 0 : target;
+		};
+		get.addFinalizer(() => {
+			unsubscribeTarget?.();
+		});
+		return loadRefTarget(ref, get, setupSubscription);
+	}).pipe(Atom.keepAlive);
+});
+//#endregion
+//#region src/internal/Ref/ref.ts
+var __dxlog_file = "/__w/dxos/dxos/packages/core/echo/echo/src/internal/Ref/ref.ts";
+/**
+* The `$id` and `$ref` fields for an ECHO reference schema.
+*/
+var JSON_SCHEMA_ECHO_REF_ID = "/schemas/echo/ref";
+var getSchemaReference = (property) => {
+	const { $id, reference: { schema: { $ref } = {} } = {} } = property;
+	if ($id === "/schemas/echo/ref" && $ref) {
+		const parsed = DXN.tryMake($ref);
+		const typename = parsed ? DXN.getName(parsed) : void 0;
+		return typename ? { typename } : void 0;
+	}
+};
+var createSchemaReference = (typename) => {
+	return {
+		$id: JSON_SCHEMA_ECHO_REF_ID,
+		reference: { schema: { $ref: DXN.make(typename) } }
+	};
+};
+var getReferenceAst = (ast) => {
+	if (ast._tag !== "Declaration" || !ast.annotations[ReferenceAnnotationId]) return;
+	return {
+		typename: ast.annotations[ReferenceAnnotationId].typename,
+		version: ast.annotations[ReferenceAnnotationId].version
+	};
+};
+var RefTypeId = Symbol.for("@dxos/echo/internal/Ref");
+/**
+* Schema builder for references.
+*/
+var Ref = (input) => {
+	const schema = getStaticTypeSchema(input) ?? input;
+	assertArgument(Schema.isSchema(schema), "schema", "Must call with an instance of effect-schema");
+	const annotation = getTypeAnnotation(schema);
+	if (annotation == null) throw new Error("Reference target must be an ECHO schema.");
+	return createEchoReferenceSchema(getTypeIdentifierAnnotation(schema), annotation.typename, annotation.version);
+};
+Ref.isRef = (obj) => {
+	return obj != null && typeof obj === "object" && RefTypeId in obj;
+};
+Ref.hasEntityId = (id) => (ref) => {
+	const uri = EID.tryParse(ref.uri);
+	return uri !== void 0 && EID.isLocal(uri) && EID.getEntityId(uri) === id;
+};
+Ref.isRefSchema = (schema) => {
+	return Ref.isRefSchemaAST(schema.ast);
+};
+Ref.isRefSchemaAST = (ast) => {
+	return SchemaAST.getAnnotation(ast, ReferenceAnnotationId).pipe(Option.isSome);
+};
+Ref.make = (obj) => {
+	if (typeof obj !== "object" || obj === null) throw new TypeError("Expected: ECHO object.");
+	const id = obj.id;
+	invariant(EntityId.isValid(id), "Invalid object ID", {
+		"~LogMeta": "~LogMeta",
+		F: __dxlog_file,
+		L: 287,
+		S: void 0,
+		A: ["EntityId.isValid(id)", "'Invalid object ID'"]
+	});
+	return new RefImpl(EID.make({ entityId: id }), obj);
+};
+Ref.fromURI = (uri) => {
+	assertArgument(typeof uri === "string", "uri", "Expected URI string");
+	return new RefImpl(uri);
+};
+/**
+* @internal
+*/
+var createEchoReferenceSchema = (echoUri, typename, version) => {
+	if (!echoUri && !typename) throw new TypeError("Either echoUri or typename must be provided.");
+	const referenceInfo = {
+		schema: { $ref: echoUri ?? DXN.make(typename) },
+		schemaVersion: version
+	};
+	return Schema.declare([], {
+		encode: () => {
+			return (value) => Effect.gen(function* () {
+				if (Ref.isRef(value)) return EncodedReference.fromURI(value.uri);
+				else if (EncodedReference.isEncodedReference(value)) return value;
+				throw new Error("Invalid reference");
+			});
+		},
+		decode: () => {
+			return (value) => Effect.gen(function* () {
+				const dbService = yield* Effect.serviceOption(Service);
+				if (Ref.isRef(value)) if (Option.isSome(dbService)) return dbService.value.db.makeRef(value.uri);
+				else return value;
+				if (!EncodedReference.isEncodedReference(value)) return yield* Effect.fail(new ParseResult.Unexpected(value, "reference"));
+				if (Option.isSome(dbService)) return dbService.value.db.makeRef(EncodedReference.toURI(value));
+				else return Ref.fromURI(EncodedReference.toURI(value));
+			});
+		}
+	}, {
+		jsonSchema: {
+			$id: JSON_SCHEMA_ECHO_REF_ID,
+			$ref: JSON_SCHEMA_ECHO_REF_ID,
+			reference: referenceInfo
+		},
+		[ReferenceAnnotationId]: {
+			typename: typename ?? "",
+			version
+		}
+	});
+};
+/**
+* A settled {@link RefResolverRequest} with a fixed `state` and `result`, used by resolvers
+* whose backends are fully synchronous (e.g. {@link StaticRefResolver}).
+*/
+var makeSettledRequest = (state, result) => ({
+	state,
+	stateChanged: new Event(),
+	getResult: () => state === "ready" ? result : void 0,
+	wait: async () => state === "ready" ? result : void 0,
+	abort: () => {}
+});
+var RefImpl = class RefImpl {
+	[RefTypeId] = refVariance;
+	#uri;
+	/**
+	* Target is set when the reference is created from a specific object.
+	* In this case, the target might not be in the database.
+	*/
+	#target = void 0;
+	#resolver = void 0;
+	#resolved = new Event();
+	/**
+	* Callback to issue a reactive notification when object is resolved.
+	*/
+	#resolverCallback = () => {
+		this.#resolved.emit();
+	};
+	constructor(uri, target) {
+		this.#uri = uri;
+		this.#target = target;
+	}
+	/**
+	* @inheritdoc
+	*/
+	get uri() {
+		return this.#uri;
+	}
+	/**
+	* @inheritdoc
+	*/
+	get target() {
+		if (this.#target) return this.#target;
+		invariant(this.#resolver, "Resolver is not set", {
+			"~LogMeta": "~LogMeta",
+			F: __dxlog_file,
+			L: 534,
+			S: this,
+			A: ["this.#resolver", "'Resolver is not set'"]
+		});
+		return this.#resolver.resolveSync(this.#uri, true, this.#resolverCallback);
+	}
+	/**
+	* @inheritdoc
+	*/
+	get isAvailable() {
+		return this.#target !== void 0 || this.#resolver !== void 0;
+	}
+	get atom() {
+		return refSimpleFamily(this);
+	}
+	/**
+	* @inheritdoc
+	*/
+	async load() {
+		if (this.#target) return this.#target;
+		invariant(this.#resolver, "Resolver is not set", {
+			"~LogMeta": "~LogMeta",
+			F: __dxlog_file,
+			L: 556,
+			S: this,
+			A: ["this.#resolver", "'Resolver is not set'"]
+		});
+		const obj = await this.#resolver.resolveLegacy(this.#uri);
+		if (obj == null) throw new Error("Object not found");
+		return obj;
+	}
+	/**
+	* @inheritdoc
+	*/
+	async tryLoad() {
+		if (this.#target) return this.#target;
+		invariant(this.#resolver, "Resolver is not set", {
+			"~LogMeta": "~LogMeta",
+			F: __dxlog_file,
+			L: 571,
+			S: this,
+			A: ["this.#resolver", "'Resolver is not set'"]
+		});
+		return await this.#resolver.resolveLegacy(this.#uri);
+	}
+	/**
+	* @inheritdoc
+	*/
+	onResolved(callback) {
+		return this.#resolved.on(callback);
+	}
+	/**
+	* Do not inline the target object in the reference.
+	* Makes .target unavailable unless the reference is connected to a database context.
+	* Clones the reference object.
+	*/
+	noInline() {
+		const ref = new RefImpl(this.#uri, void 0);
+		ref.#resolver = this.#resolver;
+		return ref;
+	}
+	encode() {
+		return {
+			"/": this.#uri,
+			...this.#target ? { target: this.#target } : {}
+		};
+	}
+	/**
+	* Serializes the reference to a JSON object.
+	* The serialization format is compatible with the IPLD-style encoded references.
+	* When a reference has a saved target (i.e. the target or object holding the reference is not in the database),
+	* the target is included in the serialized object.
+	*/
+	toJSON() {
+		return this.encode();
+	}
+	toString() {
+		if (this.#target) return `Ref(${this.#target.toString()})`;
+		return `Ref(${this.#uri.toString()})`;
+	}
+	[inspectCustom] = (depth, options, inspect) => {
+		return this.toString();
+	};
+	/**
+	* Effect Hash trait. Required for MutableHashMap-based caches (e.g., Atom.family)
+	* to deduplicate Ref instances that point to the same object.
+	* ECHO proxies return new RefImpl instances on every property access,
+	* so without this, each access would create a separate cache entry.
+	*/
+	[Hash.symbol]() {
+		return Hash.hash(this.#uri.toString());
+	}
+	/** Effect Equal trait. See {@link Hash.symbol} for rationale. */
+	[Equal.symbol](that) {
+		return that instanceof RefImpl && this.#uri === that.uri;
+	}
+	pipe() {
+		return Pipeable.pipeArguments(this, arguments);
+	}
+	/**
+	* @internal
+	*/
+	_setResolver(resolver) {
+		this.#resolver = resolver;
+	}
+	/**
+	* @internal
+	*/
+	_getSavedTarget() {
+		return this.#target;
+	}
+};
+/**
+* Internal API for setting the reference resolver.
+*/
+var setRefResolver = (ref, resolver) => {
+	invariant(ref instanceof RefImpl, "Ref is not an instance of RefImpl", {
+		"~LogMeta": "~LogMeta",
+		F: __dxlog_file,
+		L: 661,
+		S: void 0,
+		A: ["ref instanceof RefImpl", "'Ref is not an instance of RefImpl'"]
+	});
+	ref._setResolver(resolver);
+};
+/**
+* Internal API for getting the saved target on a reference.
+*/
+var getRefSavedTarget = (ref) => {
+	invariant(ref instanceof RefImpl, "Ref is not an instance of RefImpl", {
+		"~LogMeta": "~LogMeta",
+		F: __dxlog_file,
+		L: 669,
+		S: void 0,
+		A: ["ref instanceof RefImpl", "'Ref is not an instance of RefImpl'"]
+	});
+	return ref._getSavedTarget();
+};
+var refVariance = { _T: null };
+var refFromEncodedReference = (encodedReference, resolver) => {
+	const ref = new RefImpl(EncodedReference.toURI(encodedReference));
+	if (resolver) setRefResolver(ref, resolver);
+	return ref;
+};
+var StaticRefResolver = class {
+	objects = /* @__PURE__ */ new Map();
+	schemas = /* @__PURE__ */ new Map();
+	addObject(obj) {
+		this.objects.set(obj.id, obj);
+		return this;
+	}
+	addSchema(input) {
+		const schema = getStaticTypeSchema(input);
+		invariant(schema, "Type entity is missing its source schema", {
+			"~LogMeta": "~LogMeta",
+			F: __dxlog_file,
+			L: 701,
+			S: this,
+			A: ["schema", "'Type entity is missing its source schema'"]
+		});
+		const uri = getSchemaURI(schema);
+		invariant(uri, "Schema has no URI", {
+			"~LogMeta": "~LogMeta",
+			F: __dxlog_file,
+			L: 703,
+			S: this,
+			A: ["uri", "'Schema has no URI'"]
+		});
+		this.schemas.set(uri, schema);
+		return this;
+	}
+	resolve(uri, _options) {
+		const obj = this.#lookup(uri);
+		return makeSettledRequest(obj ? "ready" : "unavailable", obj);
+	}
+	resolveSync(uri, _load, _onLoad) {
+		return this.#lookup(uri);
+	}
+	async resolveLegacy(uri) {
+		return this.#lookup(uri);
+	}
+	async resolveSchema(uri) {
+		return this.schemas.get(uri);
+	}
+	#lookup(uri) {
+		const echoUri = EID.tryParse(uri);
+		const id = echoUri ? EID.getEntityId(echoUri) : void 0;
+		if (id == null) return;
+		return this.objects.get(id);
+	}
+};
+//#endregion
+export { getProxyTarget as C, normalizeSpliceRange as D, isValidProxyTarget as E, symbolIsProxy as O, getProxySlot as S, isReactiveRecord as T, ChangeId as _, StaticRefResolver as a, dangerouslySetProxyId as b, getRefSavedTarget as c, makeSettledRequest as d, refFromEncodedReference as f, subscribe as g, change as h, RefTypeId as i, symbolReactivePrototype as k, getReferenceAst as l, loadRefTarget as m, Ref as n, createEchoReferenceSchema as o, setRefResolver as p, RefImpl as r, createSchemaReference as s, JSON_SCHEMA_ECHO_REF_ID as t, getSchemaReference as u, EventId as v, isProxy as w, getProxyHandler as x, createProxy as y };
+
+//# sourceMappingURL=chunk-ref.mjs.map