@typed/fx 2.0.0-beta.1 → 2.0.0-beta.10

package/dist/RefSubject/Hydration.js

@@ -0,0 +1,300 @@
+import * as Cause from "effect/Cause";
+import * as Deferred from "effect/Deferred";
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+import * as Stream from "effect/Stream";
+import { continueWith as fxContinueWith } from "../Fx/combinators/continueWith.js";
+import { unwrap as fxUnwrap } from "../Fx/combinators/unwrap.js";
+import { fromEffect as fxFromEffect } from "../Fx/constructors/fromEffect.js";
+import { isFx } from "../Fx/TypeId.js";
+import { fromStream as fxFromStream } from "../Fx/stream.js";
+import * as Sink from "../Sink/Sink.js";
+import { CurrentComputedBehavior, make, } from "./RefSubject.js";
+/**
+ * Runtime symbol exposing hydration metadata on a hydrated RefSubject.
+ *
+ * @remarks
+ * ## Why
+ *
+ * Provides the runtime key that exposes a hydrated ref's serialization and restoration metadata
+ * without changing its RefSubject prototype.
+ *
+ * ## Ownership and lifetime
+ *
+ * This declaration acquires no resources. Effects represented by the contract retain their own
+ * services and Scope requirements.
+ *
+ * @since 2.0.0
+ * @category Hydration protocol
+ */
+export const HydrationRefTypeId = Symbol.for("@typed/fx/RefSubjectRef");
+/**
+ * Canonical data attribute for the versioned envelope of unnamed hydrated refs.
+ *
+ * @remarks
+ * ## Why
+ *
+ * Names the versioned envelope used when several unnamed hydrated values share one server-rendered
+ * attribute.
+ *
+ * ## Ownership and lifetime
+ *
+ * This declaration acquires no resources. Effects represented by the contract retain their own
+ * services and Scope requirements.
+ *
+ * @since 2.0.0
+ * @category Hydration protocol
+ */
+export const HYDRATION_ATTRIBUTE = "data-typed-refsubject";
+const allUnbounded = (effects) => Effect.all(effects, { concurrency: "unbounded" });
+/**
+ * Tests whether a value carries callable hydration metadata.
+ *
+ * @remarks
+ * ## Why
+ *
+ * Detects hydration capability by its public TypeId instead of relying on a concrete class or
+ * renderer.
+ *
+ * ## Ownership and lifetime
+ *
+ * This declaration acquires no resources. Effects represented by the contract retain their own
+ * services and Scope requirements.
+ *
+ * @since 2.0.0
+ * @category Type guards
+ */
+export function isHydrationRef(value) {
+    return (typeof value === "function" &&
+        HydrationRefTypeId in value &&
+        typeof value[HydrationRefTypeId] === "object" &&
+        value[HydrationRefTypeId] !== null);
+}
+/**
+ * Implements named and unnamed hydrated RefSubject construction.
+ *
+ * @remarks
+ * ## Why
+ *
+ * Creates state whose server value is Schema-encoded and whose browser value is Schema-decoded
+ * before the initializer resumes.
+ *
+ * ## Ownership and lifetime
+ *
+ * The creation Effect requires Scope; that Scope owns initializer subscriptions and deferred
+ * server/client coordination. Schema errors and codec services remain typed.
+ *
+ * @since 2.0.0
+ * @category Hydration construction
+ */
+export function hydrate(schema, effect, options) {
+    const attributeName = options?.name === undefined ? undefined : toHydrationAttributeName(options.name);
+    return Effect.gen(function* () {
+        const initializer = yield* makeHydrationInitializer(normalizeHydrationInitializer(effect));
+        const ref = yield* make(initializer.value, {
+            ...options,
+            eq: options?.eq ?? Schema.toEquivalence(schema),
+        });
+        const member = {
+            schema,
+            attributeName,
+            ref,
+            server: initializer.server,
+            hydrate: initializer.dom,
+        };
+        const initializeForCurrentBehavior = Effect.flatMap(CurrentComputedBehavior, (behavior) => behavior === "one" ? initializer.server : Effect.void);
+        const hydrationRef = Object.assign(makeHydrationRef([member]), {
+            run: (sink) => Effect.andThen(initializeForCurrentBehavior, ref.run(sink)),
+            toEffect: () => Effect.andThen(initializeForCurrentBehavior, ref),
+        });
+        return Object.setPrototypeOf(hydrationRef, ref);
+    });
+}
+function toHydrationAttributeName(name) {
+    const attributeName = `data-${name}`.toLowerCase();
+    if (name.length === 0 ||
+        attributeName === HYDRATION_ATTRIBUTE ||
+        !isValidAttributeName(attributeName)) {
+        throw new TypeError(`Invalid hydration attribute name: ${name}`);
+    }
+    return attributeName;
+}
+const forbiddenAttributeNameCharacters = new Set(['"', "'", "/", ">", "=", "<"]);
+function isValidAttributeName(name) {
+    for (const character of name) {
+        const codePoint = character.codePointAt(0);
+        if (codePoint <= 0x20 ||
+            (codePoint >= 0x7f && codePoint <= 0x9f) ||
+            forbiddenAttributeNameCharacters.has(character)) {
+            return false;
+        }
+    }
+    return true;
+}
+function makeHydrationInitializer(value) {
+    return Effect.gen(function* () {
+        const environment = yield* Deferred.make();
+        const hydrated = yield* Deferred.make();
+        const server = Effect.asVoid(Deferred.succeed(environment, "server"));
+        const dom = (value) => Effect.asVoid(Effect.andThen(Deferred.complete(hydrated, value), Deferred.succeed(environment, "dom")));
+        if (isFx(value)) {
+            const hydratedValueDeferredFx = fxFromEffect(Deferred.await(hydrated));
+            return {
+                value: fxUnwrap(Effect.map(Deferred.await(environment), (environment) => environment === "server" ? value : fxContinueWith(hydratedValueDeferredFx, () => value))),
+                server,
+                dom,
+            };
+        }
+        let first = true;
+        const hydratedValueDeferred = Effect.suspend(() => {
+            if (first) {
+                first = false;
+                return Deferred.await(hydrated);
+            }
+            return value;
+        });
+        return {
+            value: Effect.flatMap(Deferred.await(environment), (environment) => environment === "server" ? value : hydratedValueDeferred),
+            server,
+            dom,
+        };
+    });
+}
+function normalizeHydrationInitializer(value) {
+    if (isFx(value) || Effect.isEffect(value))
+        return value;
+    if (Stream.isStream(value))
+        return fxFromStream(value);
+    return Effect.succeed(value);
+}
+/**
+ * Combines hydrated refs into one serialization and restoration boundary.
+ *
+ * @remarks
+ * ## Why
+ *
+ * Combines member metadata so several refs serialize and restore as one boundary while retaining
+ * each member's errors and codec services.
+ *
+ * ## Ownership and lifetime
+ *
+ * The combined boundary acquires nothing and delegates lifetime to its member refs. Encoding or
+ * decoding retains the members' Schema errors and services.
+ *
+ * Named attributes must be unique. Unnamed members are encoded together and restored as a group,
+ * so normal initializers cannot race ahead of a partially decoded envelope.
+ *
+ * ## Synchronous configuration errors
+ *
+ * Combining two named refs whose normalized `data-*` attribute names are equal throws `TypeError`
+ * immediately while `hydrateAll` is called. This duplicate-name check is a configuration error,
+ * not a typed Schema failure. Member encoding and decoding errors remain `Schema.SchemaError`, and
+ * their codec services remain visible in the returned `HydrationRef`.
+ *
+ * @example
+ * ```ts
+ * import { Effect, Schema } from "effect"
+ * import * as Hydration from "@typed/fx/RefSubject"
+ *
+ * const attributes = Effect.scoped(Effect.gen(function* () {
+ *   const count = yield* Hydration.hydrate(Schema.Finite, 0)
+ *   const status = yield* Hydration.hydrate(Schema.String, "ready")
+ *   const state = Hydration.hydrateAll(count, status)
+ *   return yield* state[Hydration.HydrationRefTypeId].toAttributes
+ * }))
+ * ```
+ *
+ * @since 2.0.0
+ * @category Hydration construction
+ */
+export function hydrateAll(...refs) {
+    return makeHydrationRef(refs.flatMap((ref) => ref[HydrationRefTypeId].members));
+}
+function makeHydrationRef(members) {
+    const unnamed = members.filter((member) => member.attributeName === undefined);
+    const named = members.filter((member) => member.attributeName !== undefined);
+    const names = new Set();
+    for (const member of named) {
+        const attributeName = member.attributeName;
+        if (names.has(attributeName)) {
+            throw new TypeError(`Duplicate hydration attribute: ${attributeName}`);
+        }
+        names.add(attributeName);
+    }
+    const tuple = Schema.Tuple(unnamed.map((member) => member.schema));
+    const envelope = Schema.Struct({
+        version: Schema.Literal(1),
+        values: tuple,
+    });
+    const codec = Schema.fromJsonString(Schema.toCodecJson(envelope));
+    const server = Effect.asVoid(allUnbounded(members.map((member) => member.server)));
+    const attributeEffects = [
+        ...(unnamed.length === 0
+            ? []
+            : [
+                Effect.flatMap(allUnbounded(unnamed.map((member) => member.ref)), (values) => Effect.map(Schema.encodeEffect(codec)({ version: 1, values }), (value) => ({
+                    name: HYDRATION_ATTRIBUTE,
+                    value,
+                }))),
+            ]),
+        ...named.map((member) => Effect.flatMap(member.ref, (value) => Effect.map(encodeMember(member, value), (value) => ({
+            name: member.attributeName,
+            value,
+        })))),
+    ];
+    const toAttributes = Effect.andThen(server, allUnbounded(attributeEffects));
+    const hydrateUnnamed = (element) => {
+        if (unnamed.length === 0)
+            return Effect.void;
+        const encoded = element.getAttribute(HYDRATION_ATTRIBUTE);
+        if (encoded === null) {
+            return Effect.asVoid(allUnbounded(unnamed.map((member) => member.server)));
+        }
+        return Effect.matchEffect(Schema.decodeEffect(codec)(encoded), {
+            onFailure: (error) => Effect.asVoid(allUnbounded(unnamed.map((member) => member.hydrate(Effect.fail(error))))),
+            onSuccess: ({ values }) => Effect.andThen(allUnbounded(unnamed.map((member, index) => member.hydrate(Effect.succeed(values[index])))), Effect.sync(() => element.removeAttribute(HYDRATION_ATTRIBUTE))),
+        });
+    };
+    const hydrateNamed = (member, element) => {
+        const attributeName = member.attributeName;
+        const encoded = element.getAttribute(attributeName);
+        if (encoded !== null) {
+            return Effect.matchEffect(decodeMember(member, encoded), {
+                onFailure: (error) => member.hydrate(Effect.fail(error)),
+                onSuccess: (value) => member.hydrate(Effect.succeed(value)),
+            });
+        }
+        return Effect.andThen(member.server, Effect.matchCauseEffect(member.ref, {
+            onFailure: () => Effect.void,
+            onSuccess: (value) => writeNamed(member, element, value),
+        }));
+    };
+    const hydrateElement = (element) => Effect.andThen(allUnbounded([
+        hydrateUnnamed(element),
+        ...named.map((member) => hydrateNamed(member, element)),
+    ]), Effect.asVoid(allUnbounded(named.map((member) => Effect.forkScoped(synchronizeNamed(member, element))))));
+    return Object.assign(hydrateElement, {
+        [HydrationRefTypeId]: { members, server, toAttributes },
+    });
+}
+function encodeMember(member, value) {
+    return Schema.encodeEffect(member.schema)(value);
+}
+function decodeMember(member, value) {
+    return Schema.decodeEffect(member.schema)(value);
+}
+function writeAttribute(element, name, value) {
+    return Effect.sync(() => {
+        if (element.getAttribute(name) !== value)
+            element.setAttribute(name, value);
+    });
+}
+function writeNamed(member, element, value) {
+    return Effect.matchEffect(encodeMember(member, value), {
+        onFailure: (error) => member.ref.onFailure(Cause.fail(error)),
+        onSuccess: (encoded) => writeAttribute(element, member.attributeName, encoded),
+    });
+}
+function synchronizeNamed(member, element) {
+    return member.ref.run(Sink.make(() => Effect.void, (value) => writeNamed(member, element, value)));
+}