@lwrjs/types 0.9.0-alpha.2 → 0.9.0-alpha.21

package/build/config.d.ts

@@ -1,4 +1,4 @@
-import { CacheResponse, RenderOptions, RouteHandlerViewResponse, RuntimeEnvironment, ServerTypes, Specifier, ViewParams, ViewRequest, ViewResponse } from './index';
+import { AssetProvider, AssetTransformPlugin, BundleProvider, CacheResponse, LwrService, ModuleProvider, RenderOptions, ResourceProvider, RouteHandlerViewResponse, RuntimeEnvironment, ServerTypes, ServiceCtor, Specifier, ViewParams, ViewProvider, ViewRequest, ViewResponse, ViewTransformPlugin } from './index';
 export interface View {
     id: string;
     rootComponent?: string;
@@ -22,7 +22,7 @@ export interface NormalizedLwrRoute extends LwrRoute {
 export interface LwrErrorRoute extends LwrBaseRoute {
     status: 404 | 500;
 }
-export interface NormalizedLwrErrorRoute extends LwrBaseRoute {
+export interface NormalizedLwrErrorRoute extends LwrErrorRoute {
     bootstrap: NormalizedLwrAppBootstrapConfig;
 }
 export interface LwrAppBootstrapConfig {
@@ -41,6 +41,9 @@ export interface LwrLockerConfig {
     trustedComponents?: string[];
     clientOnly?: boolean;
 }
+export interface RouteHandlersConfig {
+    [id: string]: string;
+}
 export interface LocalizedViewRequest extends ViewRequest {
     locale?: string;
 }
@@ -86,9 +89,9 @@ export interface LwrGlobalConfig {
     resourceProviders?: ServiceConfig[];
     viewProviders?: ServiceConfig[];
     viewTransformers?: ServiceConfig[];
-    templateEngine?: string;
     routes?: LwrRoute[];
     errorRoutes?: LwrErrorRoute[];
+    routeHandlers?: RouteHandlersConfig;
     bundleConfig?: BundleConfig;
     serverType?: ServerTypes;
     staticSiteGenerator?: StaticSiteGenerator;
@@ -96,10 +99,12 @@ export interface LwrGlobalConfig {
 }
 export interface NormalizedLwrGlobalConfig extends Required<Omit<LwrGlobalConfig, 'lwc'>> {
     routes: NormalizedLwrRoute[];
+    errorRoutes: NormalizedLwrErrorRoute[];
     assets: AssetConfig[];
     lwrVersion: string;
     amdLoader: string;
     esmLoader: string;
+    hooks: ServiceEntry[];
     moduleProviders: ServiceEntry[];
     viewProviders: ServiceEntry[];
     viewTransformers: ServiceEntry[];
@@ -111,9 +116,31 @@ export interface NormalizedLwrGlobalConfig extends Required<Omit<LwrGlobalConfig
 export interface StaticSiteGenerator {
     outputDir?: string;
     locales?: string[];
+    skipCleanOutputDir?: boolean;
+    skipBaseDocumentGeneration?: boolean;
     _additionalRoutePaths?: string[];
     _additionalModules?: string[];
 }
+export interface ServerBuild {
+    appConfig: NormalizedLwrGlobalConfig;
+    runtimeEnvironment: RuntimeEnvironment;
+    globalData: GlobalData;
+    hooks: HooksPlugin[];
+    services: Services;
+    routeHandlers: RouteHandlers;
+}
+export interface Services {
+    moduleProviders: ResolvedServiceEntry<ModuleProvider>[];
+    bundleProviders: ResolvedServiceEntry<BundleProvider>[];
+    viewProviders: ResolvedServiceEntry<ViewProvider>[];
+    viewTransformers: ResolvedServiceEntry<ViewTransformPlugin>[];
+    resourceProviders: ResolvedServiceEntry<ResourceProvider>[];
+    assetProviders: ResolvedServiceEntry<AssetProvider>[];
+    assetTransformers: ResolvedServiceEntry<AssetTransformPlugin>[];
+}
+export interface RouteHandlers {
+    [id: string]: RouteHandlerFunction;
+}
 interface AssetConfigCommon {
     urlPath: string;
     alias?: string;
@@ -136,12 +163,16 @@ export interface NormalizedLwcConfig extends Omit<LwcConfig, 'interchangeableMod
 }
 export declare type ServiceEntry = [string, any?];
 export declare type ServiceConfig = string | ServiceEntry;
+export declare type ResolvedServiceEntry<T extends LwrService> = [ServiceCtor<T>, any?];
 export interface BundleConfig {
     exclude?: string[];
     UNSAFE_lwrDefaultExclude?: string[];
     external?: Record<string, string>;
     alias?: Record<string, string>;
 }
+export interface BundleConfigOverrides extends BundleConfig {
+    appendExcludes?: boolean;
+}
 export declare type Environment = string;
 export interface EnvironmentConfig {
     default?: Environment;
@@ -168,7 +199,35 @@ export interface InterchangeableModuleRecord {
     };
 }
 export interface HooksPlugin {
-    initConfigs(lwrConfig: NormalizedLwrGlobalConfig, dataConfig: GlobalData, runtimeConfig: RuntimeEnvironment): Promise<void> | void;
+    /**
+     * Programmatically modify application and runtime configurations.
+     *
+     * @remarks
+     * These hooks are invoked both at build time and runtime for Express and Koa(not MRT).
+     *
+     * During server build, config hooks are invoked prior to static site generation
+     * and server bundling.
+     *
+     * For the `createServer`(ie. Express/Koa) runtime, these config hooks are invoked before all other hooks
+     * during server context initialization
+     *
+     * For the `createHandler`(ie. MRT Serverless Express) runtime, these config hooks are NOT invoked.  This runtime does
+     * not support asynchronous execution during initialization.  These hooks MUST be ran during
+     * the server build.
+     *
+     */
+    initConfigs?: (lwrConfig: NormalizedLwrGlobalConfig, dataConfig: GlobalData, runtimeConfig: RuntimeEnvironment) => Promise<void> | void;
+    /**
+     * Load routes on application start up.
+     *
+     * @remarks
+     * These hooks are invoked ONLY at runtime.
+     *
+     * For the `createServer` runtime, these hooks are invoked AFTER config hooks.
+     *
+     * For the `createHandler` runtime, these hooks are invoked during server context initialization.
+     */
+    onStart?: (routes: LwrRoute[]) => void;
 }
 export {};
 //# sourceMappingURL=config.d.ts.map

package/build/index.d.ts

@@ -2,12 +2,11 @@
 /// <reference types="node" />
 /// <reference types="node" />
 /// <reference types="node" />
-/// <reference types="node" />
+import type { WatchOptions } from 'chokidar';
 import { EventEmitter } from 'events';
 import fs from 'fs';
-import { Server } from 'http';
 import { Readable } from 'stream';
-import { BundleConfig, EnvironmentConfig, HooksPlugin, LwrLockerConfig, NormalizedLwrErrorRoute, NormalizedLwrGlobalConfig, NormalizedLwrRoute, ResolverModuleRecord } from './config.js';
+import { BundleConfig, EnvironmentConfig, HooksPlugin, LwrLockerConfig, NormalizedLwrErrorRoute, NormalizedLwrGlobalConfig, NormalizedLwrRoute, ResolverModuleRecord, BundleConfigOverrides, RouteHandlers } from './config.js';
 import { AssetReference, CompiledView, PublicViewRegistry, ViewProvider, ViewRegistry, ViewTransformPlugin } from './views.js';
 export * from './lwr-shim.js';
 export * from './config.js';
@@ -164,8 +163,10 @@ export interface ServerModeConfig {
     };
     featureFlags: FeatureFlags;
 }
-export interface FeatureFlags {
-    LEGACY_LOADER: boolean;
+export interface FeatureFlags extends Record<string, boolean | undefined> {
+    LEGACY_LOADER?: boolean;
+    SSR_STATIC_BUNDLES?: boolean;
+    SSR_SANDBOX_WORKER?: boolean;
 }
 export interface RuntimeEnvironment extends ServerModeConfig {
     apiVersion: string;
@@ -201,6 +202,11 @@ export interface BootstrapRuntimeEnvironment extends RuntimeEnvironment {
     bootstrapImports?: string[];
     bootstrapDynamicImports?: string[];
 }
+export type { WatchOptions } from 'chokidar';
+export interface WatcherFactory {
+    createFileWatcher(options?: WatchOptions): Watcher;
+    setupWatcher(onModuleChange: Function): Watcher;
+}
 export interface Watcher extends EventEmitter {
     add(paths: string | ReadonlyArray<string>): void;
     unwatch(paths: string | ReadonlyArray<string>): void;
@@ -254,7 +260,7 @@ export interface ModuleProvider {
 }
 export declare type LwrService = ModuleProvider | ResourceProvider | ViewProvider | AssetProvider | HooksPlugin | AssetTransformPlugin | ViewTransformPlugin;
 export interface ServiceCtor<T extends LwrService, R extends Record<string, Json> = {}> {
-    new (moduleProviderConfig: R, serviceProviderConfig?: any, ...args: any[]): T;
+    new (providerConfig: R, serviceProviderConfig?: any, ...args: any[]): T;
 }
 export interface ModuleRegistry {
     name: string;
@@ -265,11 +271,18 @@ export interface ModuleRegistry {
     resolveModuleUri<R extends RuntimeEnvironment, S extends string | undefined>(moduleId: Required<Pick<ModuleId, 'specifier' | 'version'>>, runtimeEnvironment: R, runtimeParams?: RuntimeParams, signature?: S): S extends string ? string : Promise<string>;
     getPublicApi(): PublicModuleRegistry;
 }
-export declare type PublicModuleRegistry = Pick<ModuleRegistry, 'getModule' | 'getModuleEntry' | 'resolveModuleUri'>;
+export declare type PublicModuleRegistry = Pick<ModuleRegistry, 'getModule' | 'getModuleEntry' | 'getLinkedModule' | 'resolveModuleUri'>;
+export interface BundleProvider {
+    name: string;
+    bundle<T extends AbstractModuleId, R extends RuntimeEnvironment>(moduleId: T, runtimeEnvironment: R, runtimeParams: RuntimeParams, configOverrides?: BundleConfig): Promise<BundleDefinition | undefined>;
+}
 export interface ModuleBundler {
-    getModuleBundle<T extends AbstractModuleId, R extends RuntimeEnvironment>(moduleId: T, runtimeEnvironment: R, runtimeParams?: RuntimeParams, bundleConfigOverrides?: BundleConfig): Promise<BundleDefinition>;
+    addBundleProviders(providers: BundleProvider[]): void;
+    getModuleBundle<T extends AbstractModuleId, R extends RuntimeEnvironment>(moduleId: T, runtimeEnvironment: R, runtimeParams?: RuntimeParams, bundleConfigOverrides?: BundleConfigOverrides): Promise<BundleDefinition>;
+    resolveModuleUri(moduleId: Required<Pick<ModuleId, 'specifier' | 'version'>>, runtimeEnvironment: RuntimeEnvironment, runtimeParams?: RuntimeParams, signature?: string): Promise<string>;
+    getPublicApi(): PublicModuleBundler;
 }
-export declare type PublicModuleBundler = Pick<ModuleBundler, 'getModuleBundle'>;
+export declare type PublicModuleBundler = Pick<ModuleBundler, 'getModuleBundle' | 'resolveModuleUri'>;
 export interface BundleRecord {
     imports?: BaseModuleReference[];
     dynamicImports?: BaseDynamicModuleReference[];
@@ -280,6 +293,7 @@ export interface BundleDefinition extends ModuleId {
     config: BundleConfig;
     map?: any;
     bundleRecord: BundleRecord;
+    src?: string;
 }
 export interface ProviderAppConfig {
     modules: ResolverModuleRecord[];
@@ -294,9 +308,9 @@ export interface ProviderAppConfig {
     amdLoader: string;
     esmLoader: string;
     environment?: EnvironmentConfig;
+    bundleConfig: BundleConfig;
 }
 export interface ProviderContext {
-    compiler: Compiler;
     appObserver: Pick<LwrAppObserver, 'onModuleDefinitionChange' | 'onModuleSourceChange' | 'onAssetSourceChange' | 'onViewSourceChange'>;
     appEmitter: Pick<LwrAppEmitter, 'notifyModuleDefinitionChanged' | 'notifyAssetSourceChanged' | 'notifyModuleSourceChanged' | 'notifyViewSourceChanged'>;
     moduleRegistry: PublicModuleRegistry;
@@ -306,6 +320,8 @@ export interface ProviderContext {
     assetRegistry: PublicAssetRegistry;
     config: ProviderAppConfig;
     runtimeEnvironment: RuntimeEnvironment;
+    watcherFactory?: WatcherFactory;
+    siteMetadata?: SiteMetadata;
 }
 export interface ResourceIdentifier {
     specifier: string;
@@ -321,7 +337,7 @@ export interface AssetUri {
     immutable: boolean;
     entry: string;
 }
-export declare type ResourceType = 'application/javascript' | 'application/json' | 'text/css' | 'lwr-importmap' | 'module';
+export declare type ResourceType = 'application/javascript' | 'application/json' | 'text/css' | 'lwr-importmap' | 'module' | string;
 export interface ResourceDefinition {
     specifier?: string;
     type: ResourceType;
@@ -331,7 +347,7 @@ export interface ResourceDefinition {
     defer?: boolean;
     nonce?: string;
     content?: string;
-    stream?: Readable;
+    stream?: () => Readable;
     isPreload?: boolean;
 }
 export interface AssetMetadata {
@@ -397,12 +413,13 @@ export declare type PublicResourceRegistry = Pick<ResourceRegistry, 'getResource
 export interface AssetRegistry {
     name: string;
     addAssetProviders(provider: AssetProvider[]): void;
+    addAssetTransformers(transformers: AssetTransformPlugin[]): void;
     getAsset<R extends AssetIdentifier, T extends RuntimeEnvironment>(resourceIdentity: R, runtimeEnvironment: T, includeMetadata?: boolean): Promise<AssetDefinition>;
     resolveAssetUri<R extends AssetIdentifier, T extends RuntimeEnvironment>(resourceIdentity: R, runtimeEnvironment: T): Promise<AssetUri>;
     getPublicApi(): PublicAssetRegistry;
 }
 export declare type PublicAssetRegistry = Pick<AssetRegistry, 'getAsset' | 'resolveAssetUri'>;
-export interface CompilerConfig {
+export interface LwcCompilerConfig {
     name: string;
     namespace?: string;
     filename: string;
@@ -436,22 +453,6 @@ export interface CompilerResult {
 export interface BundleFiles {
     [filename: string]: string;
 }
-export interface Compiler {
-    convertToAmd(source: string, { id }: {
-        id: string;
-    }): Promise<CompilerResult>;
-    getModuleMetadata(compiledSource: string): Promise<Partial<CompiledMetadata>>;
-    lockerize(compiledModule: ModuleCompiled, lockerConfig: LwrLockerConfig, sourcemap: boolean): CompilerResult;
-    minifyJavascript(source: string): Promise<CompilerResult>;
-    parseJavascript(source: string, options: ParseOptions): Promise<CompilerResult>;
-    minifyCSS(source: string): Promise<CompilerResult>;
-}
-export interface ParseOptions {
-    envMode: string;
-}
-export interface CompilerContext {
-    runtimeEnvironment: RuntimeEnvironment;
-}
 export interface ClientBootstrapConfig {
     appId?: string;
     bootstrapModule: string;
@@ -494,15 +495,16 @@ export interface MetricsConfig {
 export interface ServerContext {
     appObserver: LwrAppObserver;
     appEmitter: LwrAppEmitter;
-    server: Server;
-    compiler: Compiler;
     moduleRegistry: ModuleRegistry;
     moduleBundler: ModuleBundler;
     viewRegistry: ViewRegistry;
     resourceRegistry: ResourceRegistry;
     assetRegistry: AssetRegistry;
+    watcherFactory?: WatcherFactory;
+    siteMetadata?: SiteMetadata;
     appConfig: NormalizedLwrGlobalConfig;
     runtimeEnvironment: RuntimeEnvironment;
+    routeHandlers: RouteHandlers;
 }
 export interface Observer<V> {
     next: (value: V) => void;
@@ -579,4 +581,46 @@ export interface LwrStringBuilder {
     toString(): string;
     original: string;
 }
+export interface SiteMetadata {
+    /**
+     * Get the path that all site metadata is relative to
+     */
+    getSiteRootDir(): string;
+    /**
+     * Get the current metadata about the pre-built module bundles for the site.
+     */
+    getSiteBundles(): SiteBundles;
+    /**
+     * Get the current metadata about the pre-built resources for the site.
+     */
+    getSiteResources(): SiteResources;
+    /**
+     * Get the current metadata about the pre-built assets for the site.
+     */
+    getSiteAssets(): SiteAssets;
+    /**
+     * To save out metadata for the current site
+     * @param staticRoot
+     * @returns
+     */
+    persistSiteMetadata(): Promise<void>;
+}
+export interface SiteBundles {
+    bundles: Record<string, SiteBundle>;
+}
+export interface SiteResources {
+    resources: Record<string, SiteArtifact>;
+}
+export interface SiteAssets {
+    assets: Record<string, SiteArtifact>;
+}
+export interface SiteArtifact {
+    path: string;
+    mimeType?: string;
+}
+export interface SiteBundle extends SiteArtifact {
+    version?: Version;
+    imports: string[];
+    includedModules?: string[];
+}
 //# sourceMappingURL=index.d.ts.map

package/build/server.d.ts

@@ -4,7 +4,7 @@ import { Application as ExpressApp } from 'express';
 import Koa, { Context } from 'koa';
 import http from 'http';
 import { Readable } from 'stream';
-import { RuntimeContext, RuntimeEnvironment } from './index';
+import type { NormalizedLwrGlobalConfig, RuntimeContext, RuntimeEnvironment } from './index.js';
 export declare type ServerTypes = 'koa' | 'express' | 'fs';
 export declare type ServerTypeImpl<T extends ServerTypes> = T extends 'koa' ? Koa : T extends 'express' ? ExpressApp : T extends 'fs' ? LwrDispatcher : never;
 export interface FsContext extends Context {
@@ -37,6 +37,7 @@ export interface InternalAppServer<T extends ServerTypes> {
 }
 export declare type PublicAppServer<T extends ServerTypes> = Pick<InternalAppServer<T>, 'use' | 'all' | 'get' | 'post' | 'getRegexWildcard'>;
 export declare type InternalAppServerOptions = {
+    app?: ServerTypeImpl<ServerTypes>;
     basePath?: string;
 };
 export interface InternalAppServerConstructable {
@@ -59,6 +60,9 @@ export interface MiddlewareRequest {
     acceptsLanguages(): string[];
     get(field: string): string | undefined;
     cookie(name: string): string | undefined;
+    /**
+     * Return true if the request has a `json` query parameter
+     */
     hasJsonParam(): boolean;
     /**
      * Return JSON if:
@@ -66,20 +70,27 @@ export interface MiddlewareRequest {
      *      - the Accept header explicitly requests "application/json"
      */
     isJsonRequest(): boolean;
+    /**
+     * Return true if the request was initiated by static generation
+     */
+    isSiteGeneration(): boolean;
     /**
      * Return false when both Accept and JSON query param are applied, but do not semantically match
      */
     validateJsonRequest(): boolean;
     /**
-     * Use the Express Request parameters to create a Module/Resource Identifier and RuntimeEnvironment
+     * Return true when the environment path parameter exists and is supported
+     */
+    validateEnvironmentRequest(config: NormalizedLwrGlobalConfig): boolean;
+    /**
+     * Use the request parameters to resolve the runtime context(ie. environment and parameters)
      */
     getRuntimeContext(defaultRuntimeEnvironment: RuntimeEnvironment): RuntimeContext;
-    isSiteGeneration(): boolean;
 }
 export interface MiddlewareResponse {
     set(header: any): void;
     setHeader(name: string, value: string | string[]): void;
-    setMetadata(metadata: any): void;
+    setSiteGenerationMetadata(metadata: any): void;
     status(status: number): MiddlewareResponse;
     send(object: any): void;
     sendStatus(httpCode: number): void;

package/build/views.d.ts

@@ -1,5 +1,5 @@
 /// <reference types="node" />
-import { RouteHandlerFunction, RouteHandlerView, View } from './config.js';
+import { LwrErrorRoute, LwrRoute, RouteHandlerFunction, RouteHandlerView, View } from './config.js';
 import { AssetSource, AssetUri, Endpoints, FlattenedModuleGraphs, ImportMetadata, Json, LwrStringBuilder, ResourceDefinition, RuntimeEnvironment, RuntimeParams, Specifier, TransformPluginContext } from './index.js';
 export declare type ViewIdentity = Pick<View, 'rootComponent' | 'contentTemplate'>;
 export interface ViewSource {
@@ -82,6 +82,7 @@ export interface LinkedViewDefinition {
     renderedView: string;
     viewRecord: RenderedViewRecord;
     immutable: boolean;
+    cache?: CacheResponse;
 }
 interface ViewRequestQs {
     [key: string]: undefined | string | string[];
@@ -136,6 +137,7 @@ declare type ViewPluginLinkHook = (builder: LwrStringBuilder, viewContext: ViewT
 declare type ViewPluginLinkHookReturn = void | null | undefined | false | LwrStringBuilder | {
     builder?: LwrStringBuilder;
     context?: TransformPluginContext;
+    cache?: CacheResponse;
 };
 declare type ViewPluginOptimizeHook = (code: string, assetSource: AssetSource, context?: TransformPluginContext) => Promise<ViewPluginOptimizeHookReturn>;
 declare type ViewPluginOptimizeHookReturn = null | undefined | false | string | {
@@ -174,6 +176,7 @@ export declare type ViewModuleResourceContext = {
 };
 export interface ViewRegistry {
     addViewProviders(providers: ViewProvider[]): void;
+    addViewTransformers(transformers: ViewTransformPlugin[]): void;
     initializeViewProviders(): Promise<void[]>;
     getView(viewId: ViewIdentity, skipCaching?: boolean): Promise<CompiledView>;
     getViewDefinition<R extends RuntimeEnvironment>(view: View, viewParams: ViewParams, runtimeEnvironment: R, runtimeParams?: RuntimeParams, renderOptions?: RenderOptions): Promise<LinkedViewDefinition>;
@@ -181,6 +184,11 @@ export interface ViewRegistry {
     getPublicApi(): PublicViewRegistry;
 }
 export declare type PublicViewRegistry = Pick<ViewRegistry, 'getView' | 'getViewDefinition'>;
+export interface ViewHandler {
+    getViewContent(viewRequest: ViewRequest, route: LwrRoute | LwrErrorRoute, runtimeEnvironment: RuntimeEnvironment, runtimeParams: RuntimeParams): Promise<ViewResponse>;
+    getViewJson(viewRequest: ViewRequest, route: LwrRoute | LwrErrorRoute, runtimeEnvironment: RuntimeEnvironment, runtimeParams: RuntimeParams): Promise<ViewResponse>;
+    getViewConfiguration(viewRequest: ViewRequest, route: LwrRoute | LwrErrorRoute, runtimeEnvironment: RuntimeEnvironment, runtimeParams: RuntimeParams): Promise<ViewResponse | undefined>;
+}
 export interface SsrRequestContext {
     props: Json;
     params: {
@@ -201,6 +209,7 @@ export interface PageDataResponse {
             fetchpriority?: 'high' | 'low' | 'auto';
         }[];
     };
+    cache?: CacheResponse;
 }
 export {};
 //# sourceMappingURL=views.d.ts.map

package/package.json

@@ -8,15 +8,15 @@
         "build": "tsc -b"
     },
     "type": "module",
-    "version": "0.9.0-alpha.2",
+    "version": "0.9.0-alpha.21",
     "homepage": "https://developer.salesforce.com/docs/platform/lwr/overview",
     "repository": {
         "type": "git",
-        "url": "https://github.com/salesforce/lwr.git",
+        "url": "https://github.com/salesforce-experience-platform-emu/lwr.git",
         "directory": "packages/@lwrjs/types"
     },
     "bugs": {
-        "url": "https://github.com/salesforce/lwr/issues"
+        "url": "https://github.com/salesforce-experience-platform-emu/lwr/issues"
     },
     "main": "build/index.js",
     "files": [
@@ -26,5 +26,12 @@
     "engines": {
         "node": ">=14.15.4 <19"
     },
-    "gitHead": "bcf63de23d1a2a53fb0e961dba4396e8753710dd"
+    "devDependencies": {
+        "chokidar": "^3.5.3"
+    },
+    "volta": {
+        "node": "14.19.1",
+        "yarn": "1.22.19"
+    },
+    "gitHead": "a89adcac80601f657becd6fd734c765e6b2a2745"
 }