npm - @jay-framework/fullstack-component - Versions diffs - 0.17.3 → 0.18.0 - Mend

@jay-framework/fullstack-component 0.17.3 → 0.18.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

@@ -67,6 +67,13 @@ interface PageProps {
 interface RequestQuery {
     query: Record<string, string>;
 }
+/**
+ * HTTP cookies parsed from the request Cookie header.
+ * Available in the fast phase only — not in the slow phase.
+ */
+interface RequestCookies {
+    cookies: Record<string, string>;
+}
 type UrlParams = Record<string, string>;
 interface ServerError5xx {
     kind: 'ServerError';
@@ -111,6 +118,8 @@ interface PhaseOutput<ViewState extends object, CarryForward = {}> {
     carryForward: CarryForward;
     /** Tags to inject into <head> during SSR (Design Log #127). */
     headTags?: HeadTag[];
+    /** HTTP response headers to set on the page response (Design Log #141). */
+    responseHeaders?: Record<string, string>;
 }
 /**
  * @deprecated Use PhaseOutput instead. PartialRender is kept for backwards compatibility.
@@ -126,7 +135,7 @@ type FastRenderResult<ViewState extends object, CarryForward = {}> = RenderOutco
 type AnyFastRenderResult = FastRenderResult<object, object>;
 type LoadParams<Services, Params extends UrlParams> = (contexts: Services) => AsyncIterable<Params[]>;
 type RenderSlowly<Services extends Array<object>, PropsT extends object, SlowViewState extends object, SlowlyCarryForward> = (props: PropsT, ...services: Services) => Promise<SlowlyRenderResult<SlowViewState, SlowlyCarryForward>>;
-type RenderFast<Services extends Array<object>, PropsT extends object, FastViewState extends object, FastCarryForward> = (props: PropsT & RequestQuery, ...services: Services) => Promise<FastRenderResult<FastViewState, FastCarryForward>>;
+type RenderFast<Services extends Array<object>, PropsT extends object, FastViewState extends object, FastCarryForward> = (props: PropsT & RequestQuery & RequestCookies, ...services: Services) => Promise<FastRenderResult<FastViewState, FastCarryForward>>;
 interface JayStackComponentDefinition<Refs extends object, SlowVS extends object, FastVS extends object, InteractiveVS extends object, Services extends Array<any>, Contexts extends Array<any>, PropsT extends object, Params extends UrlParams, CompCore extends JayComponentCore<PropsT, InteractiveVS>> {
     services: ServiceMarkers<Services>;
     contexts: ContextMarkers<Contexts>;
@@ -202,6 +211,7 @@ declare function redirect3xx(status: number, location: string, message?: string)
  */
 declare function phaseOutput<ViewState extends object, CarryForward = {}>(rendered: ViewState, carryForward: CarryForward, options?: {
     headTags?: HeadTag[];
+    responseHeaders?: Record<string, string>;
 }): PhaseOutput<ViewState, CarryForward>;
 /**
  * @deprecated Use phaseOutput instead. Kept for backwards compatibility.
@@ -431,6 +441,7 @@ declare class RenderPipeline<T, TargetVS extends object = object, TargetCF exten
         viewState: TargetVS;
         carryForward: TargetCF;
         headTags?: HeadTag[];
+        responseHeaders?: Record<string, string>;
     }): Promise<RenderOutcome<TargetVS, TargetCF>>;
     /** Check if this pipeline is in a success state */
     isOk(): boolean;
@@ -466,15 +477,6 @@ interface JayFile {
     /** Absolute path to the temp file on disk (server-side only, always present in handlers) */
     path?: string;
 }
-/**
- * Options for file upload support.
- */
-interface FileUploadOptions {
-    /** Maximum file size in bytes (default: 10MB) */
-    maxFileSize?: number;
-    /** Maximum number of files (default: 10) */
-    maxFiles?: number;
-}
 /**
  * Supported HTTP methods for actions and queries.
  */
@@ -531,8 +533,6 @@ interface JayActionDefinition<Input, Output, Services extends any[]> {
     services: ServiceMarkers<Services>;
     /** Whether this action accepts file uploads (DL#131) */
     acceptsFiles?: boolean;
-    /** File upload options (DL#131) */
-    fileOptions?: FileUploadOptions;
     /** The handler function */
     handler: (input: Input, ...services: Services) => Promise<Output>;
 }
@@ -556,7 +556,7 @@ interface JayActionBuilder<Services extends any[], Input, Output, DefaultMethod
      * Mark this action as accepting file uploads (DL#131).
      * The handler will receive JayFile objects for file fields.
      */
-    withFiles(options?: FileUploadOptions): JayActionBuilder<Services, Input, Output, DefaultMethod>;
+    withFiles(): JayActionBuilder<Services, Input, Output, DefaultMethod>;
     /**
      * Define the handler function. Input and output types are inferred from the handler signature.
      */
@@ -635,8 +635,6 @@ interface JayStreamActionDefinition<Input, Chunk, Services extends any[]> {
     services: ServiceMarkers<Services>;
     /** Whether this action accepts file uploads (DL#131) */
     acceptsFiles?: boolean;
-    /** File upload options (DL#131) */
-    fileOptions?: FileUploadOptions;
     handler: (input: Input, ...services: Services) => AsyncIterable<Chunk>;
 }
 /**
@@ -647,7 +645,7 @@ interface JayStreamBuilder<Services extends any[]> {
     /**
      * Mark this streaming action as accepting file uploads (DL#131).
      */
-    withFiles(options?: FileUploadOptions): JayStreamBuilder<Services>;
+    withFiles(): JayStreamBuilder<Services>;
     withHandler<I, C>(handler: (input: I, ...services: Services) => AsyncIterable<C>): JayStreamAction<I, C> & JayStreamActionDefinition<I, C, Services>;
 }
 /**
@@ -681,6 +679,96 @@ declare function isJayStreamAction(value: unknown): value is JayStreamAction<unk
  */
 type StreamChunk<T> = T extends JayStreamAction<any, infer C> ? C : never;
+interface WebhookEvent {
+    type: string;
+    payload: unknown;
+    headers: Record<string, string | undefined>;
+}
+interface InvalidateContract {
+    (contractName: string, params?: Record<string, string>): Promise<void>;
+}
+interface JayWebhook<Services extends any[] = any[]> {
+    readonly webhookName: string;
+    readonly services: ServiceMarkers<Services>;
+    readonly handler: (event: WebhookEvent, invalidate: InvalidateContract, ...services: Services) => Promise<void>;
+    readonly _brand: 'JayWebhook';
+}
+interface JayWebhookBuilder<Services extends any[]> {
+    withServices<NewServices extends any[]>(...services: ServiceMarkers<NewServices>): JayWebhookBuilder<NewServices>;
+    withHandler(handler: (event: WebhookEvent, invalidate: InvalidateContract, ...services: Services) => Promise<void>): JayWebhook<Services>;
+}
+/**
+ * Create a webhook handler for data change invalidation.
+ *
+ * @param name - Unique webhook name (e.g., 'wix-stores.product-change')
+ *
+ * @example
+ * ```typescript
+ * export const onProductChange = makeWebhook('wix-stores.product-change')
+ *     .withServices(PRODUCTS_SERVICE)
+ *     .withHandler(async (event, invalidate, productsService) => {
+ *         const slug = await productsService.resolveSlug(event.payload.itemId);
+ *         await invalidate('product-page', { slug });
+ *     });
+ * ```
+ */
+declare function makeWebhook(name: string): JayWebhookBuilder<[]>;
+declare function isJayWebhook(value: unknown): value is JayWebhook;
+interface ConsoleContext {
+    projectRoot: string;
+    publicFolder: string;
+    build: {
+        frontend: string;
+        backend: string;
+    };
+    verbose: boolean;
+    log: (message: string) => void;
+    warn: (message: string) => void;
+    error: (message: string) => void;
+}
+declare const CONSOLE_CONTEXT: ServiceMarker<ConsoleContext>;
+interface JayCliCommand<Input> {
+    commandName: string;
+    services: ServiceMarkers<any[]>;
+    handler: (input: Input, ...services: any[]) => Promise<{
+        success: boolean;
+    }>;
+    _brand: 'JayCliCommand';
+}
+interface JayCliCommandDefinition<Input, Services extends any[]> {
+    commandName: string;
+    services: ServiceMarkers<Services>;
+    handler: (input: Input, ...services: Services) => Promise<{
+        success: boolean;
+    }>;
+}
+declare function isJayCliCommand(value: unknown): value is JayCliCommand<unknown>;
+interface JayCliCommandBuilder<Services extends any[]> {
+    withServices<NewServices extends any[]>(...services: ServiceMarkers<NewServices>): JayCliCommandBuilder<NewServices>;
+    withHandler<I>(handler: (input: I, ...services: Services) => Promise<{
+        success: boolean;
+    }>): JayCliCommand<I> & JayCliCommandDefinition<I, Services>;
+}
+/**
+ * Create a CLI command that can be run via `jay-stack run <plugin>/<command>`.
+ * Use for admin/batch operations: media upload, deployment, data sync, etc.
+ *
+ * @param name - Command name (e.g., 'upload-public')
+ *
+ * @example
+ * ```typescript
+ * export const uploadPublic = makeCliCommand('upload-public')
+ *     .withServices(MEDIA_SERVICE, CONSOLE_CONTEXT)
+ *     .withHandler(async (input: { folder?: string; dryRun?: boolean }, mediaService, console) => {
+ *         console.log('Uploading files...');
+ *         // ...
+ *         return { success: true };
+ *     });
+ * ```
+ */
+declare function makeCliCommand(name: string): JayCliCommandBuilder<[]>;
 /**
  * Builder for plugin/project initialization with type-safe server-to-client data flow.
  *
@@ -783,4 +871,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 FileUploadOptions, type GeneratedContractYaml, type HeadTag, type HttpMethod, type JayAction, type JayActionBuilder, type JayActionDefinition, type JayFile, 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 };
+export { ActionError, type ActionInput, type ActionOutput, type AnyFastRenderResult, type AnyJayStackComponentDefinition, type AnySlowlyRenderResult, type Builder, CONSOLE_CONTEXT, type CacheOptions, type ClientError4xx, type ConsoleContext, type ContractGeneratorFunction, type DynamicContractGenerator, type DynamicContractProps, type FastRenderResult, type GeneratedContractYaml, type HeadTag, type HttpMethod, type InvalidateContract, type JayAction, type JayActionBuilder, type JayActionDefinition, type JayCliCommand, type JayCliCommandBuilder, type JayCliCommandDefinition, type JayFile, type JayInit, type JayInitBuilder, type JayInitBuilderWithServer, type JayStackComponentDefinition, type JayStreamAction, type JayStreamActionDefinition, type JayStreamBuilder, type JayWebhook, type JayWebhookBuilder, type LoadParams, type PageProps, type PartialRender, type PhaseOutput, type PipelineFactory, type Redirect3xx, type RenderFast, type RenderOutcome, RenderPipeline, type RenderSlowly, type RequestCookies, type RequestQuery, type ServerError5xx, type ServiceInstances, type ServiceMarker, type ServiceMarkers, type Signals, type SlowlyRenderResult, type StreamChunk, type UrlParams, type WebhookEvent, badRequest, clientError4xx, createJayService, forbidden, isJayAction, isJayCliCommand, isJayInit, isJayStreamAction, isJayWebhook, makeCliCommand, makeContractGenerator, makeJayAction, makeJayInit, makeJayQuery, makeJayStackComponent, makeJayStream, makeWebhook, notFound, partialRender, phaseOutput, redirect3xx, serverError5xx, unauthorized };

package/dist/index.js CHANGED Viewed

@@ -45,7 +45,8 @@ function phaseOutput(rendered, carryForward, options) {
     kind: "PhaseOutput",
     rendered,
     carryForward,
-    ...options?.headTags && { headTags: options.headTags }
+    ...options?.headTags && { headTags: options.headTags },
+    ...options?.responseHeaders && { responseHeaders: options.responseHeaders }
   };
 }
 function partialRender(rendered, carryForward) {
@@ -340,8 +341,9 @@ class RenderPipeline {
     if (isErrorOutcome(resolvedValue)) {
       return resolvedValue;
     }
-    const { viewState, carryForward, headTags } = fn(resolvedValue);
-    return phaseOutput(viewState, carryForward, headTags ? { headTags } : void 0);
+    const { viewState, carryForward, headTags, responseHeaders } = fn(resolvedValue);
+    const options = headTags || responseHeaders ? { headTags, responseHeaders } : void 0;
+    return phaseOutput(viewState, carryForward, options);
   }
   // =========================================================================
   // Utility Methods
@@ -368,7 +370,6 @@ class JayActionBuilderImpl {
     __publicField(this, "_method");
     __publicField(this, "_cacheOptions");
     __publicField(this, "_acceptsFiles", false);
-    __publicField(this, "_fileOptions");
     this._actionName = _actionName;
     this._method = defaultMethod;
   }
@@ -384,9 +385,8 @@ class JayActionBuilderImpl {
     this._cacheOptions = options ?? { maxAge: 60 };
     return this;
   }
-  withFiles(options) {
+  withFiles() {
     this._acceptsFiles = true;
-    this._fileOptions = options;
     return this;
   }
   withHandler(handler) {
@@ -395,7 +395,6 @@ class JayActionBuilderImpl {
     const cacheOptions = this._cacheOptions;
     const serviceMarkers = this._services;
     const acceptsFiles = this._acceptsFiles;
-    const fileOptions = this._fileOptions;
     const action = Object.assign(
       (input) => {
         const resolver = globalThis.__JAY_SERVICE_RESOLVER__;
@@ -409,8 +408,7 @@ class JayActionBuilderImpl {
         services: serviceMarkers,
         handler,
         _brand: "JayAction",
-        ...acceptsFiles && { acceptsFiles: true },
-        ...fileOptions && { fileOptions }
+        ...acceptsFiles && { acceptsFiles: true }
       }
     );
     return action;
@@ -429,23 +427,20 @@ class JayStreamBuilderImpl {
   constructor(_actionName) {
     __publicField(this, "_services", []);
     __publicField(this, "_acceptsFiles", false);
-    __publicField(this, "_fileOptions");
     this._actionName = _actionName;
   }
   withServices(...services) {
     this._services = services;
     return this;
   }
-  withFiles(options) {
+  withFiles() {
     this._acceptsFiles = true;
-    this._fileOptions = options;
     return this;
   }
   withHandler(handler) {
     const actionName = this._actionName;
     const serviceMarkers = this._services;
     const acceptsFiles = this._acceptsFiles;
-    const fileOptions = this._fileOptions;
     const action = Object.assign(
       (input) => {
         const resolver = globalThis.__JAY_SERVICE_RESOLVER__;
@@ -459,8 +454,7 @@ class JayStreamBuilderImpl {
         services: serviceMarkers,
         handler,
         _brand: "JayStreamAction",
-        ...acceptsFiles && { acceptsFiles: true },
-        ...fileOptions && { fileOptions }
+        ...acceptsFiles && { acceptsFiles: true }
       }
     );
     return action;
@@ -472,6 +466,55 @@ function makeJayStream(name) {
 function isJayStreamAction(value) {
   return typeof value === "function" && value._brand === "JayStreamAction" && typeof value.actionName === "string";
 }
+class JayWebhookBuilderImpl {
+  constructor(_webhookName) {
+    __publicField(this, "_services", []);
+    this._webhookName = _webhookName;
+  }
+  withServices(...services) {
+    this._services = services;
+    return this;
+  }
+  withHandler(handler) {
+    return {
+      webhookName: this._webhookName,
+      services: this._services,
+      handler,
+      _brand: "JayWebhook"
+    };
+  }
+}
+function makeWebhook(name) {
+  return new JayWebhookBuilderImpl(name);
+}
+function isJayWebhook(value) {
+  return typeof value === "object" && value !== null && value._brand === "JayWebhook" && typeof value.webhookName === "string";
+}
+const CONSOLE_CONTEXT = createJayService("ConsoleContext");
+function isJayCliCommand(value) {
+  return typeof value === "object" && value !== null && "_brand" in value && value._brand === "JayCliCommand";
+}
+class JayCliCommandBuilderImpl {
+  constructor(_commandName) {
+    __publicField(this, "_services", []);
+    this._commandName = _commandName;
+  }
+  withServices(...services) {
+    this._services = services;
+    return this;
+  }
+  withHandler(handler) {
+    return {
+      commandName: this._commandName,
+      services: this._services,
+      handler,
+      _brand: "JayCliCommand"
+    };
+  }
+}
+function makeCliCommand(name) {
+  return new JayCliCommandBuilderImpl(name);
+}
 function makeJayInit(key) {
   const resolvedKey = key ?? "__JAY_INIT_KEY__";
   return {
@@ -509,20 +552,25 @@ function isJayInit(obj) {
 }
 export {
   ActionError,
+  CONSOLE_CONTEXT,
   RenderPipeline,
   badRequest,
   clientError4xx,
   createJayService,
   forbidden,
   isJayAction,
+  isJayCliCommand,
   isJayInit,
   isJayStreamAction,
+  isJayWebhook,
+  makeCliCommand,
   makeContractGenerator,
   makeJayAction,
   makeJayInit,
   makeJayQuery,
   makeJayStackComponent,
   makeJayStream,
+  makeWebhook,
   notFound,
   partialRender,
   phaseOutput,

package/package.json CHANGED Viewed

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