@process.co/element-types 0.0.18 → 0.0.19

package/src/index.ts

@@ -21,6 +21,7 @@ import type {
     ISlotStaticInstanceDefinition,
     ISlotDefinition,
 } from './slot-definition';
+import { ConfigureResponseCachingOptions } from './http-request-cache';
 
 export type { ISlotInstanceDefinition, ISlotStaticInstanceDefinition, ISlotDefinition };
 
@@ -60,6 +61,19 @@ export {
     isPlatformBoundLoaderType,
 } from './platform-loader-type';
 
+export {
+    HTTP_REQUEST_CACHE_POLICY_KEY,
+    REPLAY_BINDING_RANGE,
+    REPLAY_META_RANGE,
+    type BodyVaryProjection,
+    type CacheVaryInfoWire,
+    type ConfigureResponseCachingOptions,
+    type DurationWire,
+    type HttpRequestCacheMode,
+    type HttpRequestCachePolicy,
+    type HttpRequestCacheVary,
+} from './http-request-cache';
+
 // Base types for module definitions
 export type ModuleDefinition = {
     type: string;
@@ -110,7 +124,7 @@ export type SignalEventShape = {
  * When {@link HttpInterfaceSchemaWire.validation} is true, the runtime does **not** validate against
  * those JSON blobs alone: it loads the ESM at {@link HttpInterfaceSchemaWire.compiledValidatorKey}
  * (default export = Zod schema) and runs full `safeParse` on the payload via the runner-bound
- * {@link SignalHostServices.enforceSchema} RPC (see {@link setSignalEmitValidationHost}).
+ * {@link SignalRunHostServices.enforceSchema} RPC (see {@link setSignalEmitValidationHost}).
  */
 export type HttpInterfaceSchemaWire = {
     /**
@@ -141,9 +155,13 @@ export type HttpInterfaceSchemaWire = {
     coerceLeafPrimitives?: boolean | 'auto';
 };
 
-/** Host-backed RPC surface passed as `params.$` to signal `run` (parallel to action `ActionRunOptions.$`). */
-export type SignalHostServices = {
+/**
+ * Host `params.$` during signal **`run`** (live webhook / test execution).
+ * Not passed to `hooks.save` — use {@link SignalSaveHookHostServices} there.
+ */
+export type SignalRunHostServices = {
     export: (category: string, message: string) => void | Promise<void>;
+
     $transitionToSlot: (slots: Array<SlotTransitionDefinition>) => void | Promise<void>;
 
     /**
@@ -158,12 +176,30 @@ export type SignalHostServices = {
 
     /**
      * Wire for the primary `$.interface.schema` property (same persisted object the publish
-     * pipeline attaches `compiledValidatorKey` to). Use with {@link SignalHostServices.enforceSchema},
+     * pipeline attaches `compiledValidatorKey` to). Use with {@link SignalRunHostServices.enforceSchema},
      * e.g. `await $.enforceSchema($.interfaceEmitSchema, toEmit)`.
      */
     interfaceEmitSchema?: HttpInterfaceSchemaWire;
 };
 
+/** @deprecated Use {@link SignalRunHostServices} for `run`; hook `$` types are separate. */
+export type SignalHostServices = SignalRunHostServices;
+
+/** Host `params.$` during **`hooks.save`** (publish materialization only). */
+export type SignalSaveHookHostServices = {
+    http: {
+        configureResponseCaching: (
+            options: ConfigureResponseCachingOptions,
+        ) => Promise<void> | void;
+    };
+};
+
+/** @deprecated Use {@link SignalSaveHookHostServices} */
+export type HookSaveHostServices = SignalSaveHookHostServices;
+
+/** Host `params.$` during `hooks.activate` / `hooks.deactivate` (no `run` or `save` surfaces). */
+export type SignalLifecycleHookHostServices = Pick<SignalRunHostServices, 'export'>;
+
 /** One row from a failed Zod `safeParse` (host / `validateEmitPayload`). */
 export type SchemaValidationIssue = {
     path: string;
@@ -193,7 +229,7 @@ export type EnforceSchemaResult<T extends unknown = unknown> =
 export const PROCESS_CO_ENFORCE_SCHEMA_HOST_PAYLOAD_MARKER = 'enforceSchema' as const;
 
 export type SignalRunOptions = {
-    $: SignalHostServices;
+    $: SignalRunHostServices;
     event: SignalEventShape;
 };
 
@@ -206,10 +242,10 @@ const SIGNAL_EMIT_VALIDATION_HOST = Symbol.for('process.co.signalEmitValidationH
 
 /**
  * Host shape accepted from the runner RPC bridge (`$.enforceSchema` may be typed as
- * returning `Promise<unknown>` while {@link SignalHostServices} uses a generic `T`).
+ * returning `Promise<unknown>` while {@link SignalRunHostServices} uses a generic `T`).
  */
 export type SignalEmitValidationHostBinding =
-    | Pick<SignalHostServices, 'enforceSchema'>
+    | Pick<SignalRunHostServices, 'enforceSchema'>
     | {
         enforceSchema?: (
             inputSchema: HttpInterfaceSchemaWire | undefined,
@@ -217,8 +253,8 @@ export type SignalEmitValidationHostBinding =
         ) => Promise<unknown>;
     };
 
-function getSignalEmitValidationHostBinding(): Pick<SignalHostServices, 'enforceSchema'> | undefined {
-    return (globalThis as Record<symbol, Pick<SignalHostServices, 'enforceSchema'> | undefined>)[
+function getSignalEmitValidationHostBinding(): Pick<SignalRunHostServices, 'enforceSchema'> | undefined {
+    return (globalThis as Record<symbol, Pick<SignalRunHostServices, 'enforceSchema'> | undefined>)[
         SIGNAL_EMIT_VALIDATION_HOST
     ];
 }
@@ -232,11 +268,11 @@ function getSignalEmitValidationHostBinding(): Pick<SignalHostServices, 'enforce
 export function setSignalEmitValidationHost(
     host: SignalEmitValidationHostBinding | undefined,
 ): void {
-    const g = globalThis as Record<symbol, Pick<SignalHostServices, 'enforceSchema'> | undefined>;
+    const g = globalThis as Record<symbol, Pick<SignalRunHostServices, 'enforceSchema'> | undefined>;
     if (host === undefined) {
         delete g[SIGNAL_EMIT_VALIDATION_HOST];
     } else {
-        g[SIGNAL_EMIT_VALIDATION_HOST] = host as Pick<SignalHostServices, 'enforceSchema'>;
+        g[SIGNAL_EMIT_VALIDATION_HOST] = host as Pick<SignalRunHostServices, 'enforceSchema'>;
     }
 }
 
@@ -663,10 +699,12 @@ type PropDefinitionInput<TType = unknown> = BasePropDefinition & {
 };
 
 export type HttpInterfaceType = {
+
     /**
      * Full HTTP response (status / headers / body). Sending `body` completes the exchange for typical requests.
      */
     respond: (response: HTTPResponse) => Promise<any> | void;
+
     /**
      * Incremental write or SSE frame; does not complete the exchange. Pair with {@link end} or a terminal {@link respond} where applicable.
      */
@@ -680,6 +718,12 @@ export type HttpInterfaceType = {
      */
     deferHttpResponse: (timeoutMs?: number, options?: HttpDeferResponseOptions) => void;
 
+    /**
+     * Optional runtime vary suffix (hashed and appended to the HTTP base scenario key).
+     * Call when saved `$httpRequestCachePolicy.needsRuntimeVaryKey` is true.
+     */
+    setRequestVaryKey: (value: string) => void;
+
     /**
      * Append one JSON value to an incremental stream (`ndjson` or `jsonArray` defer modes). Each call is one line (NDJSON) or one array element (json-array).
      */
@@ -693,6 +737,7 @@ export type HttpInterfaceType = {
     flow: FlowFunctions;
     end: () => void;
     execute: () => Promise<{ headers?: Record<string, string>;[key: string]: any }>
+
 };
 
 
@@ -729,12 +774,32 @@ type PropTypeFromTypeValue<U, T = unknown> =
     : U extends "integer" ? number
     : U extends "$.interface.schema" ? HttpInterfaceSchemaWire
     : U extends "$.interface.http" ? HttpInterfaceType
+    : U extends "$.interface.duration" ? import('./http-request-cache').DurationWire
+    : U extends "$.interface.cacheVaryInfo" ? import('./http-request-cache').CacheVaryInfoWire
     : unknown;
 
+/**
+ * Runtime shape of an embedded app prop (`props: { http: httpApp }` on a signal/action).
+ * Maps `propDefinitions` / `props` / `methods` to instance fields — not the `defineApp` module metadata (`type`, `app`, …).
+ */
+export type DeriveEmbeddedAppPropInstance<T extends { type: 'app' }> = Spread<
+    (T extends { propDefinitions: Record<string, any> }
+        ? { [K in keyof T['propDefinitions']]: PropType<T['propDefinitions'][K]> }
+        : {}) &
+        (T extends { props: Record<string, any> }
+            ? { [K in keyof T['props']]: PropType<T['props'][K]> }
+            : {}) &
+        (T extends { methods: Record<string, any> }
+            ? { [K in keyof T['methods']]: T['methods'][K] }
+            : {})
+>;
+
 // Utility type for transforming prop definitions to their runtime types
 export type PropType<T> =
-    // 1. If T is an app definition, derive its instance type
-    T extends { props: Record<string, any>; methods: Record<string, any> }
+    // 1. Embedded app module → runtime prop surface (not the definition object)
+    T extends { type: 'app' }
+    ? DeriveEmbeddedAppPropInstance<T>
+    : T extends { props: Record<string, any>; methods: Record<string, any> }
     ? DeriveAppInstance<T>
     // 2. If T is a propDefinition, resolve from propDefinitions or props
     : T extends { propDefinition: readonly [infer App, infer PropName] }
@@ -801,24 +866,69 @@ export type DeriveAppInstance<T> =
         { [K in keyof T as K extends "props" | "propDefinitions" | "methods" ? never : K]: T[K] }
     >;
 
+/** True when a prop definition resolves to `$.interface.http` (runtime-only on `run`). */
+type IsHttpInterfacePropDef<P> =
+    P extends { type: '$.interface.http' }
+    ? true
+    : P extends { propDefinition: readonly [infer App, infer PropName] }
+    ? App extends { propDefinitions: Record<string, any> }
+        ? PropName extends keyof App['propDefinitions']
+            ? App['propDefinitions'][PropName] extends { type: '$.interface.http' }
+                ? true
+                : false
+            : false
+        : App extends { props: Record<string, any> }
+            ? PropName extends keyof App['props']
+                ? App['props'][PropName] extends { type: '$.interface.http' }
+                    ? true
+                    : false
+                : false
+            : false
+    : false;
+
 export type DeriveSignalInstance<T> =
     Spread<
-        Omit<T, "props" | "propDefinitions" | "methods"> &
+        Omit<T, SignalInstanceExcludedKeys> &
         (T extends { props: Record<string, any> }
-            ? { [K in keyof T["props"]]: PropType<T["props"][K]> }
+            ? { [K in keyof T['props']]: PropType<T['props'][K]> }
             : {}) &
         (T extends { propDefinitions: Record<string, any> }
-            ? { [K in keyof T["propDefinitions"]]: PropType<T["propDefinitions"][K]> }
+            ? { [K in keyof T['propDefinitions']]: PropType<T['propDefinitions'][K]> }
             : {}) &
-        // Add $emit to all signal instances
         EmitFunction &
         (T extends { methods: Record<string, any> }
-            ? { [K in keyof T["methods"]]: T["methods"][K] }
+            ? { [K in keyof T['methods']]: T['methods'][K] }
             : {}) &
-        // Also include all direct methods on the object
-        { [K in keyof T as K extends "props" | "propDefinitions" | "methods" ? never : K]: T[K] }
+        {
+            [K in keyof T as K extends SignalInstanceExcludedKeys ? never : K]: T[K];
+        }
     >;
 
+/** Module definition keys that are not instance fields on `this` in `run` or hooks. */
+type SignalInstanceExcludedKeys =
+    | 'props'
+    | 'propDefinitions'
+    | 'methods'
+    | 'run'
+    | 'hooks';
+
+/** Prop names on `T` that are `$.interface.http` (excluded from hook `this`). */
+type HttpInterfacePropKeys<T> =
+    T extends { props: infer P extends Record<string, unknown> }
+        ? keyof {
+              [K in keyof P as IsHttpInterfacePropDef<P[K]> extends true ? K : never]: true;
+          }
+        : never;
+
+/**
+ * `this` inside signal hooks: instance props minus `$.interface.http` and `$emit`.
+ * Use `params.$.http.configureResponseCaching` in `save`.
+ */
+export type DeriveSignalHookInstance<T> = Omit<
+    DeriveSignalInstance<T>,
+    HttpInterfacePropKeys<T> | keyof EmitFunction
+>;
+
 // In your element-types
 export type PropDefinitionType<App, PropName extends string> =
     App extends { propDefinitions: Record<string, any> }
@@ -827,21 +937,37 @@ export type PropDefinitionType<App, PropName extends string> =
     : unknown
     : unknown;
 
-// --- Add this helper above DeriveActionInstance ---
-
-// Enhanced action instance type
+/** Module definition keys that are not instance fields on `this` in `run`. */
+type ActionInstanceExcludedKeys =
+    | 'props'
+    | 'propDefinitions'
+    | 'methods'
+    | 'run'
+    | 'type'
+    | 'name'
+    | 'description'
+    | 'icon'
+    | 'noAuth'
+    | 'slots'
+    | 'hasNew'
+    | 'initValue';
+
+/** Runtime `this` for action `run` (prop values via {@link PropType}, including embedded apps). */
 export type DeriveActionInstance<T> =
     Spread<
-        Omit<T, "props" | "propDefinitions" | "methods"> &
+        Omit<T, ActionInstanceExcludedKeys> &
         (T extends { props: Record<string, any> }
-            ? { [K in keyof T["props"]]: PropType<T["props"][K]> }
+            ? { [K in keyof T['props']]: PropType<T['props'][K]> }
             : {}) &
         (T extends { propDefinitions: Record<string, any> }
-            ? { [K in keyof T["propDefinitions"]]: PropType<T["propDefinitions"][K]> }
+            ? { [K in keyof T['propDefinitions']]: PropType<T['propDefinitions'][K]> }
             : {}) &
         (T extends { methods: Record<string, any> }
-            ? { [K in keyof T["methods"]]: T["methods"][K] }
-            : {})
+            ? { [K in keyof T['methods']]: T['methods'][K] }
+            : {}) &
+        {
+            [K in keyof T as K extends ActionInstanceExcludedKeys ? never : K]: T[K];
+        }
     >;
 
 // Helper type to create a module with proper this context
@@ -878,7 +1004,10 @@ export type ActionInstance<A extends Action> = DeriveActionInstance<A>;
 export type SignalInstance<S extends Signal> = DeriveSignalInstance<S>;
 
 export type SignalMethod<S extends Signal> = (this: SignalInstance<S>, params: SignalRunOptions) => Promise<unknown>;
-export type ActionMethod<A extends Action> = (this: ActionInstance<A>, params: { $: any }) => Promise<unknown>;
+export type ActionMethod<A extends Action> = (
+    this: ActionInstance<A>,
+    params: ActionRunOptions,
+) => Promise<unknown>;
 
 export type PropStringDefinitionTypes = "text" | "html" | "markdown" | "json" | "xml" | "yaml" | "csv" | "tsv" | "css" | "sql" | "email" | "emailList" | "urlList" | "url" | "base64" | "javascript";
 
@@ -905,22 +1034,112 @@ export function defineApp<const T extends object>(app: T & ThisType<DeriveAppIns
     return app;
 }
 
-// Helper to provide ThisType context for action definitions
-export function defineAction<const T extends
-    { props?: Record<string, unknown> } &
-    { type: "action" } &
-    { name?: string } &
-    { description?: string } &
-    { icon?: ElementIcon } &
-    { noAuth?: boolean } &
-    { slots?: ISlotDefinition } &
-    { methods?: Record<string, (...args: any[]) => any> } &
-    { hasNew?: boolean } &
-    { initValue?: any }>(action: T & ThisType<DeriveActionInstance<T>>): T {
+export type ActionRunFn = (params: ActionRunOptions) => void | Promise<unknown>;
+
+/** Canonical action entrypoint — implement `run` here (see process-internal loop, etc.). */
+export type ActionMethodsRun = {
+    methods: Record<string, unknown> & { run: ActionRunFn };
+};
+
+/**
+ * @deprecated Use `methods: { run }` instead of a top-level `run` property.
+ * Runtime still accepts this shape via `restructureElement`.
+ */
+export type ActionMethodsLegacyTopLevelRun = {
+    /** @deprecated Use `methods.run`. */
+    run?: ActionRunFn;
+};
+
+/** Minimum shape for {@link defineAction}. Prefer {@link ActionMethodsRun}. */
+export type ActionMethods = ActionMethodsRun | ActionMethodsLegacyTopLevelRun;
+
+/** Structural requirements for an action module (tooling; prefer {@link defineAction}). */
+export type ActionDefinitionShape<T> = {
+    methods: Record<string, unknown> & {
+        run: (this: DeriveActionInstance<T>, params: ActionRunOptions) => Promise<unknown>;
+    };
+    /**
+     * @deprecated Use `methods.run`.
+     */
+    run?: (this: DeriveActionInstance<T>, params: ActionRunOptions) => Promise<unknown>;
+};
+
+/** Contextual `this` for top-level and `methods.*` action functions. */
+export type ActionMethodsWithThis<T> = T &
+    ThisType<DeriveActionInstance<T>> &
+    (T extends { methods?: infer M extends Record<string, unknown> }
+        ? { methods: M & ThisType<DeriveActionInstance<T>> }
+        : {});
+
+export function defineAction<
+    const T extends ActionMethods & { type: 'action' } & Record<string, unknown>,
+>(action: ActionMethodsWithThis<T>): T {
     return action;
 }
 
-export function defineSignal<const T extends { run: (params: SignalRunOptions) => Promise<unknown> }>(signal: T & ThisType<DeriveSignalInstance<T>>): T {
+/** `params.$` for `hooks.activate` / `hooks.deactivate`. */
+export type SignalHostHookParameters = {
+    $: SignalLifecycleHookHostServices;
+};
+
+/** `params.$` for `hooks.save` — publish-only; not {@link SignalRunHostServices}. */
+export type SignalSaveHostParameters = {
+    $: SignalSaveHookHostServices;
+};
+
+export type SignalHostHookMethod<T> = (
+    this: DeriveSignalHookInstance<T>,
+    params: SignalHostHookParameters,
+) => void | Promise<void>;
+
+export type SignalSaveHookMethod<T> = (
+    this: DeriveSignalHookInstance<T>,
+    params: SignalSaveHostParameters,
+) => void | Promise<void>;
+
+export type SignalHooksDefinition<T> = {
+    deactivate?: SignalHostHookMethod<T>;
+    activate?: SignalHostHookMethod<T>;
+    save?: SignalSaveHookMethod<T>;
+    onDeactivate?: SignalHostHookMethod<T>;
+    onActivate?: SignalHostHookMethod<T>;
+    onSave?: SignalSaveHookMethod<T>;
+};
+
+/**
+ * Hook implementations for {@link defineSignal}: `params.$` is typed here; `this` comes from
+ * {@link ThisType}<{@link DeriveSignalHookInstance}<T>> (avoids circular `T` and empty `this`).
+ */
+export type SignalHooksContextualDefinition = {
+    deactivate?: (params: SignalHostHookParameters) => void | Promise<void>;
+    activate?: (params: SignalHostHookParameters) => void | Promise<void>;
+    save?: (params: SignalSaveHostParameters) => void | Promise<void>;
+    onDeactivate?: (params: SignalHostHookParameters) => void | Promise<void>;
+    onActivate?: (params: SignalHostHookParameters) => void | Promise<void>;
+    onSave?: (params: SignalSaveHostParameters) => void | Promise<void>;
+};
+
+/** Hook bag for {@link defineSignal}. */
+export type SignalHooksWithThis<T> = SignalHooksContextualDefinition &
+    ThisType<DeriveSignalHookInstance<T>>;
+
+/** Structural requirements for a signal module (used by tooling; prefer {@link defineSignal}). */
+export type SignalDefinitionShape<T> = {
+    run: (this: DeriveSignalInstance<T>, params: SignalRunOptions) => Promise<unknown>;
+    hooks?: SignalHooksDefinition<T>;
+};
+
+/** @deprecated Use {@link defineSignal} — kept for generated lib compatibility. */
+export type SignalMethods = {
+    run: (params: SignalRunOptions) => Promise<unknown>;
+};
+
+export function defineSignal<const T extends SignalMethods & Record<string, unknown>>(
+    signal: T &
+        ThisType<DeriveSignalInstance<T>> & {
+            hooks?: SignalHooksWithThis<T>;
+        },
+): T {
     return signal;
 }