@nutin/cli 1.3.0 → 2.0.0

package/templates/base/src/core/services/event-bus/lifecycle.facade.test.js.hbs

@@ -0,0 +1,123 @@
+import { Lifecycle, AppEventBus } from '#root/dist/src/core/index.js';
+
+describe('LifecycleFacade (Lifecycle)', () => {
+  afterEach(() => {
+    AppEventBus.cleanupEventListeners();
+  });
+
+  it('beforeRender emits "before-render"', () => {
+    const emit = spyOn(AppEventBus, 'emit');
+    Lifecycle.beforeRender();
+    expect(emit).toHaveBeenCalledWith('before-render');
+    emit.restore();
+  });
+
+  it('onBeforeRender subscribes to "before-render", and the returned unsubscribe removes it', () => {
+    let called = 0;
+    const unsubscribe = Lifecycle.onBeforeRender(() => called++);
+
+    Lifecycle.beforeRender();
+    expect(called).toBe(1);
+
+    unsubscribe();
+    Lifecycle.beforeRender();
+    expect(called).toBe(1);
+  });
+
+  it('afterRender emits "after-render"', () => {
+    const emit = spyOn(AppEventBus, 'emit');
+    Lifecycle.afterRender();
+    expect(emit).toHaveBeenCalledWith('after-render');
+    emit.restore();
+  });
+
+  it('onAfterRender subscribes to "after-render", and the returned unsubscribe removes it', () => {
+    let called = 0;
+    const unsubscribe = Lifecycle.onAfterRender(() => called++);
+
+    Lifecycle.afterRender();
+    expect(called).toBe(1);
+
+    unsubscribe();
+    Lifecycle.afterRender();
+    expect(called).toBe(1);
+  });
+
+  it('beforeDestroy emits "before-destroy"', () => {
+    const emit = spyOn(AppEventBus, 'emit');
+    Lifecycle.beforeDestroy();
+    expect(emit).toHaveBeenCalledWith('before-destroy');
+    emit.restore();
+  });
+
+  it('onBeforeDestroy subscribes to "before-destroy", and the returned unsubscribe removes it', () => {
+    let called = 0;
+    const unsubscribe = Lifecycle.onBeforeDestroy(() => called++);
+
+    Lifecycle.beforeDestroy();
+    expect(called).toBe(1);
+
+    unsubscribe();
+    Lifecycle.beforeDestroy();
+    expect(called).toBe(1);
+  });
+
+  it('afterDestroy emits "after-destroy"', () => {
+    const emit = spyOn(AppEventBus, 'emit');
+    Lifecycle.afterDestroy();
+    expect(emit).toHaveBeenCalledWith('after-destroy');
+    emit.restore();
+  });
+
+  it('onAfterDestroy subscribes to "after-destroy", and the returned unsubscribe removes it', () => {
+    let called = 0;
+    const unsubscribe = Lifecycle.onAfterDestroy(() => called++);
+
+    Lifecycle.afterDestroy();
+    expect(called).toBe(1);
+
+    unsubscribe();
+    Lifecycle.afterDestroy();
+    expect(called).toBe(1);
+  });
+
+  it('viewMount emits "view-mount" with { viewName }', () => {
+    const emit = spyOn(AppEventBus, 'emit');
+    Lifecycle.viewMount('home');
+    expect(emit).toHaveBeenCalledWith('view-mount', { viewName: 'home' });
+    emit.restore();
+  });
+
+  it('onViewMount subscribes to "view-mount", and the returned unsubscribe removes it', () => {
+    let received = null;
+    const unsubscribe = Lifecycle.onViewMount((data) => { received = data; });
+
+    Lifecycle.viewMount('home');
+    expect(received).toEqual({ viewName: 'home' });
+
+    unsubscribe();
+    received = null;
+    Lifecycle.viewMount('other');
+    expect(received).toBe(null);
+  });
+
+  it('viewUnmount emits "view-unmount" with { viewName }', () => {
+    const emit = spyOn(AppEventBus, 'emit');
+    Lifecycle.viewUnmount('home');
+    expect(emit).toHaveBeenCalledWith('view-unmount', { viewName: 'home' });
+    emit.restore();
+  });
+
+  it('onViewUnmount subscribes to "view-unmount", and the returned unsubscribe removes it', () => {
+    let received = null;
+    const unsubscribe = Lifecycle.onViewUnmount((data) => { received = data; });
+
+    Lifecycle.viewUnmount('home');
+    expect(received).toEqual({ viewName: 'home' });
+
+    unsubscribe();
+    received = null;
+    Lifecycle.viewUnmount('other');
+    expect(received).toBe(null);
+  });
+});

package/templates/base/src/core/services/event-bus/lifecycle.facade.ts.hbs

@@ -0,0 +1,61 @@
+import { AppEventBus, IEventBus } from "./event-bus.js";
+
+class LifecycleFacade {
+  constructor(private bus: IEventBus) {}
+
+  beforeRender(): void {
+    this.bus.emit('before-render');
+  }
+
+  onBeforeRender(callback: () => void): () => void {
+    this.bus.subscribe('before-render', callback);
+    return () => this.bus.off('before-render', callback);
+  }
+
+  afterRender(): void {
+    this.bus.emit('after-render');
+  }
+
+  onAfterRender(callback: () => void): () => void {
+    this.bus.subscribe('after-render', callback);
+    return () => this.bus.off('after-render', callback);
+  }
+
+  beforeDestroy(): void {
+    this.bus.emit('before-destroy');
+  }
+
+  onBeforeDestroy(callback: () => void): () => void {
+    this.bus.subscribe('before-destroy', callback);
+    return () => this.bus.off('before-destroy', callback);
+  }
+
+  afterDestroy(): void {
+    this.bus.emit('after-destroy');
+  }
+
+  onAfterDestroy(callback: () => void): () => void {
+    this.bus.subscribe('after-destroy', callback);
+    return () => this.bus.off('after-destroy', callback);
+  }
+
+  viewMount(viewName: string): void {
+    this.bus.emit('view-mount', {viewName});
+  }
+
+  onViewMount(callback: (data: { viewName: string }) => void): () => void {
+    this.bus.subscribe('view-mount', callback);
+    return () => this.bus.off('view-mount', callback);
+  }
+
+  viewUnmount(viewName: string): void {
+    this.bus.emit('view-unmount', { viewName });
+  }
+
+  onViewUnmount(callback: (data: { viewName: string }) => void): () => void {
+    this.bus.subscribe('view-unmount', callback);
+    return () => this.bus.off('view-unmount', callback);
+  }
+}
+
+export const Lifecycle = new LifecycleFacade(AppEventBus);

package/templates/base/src/core/services/event-bus/navigation.facade.test.js.hbs

@@ -0,0 +1,46 @@
+import { Navigation, AppEventBus } from '#root/dist/src/core/index.js';
+
+describe('NavigationFacade (Navigation)', () => {
+  afterEach(() => {
+    AppEventBus.cleanupEventListeners();
+  });
+
+  it('navigateTo emits "navigate" with { path }', () => {
+    const emit = spyOn(AppEventBus, 'emit');
+    Navigation.navigateTo('/about');
+    expect(emit).toHaveBeenCalledWith('navigate', { path: '/about' });
+    emit.restore();
+  });
+
+  it('onNavigate subscribes to "navigate", and the returned unsubscribe removes it', () => {
+    let received = null;
+    const unsubscribe = Navigation.onNavigate((data) => { received = data; });
+
+    Navigation.navigateTo('/about');
+    expect(received).toEqual({ path: '/about' });
+
+    unsubscribe();
+    received = null;
+    Navigation.navigateTo('/contact');
+    expect(received).toBe(null);
+  });
+
+  it('reload emits "reload"', () => {
+    const emit = spyOn(AppEventBus, 'emit');
+    Navigation.reload();
+    expect(emit).toHaveBeenCalledWith('reload');
+    emit.restore();
+  });
+
+  it('onReload subscribes to "reload", and the returned unsubscribe removes it', () => {
+    let called = 0;
+    const unsubscribe = Navigation.onReload(() => called++);
+
+    Navigation.reload();
+    expect(called).toBe(1);
+
+    unsubscribe();
+    Navigation.reload();
+    expect(called).toBe(1);
+  });
+});

package/templates/base/src/core/services/event-bus/navigation.facade.ts.hbs

@@ -0,0 +1,25 @@
+import { AppEventBus, IEventBus } from "./event-bus.js";
+
+class NavigationFacade {
+  constructor(private bus: IEventBus) {}
+
+  navigateTo(path: string): void {
+    this.bus.emit('navigate', { path });
+  }
+
+  onNavigate(callback: (data: { path: string }) => void): () => void {
+    this.bus.subscribe('navigate', callback);
+    return () => this.bus.off('navigate', callback);
+  }
+
+  reload(): void {
+    this.bus.emit('reload');
+  }
+
+  onReload(callback: () => void): () => void {
+    this.bus.subscribe('reload', callback);
+    return () => this.bus.off('reload', callback);
+  }
+}
+
+export const Navigation = new NavigationFacade(AppEventBus);

package/templates/base/src/core/services/globals/globals.test.js.hbs

@@ -0,0 +1,149 @@
+import { registerGlobals, hideGlobals, revealGlobals, Globals } from '#root/dist/src/core/services/globals/globals.js';
+
+function makeComponent(tag = 'div') {
+  return class {
+    constructor(mountTarget) {
+      this.mountTarget = mountTarget;
+    }
+    render() {
+      return document.createElement(tag);
+    }
+  };
+}
+
+describe('globals (registerGlobals)', () => {
+  afterEach(() => {
+    // registerGlobals mounts directly onto document.body (a sibling of the
+    // pre-existing <main id="app">), so only strip what each test added.
+    [...document.body.children].forEach((el) => {
+      if (el.id !== 'app') el.remove();
+    });
+    // Globals is a process-wide singleton (like every other Service) - drop
+    // its registered-id state so a later test's ids can't collide with an
+    // earlier one's.
+    Globals.testingResetAll();
+  });
+
+  it('is defined', () => {
+    expect(registerGlobals).toBeDefined();
+  });
+
+  it('touches nothing when called with no options', () => {
+    registerGlobals({});
+    expect(document.body.children.length).toBe(1); // just #app
+  });
+
+  it('prepends a single "before" entry ahead of the existing #app, stamping its id', () => {
+    registerGlobals({ before: [{ component: makeComponent('header'), id: 'header' }] });
+    expect(document.body.firstElementChild.tagName).toBe('HEADER');
+    expect(document.body.firstElementChild.id).toBe('header');
+    expect(document.body.children[1].id).toBe('app');
+  });
+
+  it('appends a single "after" entry behind the existing #app, stamping its id', () => {
+    registerGlobals({ after: [{ component: makeComponent('footer'), id: 'footer' }] });
+    expect(document.body.lastElementChild.tagName).toBe('FOOTER');
+    expect(document.body.lastElementChild.id).toBe('footer');
+  });
+
+  it('mounts multiple "before" entries in the given order (not reversed)', () => {
+    registerGlobals({
+      before: [
+        { component: makeComponent('div'), id: 'first' },
+        { component: makeComponent('div'), id: 'second' },
+      ],
+    });
+    const ids = [...document.body.children].filter((el) => el.id !== 'app').map((el) => el.id);
+    expect(ids).toEqual(['first', 'second']);
+  });
+
+  it('mounts multiple "after" entries in the given order (not reversed)', () => {
+    registerGlobals({
+      after: [
+        { component: makeComponent('div'), id: 'first' },
+        { component: makeComponent('div'), id: 'second' },
+      ],
+    });
+    const ids = [...document.body.children].filter((el) => el.id !== 'app').map((el) => el.id);
+    expect(ids).toEqual(['first', 'second']);
+  });
+
+  it('passes the same mountTarget value through to every constructed component', () => {
+    const seen = [];
+    class TrackingComponent {
+      constructor(mountTarget) {
+        seen.push(mountTarget);
+      }
+      render() {
+        return document.createElement('div');
+      }
+    }
+    registerGlobals({
+      before: [{ component: TrackingComponent, id: 'a' }],
+      after: [{ component: TrackingComponent, id: 'b' }],
+    });
+    expect(seen).toEqual(['body', 'body']);
+  });
+
+  it('registering a duplicate id warns and skips the second mount', () => {
+    const warnSpy = spyOn(console, 'warn');
+    warnSpy.andCallFake(() => {});
+
+    registerGlobals({ before: [{ component: makeComponent('header'), id: 'dup' }] });
+    registerGlobals({ after: [{ component: makeComponent('footer'), id: 'dup' }] });
+
+    const matches = [...document.body.children].filter((el) => el.id === 'dup');
+    expect(matches.length).toBe(1);
+    expect(matches[0].tagName).toBe('HEADER');
+    expect(warnSpy.callCount).toBe(1);
+
+    warnSpy.restore();
+  });
+});
+
+describe('globals (hideGlobals/revealGlobals)', () => {
+  afterEach(() => {
+    [...document.body.children].forEach((el) => {
+      if (el.id !== 'app') el.remove();
+    });
+  });
+
+  it('toggle display for every given id that is present', () => {
+    const header = document.createElement('div');
+    header.id = 'header';
+    document.body.appendChild(header);
+    const footer = document.createElement('div');
+    footer.id = 'footer';
+    document.body.appendChild(footer);
+
+    hideGlobals(['header', 'footer']);
+    expect(header.style.display).toBe('none');
+    expect(footer.style.display).toBe('none');
+
+    revealGlobals(['header', 'footer']);
+    expect(header.style.display).toBe('block');
+    expect(footer.style.display).toBe('block');
+  });
+
+  it('only touch the display property, leaving other inline styles intact', () => {
+    const header = document.createElement('div');
+    header.id = 'header';
+    header.style.cssText = 'background: coral; padding: 8px';
+    document.body.appendChild(header);
+
+    hideGlobals(['header']);
+    expect(header.style.display).toBe('none');
+    expect(header.style.background).toBe('coral');
+    expect(header.style.padding).toBe('8px');
+
+    revealGlobals(['header']);
+    expect(header.style.display).toBe('block');
+    expect(header.style.background).toBe('coral');
+    expect(header.style.padding).toBe('8px');
+  });
+
+  it('are no-ops for ids that are absent', () => {
+    expect(() => hideGlobals(['missing'])).not.toThrow();
+    expect(() => revealGlobals(['missing'])).not.toThrow();
+  });
+});

package/templates/base/src/core/services/globals/globals.ts.hbs

@@ -0,0 +1,95 @@
+import { Service } from '../../base-classes/index.js';
+
+export interface GlobalMountable {
+  render(): HTMLElement;
+  destroy?(): void;
+}
+
+export interface GlobalConfig<T extends GlobalMountable = GlobalMountable> {
+  /** The component's own class — constructed internally as `new component(mountTarget)`. */
+  component: new (mountTarget: HTMLElement) => T;
+  /** Stamped onto the mounted root element; pass this same id to `hideGlobals`/`revealGlobals`. */
+  id: string;
+}
+
+export interface RegisterGlobalsOptions {
+  /** Rendered and prepended to `<body>`, in the given order (e.g. a header). */
+  before?: GlobalConfig[];
+  /** Rendered and appended to `<body>`, in the given order (e.g. a footer). */
+  after?: GlobalConfig[];
+}
+
+export class Globals extends Service<Globals> {
+  private _mounted: Record<string, GlobalMountable> = {};
+
+  constructor() { super(); }
+
+  public register({ before = [], after = [] }: RegisterGlobalsOptions): void {
+    // Component subclasses generated via `nutin generate component` type their
+    // mountTarget param as HTMLElement, but DomHelper.mountElement only
+    // *appends* (rather than replacing) the target when mountTarget is a string
+    // selector. This cast satisfies the stricter constructor type while still
+    // passing the string 'body' through at runtime, so components append into
+    // <body> instead of replacing it.
+    const mountTarget = 'body' as unknown as HTMLElement;
+    const isElement = (el: HTMLElement | null): el is HTMLElement => el !== null;
+
+    const mount = ({ component: Component, id }: GlobalConfig): HTMLElement | null => {
+      if (this._mounted[id]) {
+        console.warn(`Global "${id}" is already registered - skipping.`);
+        return null;
+      }
+      const instance = new Component(mountTarget);
+      const element = instance.render();
+      element.id = id;
+      this._mounted[id] = instance;
+      return element;
+    };
+
+    document.body.prepend(...before.map(mount).filter(isElement));
+    document.body.append(...after.map(mount).filter(isElement));
+  }
+
+  public hide(globalIds: string[]): void {
+    this.setDisplay(globalIds, 'none');
+  }
+
+  public reveal(globalIds: string[]): void {
+    this.setDisplay(globalIds, 'block');
+  }
+
+  private setDisplay(globalIds: string[], display: 'none' | 'block'): void {
+    globalIds.forEach((id) => {
+      const el = document.getElementById(id) as HTMLElement | null;
+      if (el) el.style.display = display;
+    });
+  }
+
+  protected onDestroy(): void {
+    Object.values(this._mounted).forEach((instance) => instance.destroy?.());
+    this._mounted = {};
+  }
+}
+
+/**
+ * Mounts components outside the router's render target (`<main id="app">`),
+ * e.g. a header/footer that should persist across every route. Each entry's
+ * `component` is constructed internally — callers never see or handle
+ * `mountTarget` themselves — and its rendered root element is given the
+ * entry's `id`, so `hideGlobals(ids)`/`revealGlobals(ids)` can target it
+ * later by that same id. Registering an `id` that's already registered logs
+ * a `console.warn` and skips it.
+ */
+export const registerGlobals = (options: RegisterGlobalsOptions): void => {
+  Globals.getInstance().register(options);
+};
+
+/** Hide the elements with the given ids (as registered via `registerGlobals`). */
+export const hideGlobals = (globalIds: string[]): void => {
+  Globals.getInstance().hide(globalIds);
+};
+
+/** Reveal the elements with the given ids (as registered via `registerGlobals`). */
+export const revealGlobals = (globalIds: string[]): void => {
+  Globals.getInstance().reveal(globalIds);
+};

package/templates/base/src/core/services/http-client/helpers/http-builder.helper.test.js.hbs

@@ -75,6 +75,11 @@ describe('HttpBuilder', () => {
     expect(url.search).toBe('?page=1&limit=10');
   });
 
+  it('buildRequestUrl leaves an existing query in the endpoint untouched when no new params are passed', () => {
+    const url = HttpBuilder.buildRequestUrl('https://api.example.com?page=1');
+    expect(url.search).toBe('?page=1');
+  });
+
   // Tests for buildRequestOptions
   it('buildRequestOptions sets GET without body', () => {
     const options = HttpBuilder.buildRequestOptions(
@@ -106,4 +111,24 @@ describe('HttpBuilder', () => {
     expect(options.body).toBeUndefined();
     expect(options.headers).toBeUndefined();
   });
+
+  it('buildRequestOptions sets PUT with body', () => {
+    const data = { id: 1, name: 'Updated' };
+    const options = HttpBuilder.buildRequestOptions('PUT', data, {}, mockAbortSignal);
+    expect(options.method).toBe('PUT');
+    expect(options.body).toBe(JSON.stringify(data));
+  });
+
+  it('buildRequestOptions sets PATCH with body', () => {
+    const data = { name: 'Patched' };
+    const options = HttpBuilder.buildRequestOptions('PATCH', data, {}, mockAbortSignal);
+    expect(options.method).toBe('PATCH');
+    expect(options.body).toBe(JSON.stringify(data));
+  });
+
+  it('buildRequestOptions sets DELETE without body', () => {
+    const options = HttpBuilder.buildRequestOptions('DELETE', undefined, {}, mockAbortSignal);
+    expect(options.method).toBe('DELETE');
+    expect(options.body).toBeUndefined();
+  });
 })

package/templates/base/src/core/services/http-client/helpers/http-manager.helper.test.js.hbs

@@ -55,6 +55,26 @@ describe('HttpManager', () => {
     expect(thrown).toBe(true);
   });
 
+  it('should throw HttpError with a null response body when the error body is not valid JSON', async () => {
+    const mockResponse = new Response('plain text failure', {
+      status: 500,
+      statusText: 'Internal Server Error',
+      headers: { 'Content-Type': 'text/plain' }
+    });
+
+    let thrown = false;
+    try {
+      await HttpManager.validateResponse(mockResponse);
+    } catch (e) {
+      thrown = true;
+      expect(e).toBeInstanceOf(HttpError);
+      expect(e.status).toBe(500);
+      expect(e.statusText).toBe('Internal Server Error');
+      expect(e.response).toBe(null);
+    }
+    expect(thrown).toBe(true);
+  });
+
   it('should detect JSON content types', () => {
     expect(HttpManager.isJsonResponse('application/json')).toBe(true);
     expect(HttpManager.isJsonResponse('application/json; charset=utf-8')).toBe(true);

package/templates/base/src/core/services/http-client/http-client.test.js.hbs

@@ -204,6 +204,49 @@ describe('HttpClient', () => {
     expect(lastCall.options.headers['Authorization']).toBe('Bearer custom-token');
   });
 
+  it('should invoke request interceptors with the final url and options before sending', async () => {
+    fetchMock.mockJsonResponse('https://api.example.com/users', []);
+    const calls = [];
+    httpClient.addRequestInterceptor((url, options) => calls.push({ url, options }));
+
+    await httpClient.get('https://api.example.com/users');
+
+    expect(calls.length).toBe(1);
+    expect(calls[0].url).toBe('https://api.example.com/users');
+    expect(calls[0].options.method).toBe('GET');
+  });
+
+  it('should invoke response interceptors with the raw fetch response', async () => {
+    fetchMock.mockJsonResponse('https://api.example.com/users', []);
+    const received = [];
+    httpClient.addResponseInterceptor((response) => received.push(response));
+
+    await httpClient.get('https://api.example.com/users');
+
+    expect(received.length).toBe(1);
+    expect(received[0].ok).toBe(true);
+  });
+
+  it('should propagate a non-timeout error thrown while parsing the response', async () => {
+    fetchMock.mockResponse('https://api.example.com/broken', {
+      ok: true,
+      status: 200,
+      statusText: 'OK',
+      headers: { get: () => 'application/json' },
+      json: () => Promise.reject(new Error('Malformed JSON')),
+      text: () => Promise.resolve('not json'),
+    });
+
+    let thrown = false;
+    try {
+      await httpClient.get('https://api.example.com/broken');
+    } catch (error) {
+      thrown = true;
+      expect(error.message).toBe('Malformed JSON');
+    }
+    expect(thrown).toBe(true);
+  });
+
   it('should handle HTTP errors', async () => {
     fetchMock.mockError('https://api.example.com/users', 404, { message: 'Not found' });