Merge pull request #623 from smapiot/develop

Release 1.2.0

CHANGELOG.md

@@ -1,5 +1,15 @@
 # Piral Changelog
 
+## 1.2.0 (tbd)
+
+- Fixed issue with `loader-utils` version
+- Fixed issue with potential URL flickering using `piral-ng`
+- Fixed build issue in codegen of `piral-core` on Windows (#619)
+- Updated `importmap` with `exclude` key allowing exclusions
+- Added support for `dependencySymbols` in `piral-blazor`
+- Added option to stop module teardown via `flags` parameter in `piral-ng`
+- Added abort `signal` to `piral-fetch` options (#621)
+
 ## 1.1.0 (July 25, 2023)
 
 - Fixed retrieval of dep versions not exporting their *package.json*

docs/concepts/I08-importmap.md

@@ -14,7 +14,7 @@ In general, Piral distinguishes between three types of dependencies:
 - centrally shared dependencies, i.e., dependencies that are already bundled with an app shell, but otherwise not optimized
 - distributed shared dependencies, i.e., dependencies that are shipped (not bundled) unoptimized with a pilet - such that other pilets can use them, too
 
-Besides the standard `imports` key of the importmaps specification, the `piral-cli` also allows a new key called `inherit`. This one can be used to specify packages coming with an importmap.
+Besides the standard `imports` key of the importmaps specification, the `piral-cli` also allows new keys called `inherit` and `exclude`. While `inherit` can be used to specify packages coming with an importmap the `exclude` property can be used to exclude dependencies from inherited importmaps.
 
 ## Piral Instance Importmaps
 
@@ -98,6 +98,16 @@ This way, you can either create reusable packages containing importmaps or easil
 }
 ```
 
+Alternatively, you can still inherit from a package but exclude certain packages using the `exclude` keyword. For instance, using the following notation `piral-base` and `piral-core` are still inherited (importing, among other things, `react`, `react-dom`, `react-router`, and `react-router-dom`), however, `react-dom` is being excluded from these imports.
+
+```json
+{
+  "imports": {},
+  "inherit": ["piral-base", "piral-core"],
+  "exclude": "react-dom"
+}
+```
+
 Classically, all centrally shared dependencies are delivered with the app shell ("single bundle"). In some case it might make sense to load a shared dependency only when needed. To enable this behavior you can suffix the dependency with the `?` character - indicating that the shared dependency is optional:
 
 ```json
@@ -176,6 +186,18 @@ Consequently, the following
 
 will add `emojis-list` as a distributed dependency (adding a side-bundle for the dependency to the assets) and treat any dependency exposed by the `my-app-shell` as a centrally shared dependency.
 
+If you want to bundle in a dependency that is already declared as a centrally shared dependency in the app shell you can use the `exclude` keyword. For instance, the following call declares the packages shared from `my-app-shell` as external with exception of the `react` package:
+
+```json
+{
+  "imports": {},
+  "inherit": ["my-app-shell"],
+  "exclude": ["react"]
+}
+```
+
+If a dependency is both excluded and marked as a distributed dependency in the `imports` section then the latter wins - explicit imports are always more relevant than exclusions from the inheritance chain.
+
 ## Importmap Notation
 
 The importmap notation also allows some special syntax that can be used to set up some rules for the dependency. For instance,
@@ -277,3 +299,7 @@ The precedence of the lookup is:
 
 1. See if `<inherited-name>/package.json` exists. Follow up on any `importmap` property from the file if exists.
 2. See if `<inherited-name>` exists. Take it if it exists. **Note**: This has to be an importmap (JSON) then.
+
+## Exclusions
+
+Exclusions work across all inherited packages - directly and indirectly. This way, you can also make general statements about bundling. For instance, you might want to put a dependency in `exclude` that you *want* to see bundled - independent if it appears (right now) in the inherited importmaps or not.

src/converters/piral-blazor/src/dependencies.ts

@@ -6,6 +6,11 @@ import type { BlazorDependencyLoader, BlazorRootConfig } from './types';
 const loadedDependencies = (window.$blazorDependencies ??= []);
 const depsWithPrios = (window.$blazorDependencyPrios ??= []);
 
+function toPdb(url: string) {
+  const front = url.substring(0, url.length - 4);
+  return `${front}.pdb`;
+}
+
 export function createDependencyLoader(convert: ReturnType<typeof createConverter>) {
   const definedBlazorReferences: Array<string> = [];
   const loadedBlazorPilets: Array<string> = [];
@@ -41,9 +46,8 @@ export function createDependencyLoader(convert: ReturnType<typeof createConverte
 
           const dependencies = references.filter((m) => m.endsWith('.dll'));
           const dllUrl = dependencies.pop();
-          const piletName = dllUrl.substring(0, dllUrl.length - 4);
-          const piletPdb = `${piletName}.pdb`;
-          const pdbUrl = references.find((m) => m === piletPdb);
+          const pdbUrl = toPdb(dllUrl);
+          const dependencySymbols = dependencies.map(toPdb).filter(dep => references.includes(dep));
           const id = Math.random().toString(26).substring(2);
 
           await loadBlazorPilet(id, {
@@ -52,9 +56,10 @@ export function createDependencyLoader(convert: ReturnType<typeof createConverte
             config: JSON.stringify(meta.config || {}),
             baseUrl: meta.basePath || dllUrl.substring(0, dllUrl.lastIndexOf('/')).replace('/_framework/', '/'),
             dependencies,
+            dependencySymbols: capabilities.includes('dependency-symbols') ? dependencySymbols : undefined,
             satellites,
             dllUrl,
-            pdbUrl,
+            pdbUrl: references.includes(pdbUrl) ? pdbUrl : undefined,
           });
 
           loadedBlazorPilets.push(id);

src/converters/piral-blazor/src/interop.ts

@@ -218,6 +218,7 @@ export interface PiletData {
   baseUrl: string;
   satellites?: Record<string, Array<string>>;
   dependencies: Array<string>;
+  dependencySymbols?: Array<string>;
 }
 
 export function loadBlazorPilet(id: string, data: PiletData) {

src/converters/piral-ng/src/RoutingService.ts

@@ -64,6 +64,10 @@ export class RoutingService implements OnDestroy {
       const skipIds: Array<number> = [];
       const nav = this.context.navigation;
 
+      const queueNavigation = (url: string) => {
+        window.requestAnimationFrame(() => nav.push(url));
+      };
+
       this.dispose = nav.listen(({ location }) => {
         const path = location.pathname;
 
@@ -84,7 +88,7 @@ export class RoutingService implements OnDestroy {
           }
 
           if (routerUrl !== locationUrl) {
-            nav.push(routerUrl);
+            queueNavigation(routerUrl);
           }
         } else if (e.type === 0 && skipNavigation) {
           skipIds.push(e.id);
@@ -97,7 +101,7 @@ export class RoutingService implements OnDestroy {
             const routerUrl = e.routerEvent.url;
 
             if (routerUrl !== locationUrl) {
-              nav.push(routerUrl);
+              queueNavigation(routerUrl);
             }
           } else {
             skipIds.splice(index, 1);

src/converters/piral-ng/src/bootstrap.ts

@@ -17,7 +17,7 @@ export async function prepareBootstrap(
           throw new Error('The lazy loaded module does not `default` export a NgModule class.');
         }
 
-        defineModule(result.default, moduleOrComponent.opts);
+        defineModule(result.default, moduleOrComponent.opts, moduleOrComponent.flags);
         return findModule(result.default);
       });
     }
@@ -59,8 +59,8 @@ export async function bootstrap<TProps extends BaseComponentProps>(
   props: BehaviorSubject<TProps>,
   context: ComponentContext,
 ): Promise<Disposable> {
-  const [selectedModule, ngOptions, component] = result;
-  const ref = await startup(selectedModule, context, ngOptions);
+  const [selectedModule, ngOptions, ngFlags, component] = result;
+  const ref = await startup(selectedModule, context, ngOptions, ngFlags);
 
   if (ref) {
     ref.instance.attach(component, node, props);

src/converters/piral-ng/src/module.ts

@@ -1,13 +1,14 @@
 import type { PiletApi } from 'piral-core';
 import type { BehaviorSubject } from 'rxjs';
-import type { NgOptions, ModuleInstanceResult } from './types';
+import type { NgOptions, ModuleInstanceResult, NgModuleFlags } from './types';
 import { BrowserModule } from '@angular/platform-browser';
 import { CommonModule } from '@angular/common';
 import {
   ApplicationRef,
   ComponentFactoryResolver,
   ComponentRef,
   CUSTOM_ELEMENTS_SCHEMA,
+  Inject,
   NgModule,
   NgZone,
 } from '@angular/core';
@@ -21,6 +22,7 @@ interface ModuleDefinition {
   module: any;
   components: Array<any>;
   opts: NgOptions;
+  flags: NgModuleFlags;
 }
 
 const availableModules: Array<ModuleDefinition> = [];
@@ -45,7 +47,12 @@ function instantiateModule(moduleDef: ModuleDefinition, piral: PiletApi) {
     private appRef: ApplicationRef;
     private refs: Array<[any, HTMLElement, ComponentRef<any>]> = [];
 
-    constructor(private resolver: ComponentFactoryResolver, private zone: NgZone, public routing: RoutingService) {}
+    constructor(
+      private resolver: ComponentFactoryResolver,
+      private zone: NgZone,
+      public routing: RoutingService,
+      @Inject('NgFlags') private flags: NgModuleFlags,
+    ) {}
 
     ngDoBootstrap(appRef: ApplicationRef) {
       this.appRef = appRef;
@@ -81,7 +88,7 @@ function instantiateModule(moduleDef: ModuleDefinition, piral: PiletApi) {
         }
       }
 
-      if (this.refs.length === 0) {
+      if (!this.flags?.keepAlive && this.refs.length === 0) {
         teardown(BootstrapModule);
       }
     }
@@ -95,7 +102,7 @@ export function activateModuleInstance(moduleDef: ModuleDefinition, piral: Pilet
     moduleDef.active = instantiateModule(moduleDef, piral);
   }
 
-  return [moduleDef.active, moduleDef.opts];
+  return [moduleDef.active, moduleDef.opts, moduleDef.flags];
 }
 
 export function getModuleInstance(component: any, standalone: boolean, piral: PiletApi) {
@@ -140,14 +147,15 @@ export function findModule(module: any) {
   return availableModules.find((m) => m.module === module);
 }
 
-export function defineModule(module: any, opts: NgOptions = undefined) {
+export function defineModule(module: any, opts: NgOptions = undefined, flags: NgModuleFlags = undefined) {
   const [annotation] = getAnnotations(module);
 
   if (annotation) {
     availableModules.push({
       active: undefined,
       components: findComponents(annotation.exports),
       module,
+      flags,
       opts,
     });
   } else if (typeof module === 'function') {
@@ -156,7 +164,7 @@ export function defineModule(module: any, opts: NgOptions = undefined) {
     };
 
     return (selector: string) => ({
-      component: { selector, module, opts, state },
+      component: { selector, module, opts, flags, state },
       type: 'ng' as const,
     });
   }

src/converters/piral-ng/src/startup.ts

@@ -1,5 +1,5 @@
 import type { ComponentContext } from 'piral-core';
-import type { NgOptions } from './types';
+import type { NgModuleFlags, NgOptions } from './types';
 import {
   createPlatformFactory,
   enableProdMode,
@@ -31,11 +31,12 @@ const customPlatformDynamicFactory = createPlatformFactory(platformCoreDynamic,
 ]);
 const runningModules: Array<[any, NgModuleInt, PlatformRef]> = [];
 
-function startNew(BootstrapModule: any, context: ComponentContext, ngOptions?: NgOptions) {
+function startNew(BootstrapModule: any, context: ComponentContext, ngOptions?: NgOptions, ngFlags?: NgModuleFlags) {
   const path = context.publicPath || '/';
   const platform = customPlatformDynamicFactory([
     { provide: 'Context', useValue: context },
     { provide: APP_BASE_HREF, useValue: path },
+    { provide: 'NgFlags', useValue: ngFlags },
   ]);
   const id = getId();
   const zoneIdentifier = `piral-ng:${id}`;
@@ -87,6 +88,7 @@ export function startup(
   BootstrapModule: any,
   context: ComponentContext,
   ngOptions?: NgOptions,
+  ngFlags?: NgModuleFlags,
 ): Promise<void | NgModuleInt> {
   const runningModule = runningModules.find(([ref]) => ref === BootstrapModule);
 
@@ -100,7 +102,7 @@ export function startup(
     }
   }
 
-  return startNew(BootstrapModule, context, ngOptions);
+  return startNew(BootstrapModule, context, ngOptions, ngFlags);
 }
 
 if (process.env.NODE_ENV === 'development') {

src/converters/piral-ng/src/types.ts

@@ -10,6 +10,13 @@ declare module 'piral-core/lib/types/custom' {
   }
 }
 
+export interface NgModuleFlags {
+  /**
+   * If set to true prevents the module from being disposed.
+   */
+  keepAlive?: boolean;
+}
+
 /**
  * Options passed through to Angular `bootstrapModule`.
  *
@@ -18,7 +25,7 @@ declare module 'piral-core/lib/types/custom' {
  */
 export type NgOptions = Parameters<PlatformRef['bootstrapModule']>[1];
 
-export type ModuleInstanceResult = [any, NgOptions];
+export type ModuleInstanceResult = [any, NgOptions, NgModuleFlags];
 
 export type PrepareBootstrapResult = [...ModuleInstanceResult, any];
 
@@ -39,6 +46,7 @@ export interface NgLazyType {
   selector: string;
   module: () => Promise<{ default: Type<any> }>;
   opts: NgOptions;
+  flags: NgModuleFlags;
   state: any;
 }
 
@@ -60,15 +68,17 @@ export interface NgModuleDefiner {
    * Defines the module to use when bootstrapping the Angular pilet.
    * @param ngModule The module to use for running Angular.
    * @param opts The options to pass when bootstrapping.
+   * @param flags The flags to use when dealing with the module.
    */
-  <T>(module: Type<T>, opts?: NgOptions): void;
+  <T>(module: Type<T>, opts?: NgOptions, flags?: NgModuleFlags): void;
   /**
    * Defines the module to lazy load for bootstrapping the Angular pilet.
    * @param getModule The module lazy loader to use for running Angular.
    * @param opts The options to pass when bootstrapping.
+   * @param flags The flags to use when dealing with the module.
    * @returns The module ID to be used to reference components.
    */
-  <T>(getModule: LazyType<T>, opts?: NgOptions): NgComponentLoader;
+  <T>(getModule: LazyType<T>, opts?: NgOptions, flags?: NgModuleFlags): NgComponentLoader;
 }
 
 export interface NgComponent {

src/framework/piral-core/src/tools/codegen.ts

@@ -1,7 +1,7 @@
 // this file is bundled, so the references here will not be at runtime (i.e., for a user)
 import { getModulePath } from 'piral-cli/src/external/resolve';
 import { readFileSync, existsSync } from 'fs';
-import { resolve, relative, dirname } from 'path';
+import { resolve, relative, dirname, sep, posix } from 'path';
 
 function findPackagePath(moduleDir: string) {
   const packageJson = 'package.json';
@@ -66,7 +66,11 @@ function getIdentifiers(root: string, packageName: string) {
 function getModulePathOrDefault(root: string, origin: string, name: string) {
   try {
     const absPath = getModulePath(root, name);
-    const path = relative(origin, absPath);
+    const relPath = relative(origin, absPath);
+
+    // The relative path is to be used in an import statement,
+    // so it should be normalized back to use posix path separators.
+    const path = relPath.split(sep).join(posix.sep);
     return path;
   } catch {
     return name;

src/plugins/piral-fetch/src/fetch.ts

@@ -9,7 +9,7 @@ export function httpFetch<T>(config: FetchConfig, path: string, options: FetchOp
   const baseInit = config.default || {};
   const baseHeaders = baseInit.headers || {};
   const baseUrl = config.base || location.origin;
-  const { method = 'get', body, headers = {}, cache = baseInit.cache, mode = baseInit.mode, result = 'auto' } = options;
+  const { method = 'get', body, headers = {}, cache = baseInit.cache, mode = baseInit.mode, result = 'auto', signal } = options;
   const json =
     Array.isArray(body) ||
     typeof body === 'number' ||
@@ -25,6 +25,7 @@ export function httpFetch<T>(config: FetchConfig, path: string, options: FetchOp
     },
     cache,
     mode,
+    signal,
   };
 
   if (json) {

src/plugins/piral-fetch/src/types.ts

@@ -33,6 +33,10 @@ export interface FetchOptions {
    * @default 'auto'
    */
   result?: 'auto' | 'json' | 'text';
+  /**
+   * Sets the Abort Signal to cancel the request.
+   */
+  signal?: AbortSignal;
 }
 
 export interface FetchResponse<T> {

src/tooling/piral-cli-webpack5/package.json

@@ -64,6 +64,7 @@
     "express": "^4.17.1",
     "html-entities": "^1.2.0",
     "html-webpack-plugin": "^5.5.3",
+    "loader-utils": "^2.0.0",
     "mini-css-extract-plugin": "^2.7.6",
     "parcel-codegen-loader": "^1.0.0",
     "querystring": "^0.2.0",