npm - @jay-framework/fullstack-component - Versions diffs - 0.15.5 → 0.16.0 - Mend

@jay-framework/fullstack-component 0.15.5 → 0.16.0

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 (3) hide show

package/dist/index.d.ts CHANGED Viewed

@@ -88,6 +88,19 @@ interface Redirect3xx {
     location: string;
     message?: string;
 }
+/**
+ * A tag to inject into the HTML <head> during SSR (Design Log #127).
+ * Components return these from phaseOutput() to control page metadata (title, meta, link, etc.).
+ * Head tags are SSR-only — not hydrated on the client.
+ */
+interface HeadTag {
+    /** Element name, e.g. 'title', 'meta', 'link' */
+    tag: string;
+    /** HTML attributes, e.g. { name: 'description', content: '...' } */
+    attrs?: Record<string, string>;
+    /** Text content, e.g. 'My Page Title' for <title> */
+    children?: string;
+}
 /**
  * Successful output of a rendering phase.
  * Contains the rendered ViewState and data to carry forward to the next phase.
@@ -96,6 +109,8 @@ interface PhaseOutput<ViewState extends object, CarryForward = {}> {
     kind: 'PhaseOutput';
     rendered: ViewState;
     carryForward: CarryForward;
+    /** Tags to inject into <head> during SSR (Design Log #127). */
+    headTags?: HeadTag[];
 }
 /**
  * @deprecated Use PhaseOutput instead. PartialRender is kept for backwards compatibility.
@@ -181,8 +196,11 @@ declare function forbidden(message?: string, details?: Record<string, unknown>):
 declare function redirect3xx(status: number, location: string, message?: string): Redirect3xx;
 /**
  * Create a successful phase output with rendered ViewState and carry-forward data.
+ * Optionally include head tags to inject into <head> during SSR (Design Log #127).
  */
-declare function phaseOutput<ViewState extends object, CarryForward = {}>(rendered: ViewState, carryForward: CarryForward): PhaseOutput<ViewState, CarryForward>;
+declare function phaseOutput<ViewState extends object, CarryForward = {}>(rendered: ViewState, carryForward: CarryForward, options?: {
+    headTags?: HeadTag[];
+}): PhaseOutput<ViewState, CarryForward>;
 /**
  * @deprecated Use phaseOutput instead. Kept for backwards compatibility.
  */
@@ -410,6 +428,7 @@ declare class RenderPipeline<T, TargetVS extends object = object, TargetCF exten
     toPhaseOutput(fn: (value: T) => {
         viewState: TargetVS;
         carryForward: TargetCF;
+        headTags?: HeadTag[];
     }): Promise<RenderOutcome<TargetVS, TargetCF>>;
     /** Check if this pipeline is in a success state */
     isOk(): boolean;
@@ -551,6 +570,69 @@ type ActionOutput<T> = T extends JayAction<any, infer O> ? O : never;
  * Check if a value is a JayAction.
  */
 declare function isJayAction(value: unknown): value is JayAction<unknown, unknown>;
+/**
+ * A callable streaming action that returns an async iterable of chunks.
+ * Server handler is an async generator; client receives chunks via NDJSON.
+ */
+interface JayStreamAction<Input, Chunk> {
+    /** Call the action — returns async iterable of chunks */
+    (input: Input): AsyncIterable<Chunk>;
+    /** Unique action name for routing */
+    readonly actionName: string;
+    /** HTTP method (always POST for streaming) */
+    readonly method: 'POST';
+    /** Streaming flag */
+    readonly isStreaming: true;
+    /** Internal marker for type identification */
+    readonly _brand: 'JayStreamAction';
+}
+/**
+ * Internal definition for server-side registration of streaming actions.
+ */
+interface JayStreamActionDefinition<Input, Chunk, Services extends any[]> {
+    actionName: string;
+    method: 'POST';
+    isStreaming: true;
+    services: ServiceMarkers<Services>;
+    handler: (input: Input, ...services: Services) => AsyncIterable<Chunk>;
+}
+/**
+ * Builder interface for streaming actions.
+ */
+interface JayStreamBuilder<Services extends any[]> {
+    withServices<NewServices extends any[]>(...services: ServiceMarkers<NewServices>): JayStreamBuilder<NewServices>;
+    withHandler<I, C>(handler: (input: I, ...services: Services) => AsyncIterable<C>): JayStreamAction<I, C> & JayStreamActionDefinition<I, C, Services>;
+}
+/**
+ * Create a streaming action that yields chunks via an async generator.
+ * Use for paginated data, long-running operations, or any streaming response.
+ *
+ * @param name - Unique action name (e.g., 'routes.discoverParams')
+ *
+ * @example
+ * ```typescript
+ * export const discoverParams = makeJayStream('routes.discoverParams')
+ *     .withServices(PRODUCTS_SERVICE)
+ *     .withHandler(async function* (input: { route: string }, productsService) {
+ *         let page = 1;
+ *         while (true) {
+ *             const products = await productsService.list({ page, pageSize: 100 });
+ *             yield products.map(p => ({ slug: p.slug }));
+ *             if (!products.hasMore) break;
+ *             page++;
+ *         }
+ *     });
+ * ```
+ */
+declare function makeJayStream(name: string): JayStreamBuilder<[]>;
+/**
+ * Check if a value is a JayStreamAction.
+ */
+declare function isJayStreamAction(value: unknown): value is JayStreamAction<unknown, unknown>;
+/**
+ * Extract the chunk type from a JayStreamAction.
+ */
+type StreamChunk<T> = T extends JayStreamAction<any, infer C> ? C : never;
 /**
  * Builder for plugin/project initialization with type-safe server-to-client data flow.
@@ -654,4 +736,4 @@ declare function makeJayInit(key?: string): JayInitBuilder<void>;
  */
 declare function isJayInit(obj: unknown): obj is JayInit<any>;
-export { ActionError, type ActionInput, type ActionOutput, type AnyFastRenderResult, type AnyJayStackComponentDefinition, type AnySlowlyRenderResult, type Builder, type CacheOptions, type ClientError4xx, type ContractGeneratorFunction, type DynamicContractGenerator, type DynamicContractProps, type FastRenderResult, type GeneratedContractYaml, type HttpMethod, type JayAction, type JayActionBuilder, type JayActionDefinition, type JayInit, type JayInitBuilder, type JayInitBuilderWithServer, type JayStackComponentDefinition, type LoadParams, type PageProps, type PartialRender, type PhaseOutput, type PipelineFactory, type Redirect3xx, type RenderFast, type RenderOutcome, RenderPipeline, type RenderSlowly, type RequestQuery, type ServerError5xx, type ServiceInstances, type ServiceMarker, type ServiceMarkers, type Signals, type SlowlyRenderResult, type UrlParams, badRequest, clientError4xx, createJayService, forbidden, isJayAction, isJayInit, makeContractGenerator, makeJayAction, makeJayInit, makeJayQuery, makeJayStackComponent, notFound, partialRender, phaseOutput, redirect3xx, serverError5xx, unauthorized };
+export { ActionError, type ActionInput, type ActionOutput, type AnyFastRenderResult, type AnyJayStackComponentDefinition, type AnySlowlyRenderResult, type Builder, type CacheOptions, type ClientError4xx, type ContractGeneratorFunction, type DynamicContractGenerator, type DynamicContractProps, type FastRenderResult, type GeneratedContractYaml, type HeadTag, type HttpMethod, type JayAction, type JayActionBuilder, type JayActionDefinition, type JayInit, type JayInitBuilder, type JayInitBuilderWithServer, type JayStackComponentDefinition, type JayStreamAction, type JayStreamActionDefinition, type JayStreamBuilder, type LoadParams, type PageProps, type PartialRender, type PhaseOutput, type PipelineFactory, type Redirect3xx, type RenderFast, type RenderOutcome, RenderPipeline, type RenderSlowly, type RequestQuery, type ServerError5xx, type ServiceInstances, type ServiceMarker, type ServiceMarkers, type Signals, type SlowlyRenderResult, type StreamChunk, type UrlParams, badRequest, clientError4xx, createJayService, forbidden, isJayAction, isJayInit, isJayStreamAction, makeContractGenerator, makeJayAction, makeJayInit, makeJayQuery, makeJayStackComponent, makeJayStream, notFound, partialRender, phaseOutput, redirect3xx, serverError5xx, unauthorized };

package/dist/index.js CHANGED Viewed

@@ -40,8 +40,13 @@ function redirect3xx(status, location, message) {
     message
   };
 }
-function phaseOutput(rendered, carryForward) {
-  return { kind: "PhaseOutput", rendered, carryForward };
+function phaseOutput(rendered, carryForward, options) {
+  return {
+    kind: "PhaseOutput",
+    rendered,
+    carryForward,
+    ...options?.headTags && { headTags: options.headTags }
+  };
 }
 function partialRender(rendered, carryForward) {
   return phaseOutput(rendered, carryForward);
@@ -61,6 +66,7 @@ class BuilderImplementation {
     __publicField(this, "fastRender");
     __publicField(this, "comp");
     __publicField(this, "clientDefaults");
+    this.comp = () => ({ render: () => ({}) });
   }
   withProps() {
     return this;
@@ -331,8 +337,8 @@ class RenderPipeline {
     if (isErrorOutcome(resolvedValue)) {
       return resolvedValue;
     }
-    const { viewState, carryForward } = fn(resolvedValue);
-    return phaseOutput(viewState, carryForward);
+    const { viewState, carryForward, headTags } = fn(resolvedValue);
+    return phaseOutput(viewState, carryForward, headTags ? { headTags } : void 0);
   }
   // =========================================================================
   // Utility Methods
@@ -405,6 +411,42 @@ function makeJayQuery(name) {
 function isJayAction(value) {
   return typeof value === "function" && value._brand === "JayAction" && typeof value.actionName === "string";
 }
+class JayStreamBuilderImpl {
+  constructor(_actionName) {
+    __publicField(this, "_services", []);
+    this._actionName = _actionName;
+  }
+  withServices(...services) {
+    this._services = services;
+    return this;
+  }
+  withHandler(handler) {
+    const actionName = this._actionName;
+    const serviceMarkers = this._services;
+    const action = Object.assign(
+      (input) => {
+        const resolver = globalThis.__JAY_SERVICE_RESOLVER__;
+        const resolvedServices = resolver ? resolver(serviceMarkers) : [];
+        return handler(input, ...resolvedServices);
+      },
+      {
+        actionName,
+        method: "POST",
+        isStreaming: true,
+        services: serviceMarkers,
+        handler,
+        _brand: "JayStreamAction"
+      }
+    );
+    return action;
+  }
+}
+function makeJayStream(name) {
+  return new JayStreamBuilderImpl(name);
+}
+function isJayStreamAction(value) {
+  return typeof value === "function" && value._brand === "JayStreamAction" && typeof value.actionName === "string";
+}
 function makeJayInit(key) {
   const resolvedKey = key ?? "__JAY_INIT_KEY__";
   return {
@@ -449,11 +491,13 @@ export {
   forbidden,
   isJayAction,
   isJayInit,
+  isJayStreamAction,
   makeContractGenerator,
   makeJayAction,
   makeJayInit,
   makeJayQuery,
   makeJayStackComponent,
+  makeJayStream,
   notFound,
   partialRender,
   phaseOutput,

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@jay-framework/fullstack-component",
-  "version": "0.15.5",
+  "version": "0.16.0",
   "type": "module",
   "license": "Apache-2.0",
   "main": "dist/index.js",
@@ -26,12 +26,12 @@
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@jay-framework/component": "^0.15.5",
-    "@jay-framework/runtime": "^0.15.5"
+    "@jay-framework/component": "^0.16.0",
+    "@jay-framework/runtime": "^0.16.0"
   },
   "devDependencies": {
-    "@jay-framework/dev-environment": "^0.15.5",
-    "@jay-framework/jay-cli": "^0.15.5",
+    "@jay-framework/dev-environment": "^0.16.0",
+    "@jay-framework/jay-cli": "^0.16.0",
     "@types/express": "^5.0.2",
     "@types/node": "^22.15.21",
     "nodemon": "^3.0.3",