foldkit 0.146.0 → 0.148.0

package/dist/experimental/server/server.d.ts

@@ -0,0 +1,242 @@
+import { Effect, Schema } from 'effect';
+import { type Document, type HtmlBuilder } from '../../html/index.js';
+import { FOLDKIT_APP_ATTRIBUTE, FOLDKIT_FLAGS_ATTRIBUTE } from '../../hydrationMarker.js';
+import { Url } from '../../url/index.js';
+export declare const __assertNoDeclarativeShadowRoot: (html: string) => void;
+export declare const __assertNoLiveBaseElement: (html: string) => void;
+export declare const __assertNoDocumentStructureEscape: (html: string) => void;
+export { FOLDKIT_APP_ATTRIBUTE, FOLDKIT_FLAGS_ATTRIBUTE };
+/** The server render of one request: the stamped root markup (plus the Flags
+ *  payload script when the application declares Flags) and the `Document`
+ *  head fields for the host to place into its HTML template.
+ *
+ * @experimental Ships from `foldkit/experimental/server`; expect breaking changes while the API settles.
+ */
+export type RenderedApplication = Readonly<{
+    html: string;
+    title: string;
+    lang?: string;
+    dir?: 'ltr' | 'rtl' | 'auto';
+    canonical?: string;
+    ogUrl?: string;
+}>;
+declare const InvalidUrl_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "InvalidUrl";
+} & Readonly<A>;
+/** Failure of a routing render whose `url` option cannot be parsed.
+ *
+ * @experimental Ships from `foldkit/experimental/server`; expect breaking changes while the API settles.
+ */
+export declare class InvalidUrl extends InvalidUrl_base<{
+    url: string;
+}> {
+}
+declare const FlagsEncodeError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "FlagsEncodeError";
+} & Readonly<A>;
+/** Failure producing the Flags payload: the Schema encode step rejected the
+ *  Flags value, the encoded value could not be serialized to JSON, or the
+ *  encoded value could not be decoded back for the hydration-consistent
+ *  render.
+ *
+ * @experimental Ships from `foldkit/experimental/server`; expect breaking changes while the API settles.
+ */
+export declare class FlagsEncodeError extends FlagsEncodeError_base<{
+    cause: unknown;
+}> {
+}
+declare const SerializationError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "SerializationError";
+} & Readonly<A>;
+/** Failure serializing the view-produced vnode tree to safe HTML.
+ *
+ * @experimental Ships from `foldkit/experimental/server`; expect breaking changes while the API settles.
+ */
+export declare class SerializationError extends SerializationError_base<{
+    cause: unknown;
+}> {
+}
+declare const InvalidRuntimeId_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "InvalidRuntimeId";
+} & Readonly<A>;
+/** Failure of a render whose `runtimeId` is empty.
+ *
+ * @experimental Ships from `foldkit/experimental/server`; expect breaking changes while the API settles.
+ */
+export declare class InvalidRuntimeId extends InvalidRuntimeId_base<{
+    runtimeId: string;
+}> {
+}
+declare const InvalidHydrationRoot_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "InvalidHydrationRoot";
+} & Readonly<A>;
+/** Failure of a hydratable render whose view did not return an element root.
+ * Text, comments, and an empty body cannot carry the hydration marker the
+ * client runtime uses to adopt the server-rendered DOM.
+ *
+ * @experimental Ships from `foldkit/experimental/server`; expect breaking changes while the API settles.
+ */
+export declare class InvalidHydrationRoot extends InvalidHydrationRoot_base<{
+    rootKind: 'Empty' | 'Text' | 'Comment';
+}> {
+}
+declare const MissingBuildId_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "MissingBuildId";
+} & Readonly<A>;
+/** Failure of a hydratable render that was given no build id. Hydration
+ * compares the id on the served root with the client's own to refuse a page
+ * from another deployment, so a render that carries none has no such
+ * protection. Supply one from a value the deployment already has, such as a
+ * commit or a release tag, through `@foldkit/vite-plugin`'s `buildId` option or
+ * the `FOLDKIT_BUILD_ID` environment variable, and pass
+ * `import.meta.env.FOLDKIT_BUILD_ID` to `renderToString` and `Runtime.hydrate`.
+ * A render that nothing will hydrate (`isHydratable: false`) needs none.
+ *
+ * @experimental Ships from `foldkit/experimental/server`; expect breaking changes while the API settles.
+ */
+export declare class MissingBuildId extends MissingBuildId_base<{}> {
+}
+/** Union of the failures {@link renderToString} can produce.
+ *
+ * @experimental Ships from `foldkit/experimental/server`; expect breaking changes while the API settles.
+ */
+export type RenderError = MissingBuildId | InvalidUrl | FlagsEncodeError | SerializationError | InvalidRuntimeId | InvalidHydrationRoot;
+type InitReturn<Model> = readonly [Model, ReadonlyArray<unknown>];
+/** Server-side subset of a routing `makeApplication` config with Flags. The
+ *  full application config is structurally assignable; `container`, `update`,
+ *  and `subscriptions` play no part in a server render.
+ *
+ * @experimental Ships from `foldkit/experimental/server`; expect breaking changes while the API settles.
+ */
+export type RoutingApplicationConfigWithFlags<Model, Message, Flags> = Readonly<{
+    Flags: Schema.Codec<Flags, any, never, never>;
+    routing: unknown;
+    init: (flags: Flags, url: Url) => InitReturn<Model>;
+    view: (model: Model, h: HtmlBuilder<Message>) => Document;
+}>;
+/** Server-side subset of a routing `makeApplication` config without Flags.
+ *
+ * @experimental Ships from `foldkit/experimental/server`; expect breaking changes while the API settles.
+ */
+export type RoutingApplicationConfig<Model, Message> = Readonly<{
+    routing: unknown;
+    init: (url: Url) => InitReturn<Model>;
+    view: (model: Model, h: HtmlBuilder<Message>) => Document;
+}>;
+/** Server-side subset of a non-routing `makeApplication` config with Flags.
+ *
+ * @experimental Ships from `foldkit/experimental/server`; expect breaking changes while the API settles.
+ */
+export type ApplicationConfigWithFlags<Model, Message, Flags> = Readonly<{
+    Flags: Schema.Codec<Flags, any, never, never>;
+    init: (flags: Flags) => InitReturn<Model>;
+    view: (model: Model, h: HtmlBuilder<Message>) => Document;
+}>;
+/** Server-side subset of a non-routing `makeApplication` config.
+ *
+ * @experimental Ships from `foldkit/experimental/server`; expect breaking changes while the API settles.
+ */
+export type ApplicationConfig<Model, Message> = Readonly<{
+    init: () => InitReturn<Model>;
+    view: (model: Model, h: HtmlBuilder<Message>) => Document;
+}>;
+type CommonRenderOptions = Readonly<{
+    runtimeId?: string;
+}>;
+/** Render options for output a client will hydrate, which is the default. The
+ *  build id is required here: hydration compares it against the client's own
+ *  before adopting any DOM, and a page carrying none has no such protection.
+ *
+ * @experimental Ships from `foldkit/experimental/server`; expect breaking changes while the API settles.
+ */
+export type HydratableRenderOptions = CommonRenderOptions & Readonly<{
+    isHydratable?: true;
+    /**
+     * The deployment this render belongs to, stamped on the root so hydration
+     * can refuse a page from a different one before adopting its DOM. Pass
+     * `import.meta.env.FOLDKIT_BUILD_ID`, which `@foldkit/vite-plugin` fills
+     * from its `buildId` option or the `FOLDKIT_BUILD_ID` environment variable,
+     * and give the client entry the same value.
+     */
+    buildId: string;
+}>;
+/** Render options for static markup nothing will hydrate. No build id applies,
+ *  because no client will compare one.
+ *
+ * @experimental Ships from `foldkit/experimental/server`; expect breaking changes while the API settles.
+ */
+export type StaticRenderOptions = CommonRenderOptions & Readonly<{
+    isHydratable: false;
+    buildId?: undefined;
+}>;
+/** Options for {@link renderToString}. `runtimeId` names the application in the
+ *  root stamp and Flags payload; it defaults to `'app'` and must be non-empty.
+ *
+ *  A hydratable render (the default) requires `buildId`. Pass
+ *  `isHydratable: false` for static markup that nothing will hydrate, which
+ *  takes no build id.
+ *
+ * @experimental Ships from `foldkit/experimental/server`; expect breaking changes while the API settles.
+ */
+export type RenderOptions = HydratableRenderOptions | StaticRenderOptions;
+/** Render options for a routing application, adding the request URL.
+ *
+ * @experimental Ships from `foldkit/experimental/server`; expect breaking changes while the API settles.
+ */
+export type RenderUrlOptions = RenderOptions & Readonly<{
+    url: string;
+}>;
+/** Render options for a Flags application, adding the per-request Flags.
+ *
+ * @experimental Ships from `foldkit/experimental/server`; expect breaking changes while the API settles.
+ */
+export type RenderFlagsOptions<Flags> = RenderOptions & Readonly<{
+    flags: Flags;
+}>;
+/** Render options for a routing Flags application: the request URL plus the
+ *  per-request Flags.
+ *
+ * @experimental Ships from `foldkit/experimental/server`; expect breaking changes while the API settles.
+ */
+export type RenderUrlFlagsOptions<Flags> = RenderUrlOptions & RenderFlagsOptions<Flags>;
+/**
+ * Renders a `makeApplication`-shaped config to an HTML string on the server.
+ *
+ * Resolves `init` for the request (with the given Flags and URL when the
+ * config declares them), runs the pure `view` under a no-op dispatch frame,
+ * and serializes the resulting `Document` body. The root element is stamped
+ * with {@link FOLDKIT_APP_ATTRIBUTE} and, when the config declares `Flags`,
+ * the Schema-encoded Flags ride along in a JSON script tag so a hydrating
+ * client boots from the same Model.
+ *
+ * Commands returned by `init` are not run: the rendered HTML is the
+ * post-`init` state, and the client runs those Commands after hydration.
+ *
+ * A hydratable Flags render calls `init` with the encode-then-decode round
+ * trip of the given Flags, the exact value the hydrating client will
+ * reconstruct, so the served DOM and the client's first render agree by
+ * construction even for codecs whose round trip is not the identity.
+ *
+ * When a routing view omits `Document.canonical`, the render defaults it (and
+ * `ogUrl`) to the request URL, normalized the way the client computes the
+ * current location but with the query string kept. Set `Document.canonical`
+ * explicitly when the query string is not part of the page's identity, such as
+ * tracking parameters or a session token, so a crawler does not index every
+ * variant as its own canonical page.
+ *
+ * @example
+ * ```typescript
+ * const renderedApplication = yield* Server.renderToString(config, {
+ *   url: request.url,
+ *   flags: { theme },
+ *   buildId: import.meta.env.FOLDKIT_BUILD_ID,
+ * })
+ * ```
+ *
+ * @experimental Ships from `foldkit/experimental/server`; expect breaking changes while the API settles.
+ */
+export declare function renderToString<Model, Message, Flags>(config: RoutingApplicationConfigWithFlags<Model, Message, Flags>, options: RenderUrlFlagsOptions<Flags>): Effect.Effect<RenderedApplication, RenderError>;
+export declare function renderToString<Model, Message>(config: RoutingApplicationConfig<Model, Message>, options: RenderUrlOptions): Effect.Effect<RenderedApplication, RenderError>;
+export declare function renderToString<Model, Message, Flags>(config: ApplicationConfigWithFlags<Model, Message, Flags>, options: RenderFlagsOptions<Flags>): Effect.Effect<RenderedApplication, RenderError>;
+export declare function renderToString<Model, Message>(config: ApplicationConfig<Model, Message>, options: RenderOptions): Effect.Effect<RenderedApplication, RenderError>;
+//# sourceMappingURL=server.d.ts.map

package/dist/experimental/server/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../../src/experimental/server/server.ts"],"names":[],"mappings":"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"}