npm - @estjs/server - Versions diffs - 0.0.15 → 0.0.16-beta.2 - Mend

@estjs/server 0.0.15 → 0.0.16-beta.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (11) hide show

package/dist/server.cjs.js +2 -1
package/dist/server.cjs.js.map +1 -1
package/dist/server.d.cts +166 -26
package/dist/server.d.ts +166 -26
package/dist/server.dev.cjs.js +401 -0
package/dist/server.dev.cjs.js.map +1 -0
package/dist/server.dev.esm.js +368 -0
package/dist/server.dev.esm.js.map +1 -0
package/dist/server.esm.js +2 -1
package/dist/server.esm.js.map +1 -1
package/package.json +4 -3

package/dist/server.d.ts CHANGED Viewed

@@ -1,50 +1,109 @@
 import { ComponentProps, ComponentFn } from '@estjs/template';
+export { getHydrationKey, resetHydrationKey } from '@estjs/template';
 export { escapeHTML } from '@estjs/shared';
 /**
- * Render a component to HTML string
- * @param {ComponentFn} component - the component to render
- * @param {ComponentProps} props - the props to pass to the component
- * @returns {string} the rendered HTML string
+ * SSR rendering context.
+ */
+interface SSRContext {
+    /**
+     * Map of teleport target → concatenated HTML string. The caller is
+     * responsible for inlining each entry into the final document
+     * (e.g. by replacing a placeholder in a shell template).
+     */
+    teleports: Record<string, string>;
+    /**
+     * Free-form key/value bag for user-defined per-render metadata
+     * (e.g. collected `<head>` tags, status codes, response headers).
+     */
+    [key: string]: unknown;
+}
+/**
+ * Create an empty SSR context with all collection slots initialised.
  */
-declare function renderToString<P extends ComponentProps = ComponentProps>(component: ComponentFn<P>, props?: P | ComponentProps): string;
+declare function createSSRContext(): SSRContext;
+/**
+ * Get the current SSR context, if any. Returns `null` when called outside of
+ * a `renderToString` invocation, or when the caller did not pass a context.
+ */
+declare function getSSRContext(): SSRContext | null;
 /**
- * Render template with components (used by babel plugin in SSG mode)
- * @param {string[]} templates - the template fragments
- * @param {string} hydrationKey - the hydration key
- * @param {...string[]} components - the rendered component strings
- * @returns {string} the rendered HTML string
+ * Render a component to HTML string.
+ *
+ * Each invocation runs inside its own root scope so that `provide()` calls
+ * stay isolated between independent `renderToString` calls.
+ *
+ * @param component - The component to render.
+ * @param props - The props to pass to the component.
+ * @param context - Optional {@link SSRContext} that collects out-of-tree
+ *   render output (currently: `Portal`/`Teleport` content). The same context
+ *   is visible to nested `createSSGComponent` calls; the caller integrates
+ *   `context.teleports[selector]` into the final document.
+ * @returns {string} The rendered HTML string.
+ */
+declare function renderToString<P extends ComponentProps = ComponentProps>(component: ComponentFn<P>, props?: P | ComponentProps, context?: SSRContext | null): string;
+/**
+ * Render template with components (used by babel plugin in SSG mode).
+ *
+ * @param templates - The template fragments.
+ * @param hydrationKey - The hydration key.
+ * @param components - The rendered component strings.
+ * @returns {string} The rendered HTML string.
  */
 declare function render(templates: string[], hydrationKey: string, ...components: string[]): string;
 /**
- * Create a SSG component (renders component to string)
- * @param {ComponentFn} component - the component to create
- * @param {ComponentProps} props - the props to pass to the component
- * @returns {string} the rendered component as a string
+ * Async variant of {@link renderToString}. Awaits component results so that
+ * `async` components and promise-returning expressions can participate in SSR.
+ *
+ * The awaited value is passed through the same {@link convertToString}
+ * pipeline as the synchronous path, which itself transparently awaits any
+ * nested promises (arrays of promises, promise-returning thunks, etc.).
+ */
+declare function renderToStringAsync<P extends ComponentProps = ComponentProps>(component: ComponentFn<P>, props?: P | ComponentProps, context?: SSRContext | null): Promise<string>;
+/**
+ * Create a SSG component (renders component to string).
+ *
+ * The component executes inside a child scope that inherits from the current
+ * active scope, so `inject()` calls can resolve values from ancestor
+ * `provide()` calls, and `provide()` inside the component is scoped to it.
+ *
+ * @param component - The component to create.
+ * @param props - The props to pass to the component.
+ * @returns {string} The rendered component as a string.
  */
 declare function createSSGComponent<P extends ComponentProps = ComponentProps>(component: ComponentFn<P>, props?: P | ComponentProps): string;
 /**
- * Convert content to string for SSR output
+ * Convert content to string for SSR output.
  *
- * @param content - the content to convert
- * @param isSvg - whether the content is SVG
- * @returns the content as a string
+ * @param content - The content to convert.
+ * @param isSvg - Whether the content is SVG.
+ * @returns {string} The content as a string.
  */
 declare function convertToString(content: unknown, isSvg?: boolean): string;
 /**
- * Add hydration attributes to HTML content
+ * Convert child-expression content to escaped text for SSR output.
  *
- * @param htmlContent - the html content
- * @param hydrationId - the hydration id
- * @returns the html content with hydration attributes
+ * JSX expression children have text semantics, so primitives must be escaped
+ * before interpolation into the surrounding HTML template.
+ */
+declare function convertTextChildToString(content: unknown): string;
+/**
+ * Add hydration attributes to HTML content.
+ *
+ * @param htmlContent - The html content.
+ * @param hydrationId - The hydration id.
+ * @returns {string} The html content with hydration attributes.
  */
 declare function addAttributes(htmlContent: string, hydrationId: string): string;
 /**
  * Normalize component properties
  *
- * Special handling for class and style attributes, converting them to normalized format
+ * Special handling for class and style attributes, converting them to normalized format.
+ * Returns a new object when normalization is needed, preserving the original.
  *
  * @param props - Original component properties
  * @returns Normalized component properties
@@ -61,9 +120,90 @@ declare function normalizeProps(props: Record<string, any> | null): Record<strin
  *
  * @param attrName - Attribute name
  * @param attrValue - Attribute value
- * @param hydrationId - Hydration ID (for client-side reuse)
  * @returns Formatted HTML attribute string
  */
-declare function setSSGAttr(attrName: string, attrValue: any, hydrationId: string): string;
+declare function setSSGAttr(attrName: string, attrValue: any): string;
+/**
+ * Render a single attribute as an HTML attribute string.
+ *
+ * @param name - The name of the attribute.
+ * @param value - The value of the attribute.
+ * @returns {string} The rendered attribute string (e.g., ` name="value"`).
+ */
+declare function ssrAttr(name: string, value: unknown): string;
+/**
+ * Render a `class` attribute as an HTML attribute string.
+ *
+ * @param value - The class value (string, object, or array).
+ * @returns {string} The rendered class attribute string.
+ */
+declare function ssrClass(value: unknown): string;
+/**
+ * Render a `style` attribute as an HTML attribute string.
+ *
+ * @param value - The style value (string or object).
+ * @returns {string} The rendered style attribute string.
+ */
+declare function ssrStyle(value: unknown): string;
+/**
+ * Render a spread of props as HTML attribute strings.
+ * Skips event handlers and special keys.
+ *
+ * @param props - The props object to spread.
+ * @returns {string} The rendered attribute strings.
+ */
+declare function ssrSpread(props: Record<string, unknown>): string;
+interface SSRComponentProps {
+    children?: unknown;
+    [key: string]: unknown;
+}
+/**
+ * SSR Fragment — returns children converted to a string.
+ */
+declare function Fragment(props: SSRComponentProps): string;
+interface SSRPortalProps extends SSRComponentProps {
+    /**
+     * Teleport target — only CSS selector strings are meaningful on the server.
+     * Element references are silently inlined (they have no server-side meaning).
+     */
+    target?: string;
+    /**
+     * When truthy, children render inline instead of being teleported.
+     * The babel plugin resolves reactive getters before reaching the component,
+     * so only a plain boolean is needed on the server.
+     */
+    disabled?: boolean | (() => boolean);
+}
+declare const TELEPORT_CALLSITE_ANCHOR = "<!--teleport-anchor-->";
+declare const TELEPORT_BLOCK_START = "<!--teleport-start-->";
+declare const TELEPORT_BLOCK_END = "<!--teleport-end-->";
+/**
+ * SSR Portal — collects teleported content into `ctx.teleports[target]`.
+ *
+ * Emits `<!--teleport-anchor-->` at the call site and wraps children with
+ * `<!--teleport-start-->...<!--teleport-end-->` in the target buffer.
+ * Disabled / no-target / no-context falls back to inline rendering.
+ */
+declare function Portal(props: SSRPortalProps): string;
+/**
+ * SSR Suspense — renders children when available, otherwise the fallback slot.
+ */
+declare function Suspense(props: SSRComponentProps & {
+    fallback?: unknown;
+}): string;
+interface SSRForProps<T> {
+    each: T[] | {
+        value: T[];
+    } | (() => T[]);
+    children: (item: T, index: number) => unknown;
+    key?: (item: T, index: number) => unknown;
+    fallback?: unknown;
+}
+/**
+ * SSR For — maps each item through the render function and joins the output.
+ */
+declare function For<T>(props: SSRForProps<T>): string;
-export { addAttributes, convertToString, createSSGComponent, normalizeProps, render, renderToString, setSSGAttr };
+export { For, Fragment, Portal, type SSRComponentProps, type SSRContext, type SSRForProps, type SSRPortalProps, Suspense, TELEPORT_BLOCK_END, TELEPORT_BLOCK_START, TELEPORT_CALLSITE_ANCHOR, addAttributes, convertTextChildToString, convertToString, createSSGComponent, createSSRContext, getSSRContext, normalizeProps, render, renderToString, renderToStringAsync, setSSGAttr, ssrAttr, ssrClass, ssrSpread, ssrStyle };

package/dist/server.dev.cjs.js ADDED Viewed

@@ -0,0 +1,401 @@
+'use strict';
+var shared = require('@estjs/shared');
+var template = require('@estjs/template');
+var internal = require('@estjs/template/internal');
+var async_hooks = require('async_hooks');
+var signals = require('@estjs/signals');
+var __defProp = Object.defineProperty;
+var __getOwnPropSymbols = Object.getOwnPropertySymbols;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __propIsEnum = Object.prototype.propertyIsEnumerable;
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __spreadValues = (a, b) => {
+  for (var prop in b || (b = {}))
+    if (__hasOwnProp.call(b, prop))
+      __defNormalProp(a, prop, b[prop]);
+  if (__getOwnPropSymbols)
+    for (var prop of __getOwnPropSymbols(b)) {
+      if (__propIsEnum.call(b, prop))
+        __defNormalProp(a, prop, b[prop]);
+    }
+  return a;
+};
+var __async = (__this, __arguments, generator) => {
+  return new Promise((resolve, reject) => {
+    var fulfilled = (value) => {
+      try {
+        step(generator.next(value));
+      } catch (e) {
+        reject(e);
+      }
+    };
+    var rejected = (value) => {
+      try {
+        step(generator.throw(value));
+      } catch (e) {
+        reject(e);
+      }
+    };
+    var step = (x) => x.done ? resolve(x.value) : Promise.resolve(x.value).then(fulfilled, rejected);
+    step((generator = generator.apply(__this, __arguments)).next());
+  });
+};
+function createSSRContext() {
+  return {
+    teleports: /* @__PURE__ */ Object.create(null)
+  };
+}
+var store = new async_hooks.AsyncLocalStorage();
+function getSSRContext() {
+  var _a;
+  return (_a = store.getStore()) != null ? _a : null;
+}
+function runWithSSRContext(ctx, fn) {
+  return store.run(ctx, fn);
+}
+function convertToString(content, isSvg = false) {
+  if (shared.isNil(content)) {
+    return "";
+  }
+  if (shared.isString(content)) {
+    return content;
+  }
+  if (shared.isArray(content)) {
+    return content.map((item) => convertToString(item, isSvg)).join("");
+  }
+  if (shared.isFunction(content)) {
+    return convertToString(content(), isSvg);
+  }
+  return String(content);
+}
+function convertTextChildToString(content) {
+  if (content === false || shared.isNil(content)) {
+    return "";
+  }
+  if (shared.isString(content)) {
+    return shared.escapeHTML(content);
+  }
+  if (shared.isArray(content)) {
+    return content.map((item) => convertTextChildToString(item)).join("");
+  }
+  if (shared.isFunction(content)) {
+    return convertTextChildToString(content());
+  }
+  return shared.escapeHTML(String(content));
+}
+var HYDRATION_REWRITE_REGEX = /data-idx="(\d+)"|<!--(\d+)-->/g;
+function injectRootHydrationAttribute(htmlContent, hydrationId) {
+  const tagStart = htmlContent.indexOf("<");
+  if (tagStart === -1) {
+    return htmlContent;
+  }
+  let quote;
+  for (let i = tagStart + 1; i < htmlContent.length; i++) {
+    const char = htmlContent[i];
+    if (quote) {
+      if (char === quote) {
+        quote = void 0;
+      }
+      continue;
+    }
+    if (char === '"' || char === "'") {
+      quote = char;
+      continue;
+    }
+    if (char === ">") {
+      let insertAt = i;
+      for (let j = i - 1; j > tagStart; j--) {
+        const prev = htmlContent[j];
+        if (prev === " " || prev === "\n" || prev === "	" || prev === "\r") {
+          continue;
+        }
+        if (prev === "/") {
+          insertAt = j;
+        }
+        break;
+      }
+      return `${htmlContent.slice(0, insertAt)} data-hk="${hydrationId}"${htmlContent.slice(insertAt)}`;
+    }
+  }
+  return htmlContent;
+}
+function addAttributes(htmlContent, hydrationId) {
+  return injectRootHydrationAttribute(htmlContent, hydrationId).replaceAll(
+    HYDRATION_REWRITE_REGEX,
+    (_match, dataIdx, commentBody) => dataIdx !== void 0 ? `data-idx="${hydrationId}-${dataIdx}"` : `<!--${hydrationId}-${commentBody}-->`
+  );
+}
+// src/render.ts
+function runInFreshScope(fn, parent = internal.getActiveScope()) {
+  const scope = internal.createScope(parent);
+  try {
+    return internal.runWithScope(scope, fn);
+  } finally {
+    internal.disposeScope(scope);
+  }
+}
+function renderToString(component, props = {}, context = null) {
+  if (!shared.isFunction(component)) {
+    shared.error("Component must be a function");
+    return "";
+  }
+  template.resetHydrationKey();
+  const result = runWithSSRContext(
+    context,
+    () => runInFreshScope(() => component(props), null)
+  );
+  if (shared.isPromise(result)) {
+    shared.error("renderToString received a Promise \u2014 use renderToStringAsync for async components.");
+  }
+  return convertToString(result);
+}
+function render(templates, hydrationKey, ...components) {
+  const templateLen = templates.length;
+  const componentLen = components.length;
+  let content = "";
+  for (let i = 0; i < templateLen; i++) {
+    content += templates[i];
+    if (i < componentLen && components[i]) {
+      content += convertToString(components[i]);
+    }
+  }
+  return addAttributes(content, hydrationKey);
+}
+function renderToStringAsync(_0) {
+  return __async(this, arguments, function* (component, props = {}, context = null) {
+    if (!shared.isFunction(component)) {
+      shared.error("Component must be a function");
+      return "";
+    }
+    template.resetHydrationKey();
+    const scope = internal.createScope(null);
+    try {
+      return yield runWithSSRContext(context, () => __async(null, null, function* () {
+        let result = internal.runWithScope(scope, () => component(props));
+        if (shared.isPromise(result)) {
+          result = yield result;
+        }
+        return convertToStringAsync(result);
+      }));
+    } finally {
+      internal.disposeScope(scope);
+    }
+  });
+}
+function convertToStringAsync(content) {
+  return __async(this, null, function* () {
+    if (shared.isPromise(content)) {
+      return convertToStringAsync(yield content);
+    }
+    if (Array.isArray(content)) {
+      const parts = yield Promise.all(content.map((c) => convertToStringAsync(c)));
+      return parts.join("");
+    }
+    if (shared.isFunction(content)) {
+      return convertToStringAsync(content());
+    }
+    return convertToString(content);
+  });
+}
+function createSSGComponent(component, props = {}) {
+  if (!shared.isFunction(component)) {
+    shared.error("createSSGComponent: Component is not a function");
+    return "";
+  }
+  const result = runInFreshScope(() => component(props));
+  return convertToString(result);
+}
+function normalizeProps(props) {
+  if (!props) {
+    return null;
+  }
+  const { class: className, style } = props;
+  const needsClassNorm = className && !shared.isString(className);
+  const needsStyleNorm = !!style;
+  if (!needsClassNorm && !needsStyleNorm) {
+    return props;
+  }
+  const result = __spreadValues({}, props);
+  if (needsClassNorm) {
+    result.class = shared.normalizeClassName(className);
+  }
+  if (needsStyleNorm) {
+    result.style = shared.normalizeStyle(style);
+  }
+  return result;
+}
+function setSSGAttr(attrName, attrValue) {
+  if (signals.isSignal(attrValue) || signals.isComputed(attrValue)) {
+    return setSSGAttr(attrName, attrValue.value);
+  }
+  if (!attrValue && attrValue !== 0) {
+    return "";
+  }
+  if (attrName === "style") {
+    const normalizedStyle = shared.normalizeStyle(attrValue);
+    if (!normalizedStyle) {
+      return "";
+    }
+    if (shared.isString(normalizedStyle)) {
+      return ` style="${normalizedStyle}"`;
+    }
+    return ` style="${shared.styleToString(normalizedStyle)}"`;
+  }
+  if (attrName === "class") {
+    const normalizedClassName = shared.normalizeClassName(attrValue);
+    return normalizedClassName ? ` class="${normalizedClassName}"` : "";
+  }
+  if (attrName.startsWith("on")) {
+    return "";
+  }
+  if (attrValue === true) {
+    return ` ${attrName}`;
+  }
+  return ` ${attrName}="${shared.escapeHTML(String(attrValue))}"`;
+}
+function ssrAttr(name, value) {
+  if (shared.isNil(value) || value === false) return "";
+  if (value === true) return ` ${name}`;
+  return ` ${name}="${shared.escapeHTML(String(value))}"`;
+}
+function ssrClass(value) {
+  const normalized = normalizeClassSSR(value);
+  if (!normalized) return "";
+  return ` class="${shared.escapeHTML(normalized)}"`;
+}
+function ssrStyle(value) {
+  if (shared.isNil(value)) return "";
+  if (shared.isString(value)) return value ? ` style="${shared.escapeHTML(value)}"` : "";
+  if (shared.isObject(value)) {
+    const obj = value;
+    const parts = [];
+    for (const key in obj) {
+      const v = obj[key];
+      if (v != null && v !== false) {
+        const prop = key.startsWith("--") ? key : camelToKebab(key);
+        parts.push(`${prop}:${shared.escapeHTML(String(v))}`);
+      }
+    }
+    if (!parts.length) return "";
+    return ` style="${parts.join(";")}"`;
+  }
+  return "";
+}
+function ssrSpread(props) {
+  if (!props || !shared.isObject(props)) return "";
+  let out = "";
+  for (const key in props) {
+    if (key === "children" || key === "ref" || key.startsWith("on")) continue;
+    if (key === "class" || key === "className") {
+      out += ssrClass(props[key]);
+    } else if (key === "style") {
+      out += ssrStyle(props[key]);
+    } else {
+      out += ssrAttr(key, props[key]);
+    }
+  }
+  return out;
+}
+function normalizeClassSSR(value) {
+  if (shared.isNil(value) || value === false) return "";
+  if (shared.isString(value)) return value;
+  if (shared.isArray(value)) {
+    return value.map(normalizeClassSSR).filter(Boolean).join(" ");
+  }
+  if (shared.isObject(value)) {
+    const obj = value;
+    return Object.keys(obj).filter((k) => Boolean(obj[k])).join(" ");
+  }
+  return String(value);
+}
+var UPPER_RE = /[A-Z]/g;
+function camelToKebab(str) {
+  return str.replaceAll(UPPER_RE, (m) => `-${m.toLowerCase()}`);
+}
+function Fragment(props) {
+  return convertToString(props.children);
+}
+var TELEPORT_CALLSITE_ANCHOR = "<!--teleport-anchor-->";
+var TELEPORT_BLOCK_START = "<!--teleport-start-->";
+var TELEPORT_BLOCK_END = "<!--teleport-end-->";
+function Portal(props) {
+  var _a;
+  const { target, children } = props;
+  const rendered = convertToString(children);
+  const disabled = shared.isFunction(props.disabled) ? !!props.disabled() : !!props.disabled;
+  if (disabled || !target) return rendered;
+  const ctx = getSSRContext();
+  if (!ctx) return rendered;
+  if (!shared.isString(target)) {
+    {
+      shared.warn("[Portal] SSR only supports string selector targets; rendering inline.");
+    }
+    return rendered;
+  }
+  ctx.teleports[target] = ((_a = ctx.teleports[target]) != null ? _a : "") + TELEPORT_BLOCK_START + rendered + TELEPORT_BLOCK_END;
+  return TELEPORT_CALLSITE_ANCHOR;
+}
+function Suspense(props) {
+  const { children, fallback } = props;
+  return shared.isNil(children) ? convertToString(fallback) : convertToString(children);
+}
+function resolveList(input) {
+  var _a, _b;
+  if (shared.isNil(input)) return [];
+  if (shared.isObject(input) && "value" in input) {
+    return (_a = input.value) != null ? _a : [];
+  }
+  if (shared.isFunction(input)) {
+    return (_b = input()) != null ? _b : [];
+  }
+  return input;
+}
+function For(props) {
+  const list = resolveList(props.each);
+  if (list.length === 0) {
+    return convertToString(props.fallback);
+  }
+  const render2 = props.children;
+  if (!shared.isFunction(render2)) return "";
+  return list.map((item, i) => convertToString(render2(item, i))).join("");
+}
+Object.defineProperty(exports, "escapeHTML", {
+  enumerable: true,
+  get: function () { return shared.escapeHTML; }
+});
+Object.defineProperty(exports, "getHydrationKey", {
+  enumerable: true,
+  get: function () { return template.getHydrationKey; }
+});
+Object.defineProperty(exports, "resetHydrationKey", {
+  enumerable: true,
+  get: function () { return template.resetHydrationKey; }
+});
+exports.For = For;
+exports.Fragment = Fragment;
+exports.Portal = Portal;
+exports.Suspense = Suspense;
+exports.TELEPORT_BLOCK_END = TELEPORT_BLOCK_END;
+exports.TELEPORT_BLOCK_START = TELEPORT_BLOCK_START;
+exports.TELEPORT_CALLSITE_ANCHOR = TELEPORT_CALLSITE_ANCHOR;
+exports.addAttributes = addAttributes;
+exports.convertTextChildToString = convertTextChildToString;
+exports.convertToString = convertToString;
+exports.createSSGComponent = createSSGComponent;
+exports.createSSRContext = createSSRContext;
+exports.getSSRContext = getSSRContext;
+exports.normalizeProps = normalizeProps;
+exports.render = render;
+exports.renderToString = renderToString;
+exports.renderToStringAsync = renderToStringAsync;
+exports.setSSGAttr = setSSGAttr;
+exports.ssrAttr = ssrAttr;
+exports.ssrClass = ssrClass;
+exports.ssrSpread = ssrSpread;
+exports.ssrStyle = ssrStyle;
+//# sourceMappingURL=server.dev.cjs.js.map
+//# sourceMappingURL=server.dev.cjs.js.map