@nutin/cli 1.3.1 → 2.0.0

package/templates/base/src/core/base-classes/service/service.ts.hbs

@@ -1,15 +1,15 @@
 /**
- * Abstract  class for implementing the Singleton pattern.
+ * Abstract class for implementing the Singleton pattern.
  * Supports constructor parameters for initialization.
  */
 export abstract class Service<T extends Service<T>> {
   private static _instances = new Map<Function, any>();
   private static _instantiating = new Set<Function>();
   private _cleanupCallbacks: (() => void)[] = [];
-  
+
   constructor(...args: any[]) {
     const constructor = this.constructor as new (...args: any[]) => T;
-    
+
     if (!Service._instantiating.has(constructor)) {
       throw new Error(
         `${constructor.name} is a Service. Use ${constructor.name}.getInstance() instead.`
@@ -19,31 +19,39 @@ export abstract class Service<T extends Service<T>> {
     window.addEventListener('beforeunload', this.dispose);
   }
 
-  public static createInstance<T extends Service<T>>(
-    constructor: new (...args: any[]) => T,
+  /**
+   * Returns the singleton instance, creating it with the provided args if it
+   * doesn't exist yet. Throws if args are passed to an already-initialized instance,
+   * preventing silent re-initialization mismatches.
+   */
+  public static getInstance<T extends Service<T>>(
+    this: new (...args: any[]) => T,
     ...args: any[]
   ): T {
-    if (!Service._instances.has(constructor)) {
-      Service._instantiating.add(constructor);
-      Service._instances.set(constructor, new constructor(...args));
-      Service._instantiating.delete(constructor);
+    const alreadyExists = Service._instances.has(this);
+
+    if (alreadyExists && args.length > 0) {
+      throw new Error(
+        `${this.name} is already initialized. ` +
+        `getInstance() was called with arguments on an existing instance, ` +
+        `which would silently ignore them. ` +
+        `Call getInstance() without arguments to retrieve the existing instance.`
+      );
     }
-    return Service._instances.get(constructor);
-  }
 
-  public static getInstance<T extends Service<T>>(this: new () => T): T {
-    if (!Service._instances.has(this)) {
+    if (!alreadyExists) {
       Service._instantiating.add(this);
-      Service._instances.set(this, new this());
+      Service._instances.set(this, new this(...args));
       Service._instantiating.delete(this);
     }
+
     return Service._instances.get(this);
   }
 
   public static hasInstance<T extends Service<T>>(
     constructor: new (...args: any[]) => T
   ): boolean {
-    return Service._instances.has(constructor);  
+    return Service._instances.has(constructor);
   }
 
   public static async destroy<T extends Service<T>>(
@@ -65,7 +73,7 @@ export abstract class Service<T extends Service<T>> {
   public static async destroyAll(): Promise<void> {
     const destroyPromises = Array.from(Service._instances.values())
       .map(instance => instance.onDestroy());
-    
+
     await Promise.all(destroyPromises);
     Service._instances.clear();
     Service._instantiating.clear();
@@ -76,11 +84,9 @@ export abstract class Service<T extends Service<T>> {
   }
 
   /**
-   * For async and custom cleanup operations
+   * For async and custom cleanup operations.
    */
-  protected onDestroy<T extends Service<T>>(this: () => T): void {
-    console.log(`No onDestroy operations.`)
-  }
+  protected onDestroy(): void {}
 
   private autoBindMethods(): void {
     let proto = Object.getPrototypeOf(this);

package/templates/base/src/core/base-classes/view/view.test.js.hbs

@@ -0,0 +1,74 @@
+import { View } from '#root/dist/src/core/index.js';
+
+class HomeView extends View {}
+class MyFancyView extends View {}
+class NamedView extends View {}
+
+describe('View', () => {
+  let app;
+
+  beforeEach(() => {
+    app = document.getElementById('app');
+  });
+
+  afterEach(() => {
+    app.innerHTML = '';
+    app = null;
+  });
+
+  it('derives a kebab-case viewName from the class name, stripping a trailing "View"', () => {
+    const view = new HomeView({});
+    expect(view.viewName).toBe('home');
+  });
+
+  it('derives a kebab-case viewName for a multi-word class name', () => {
+    const view = new MyFancyView({});
+    expect(view.viewName).toBe('my-fancy');
+  });
+
+  it('uses an explicit viewName option instead of deriving one', () => {
+    const view = new NamedView({ viewName: 'custom-name' });
+    expect(view.viewName).toBe('custom-name');
+  });
+
+  it('generateTemplate() returns the constructor template', () => {
+    const view = new HomeView({ template: '<p>hi</p>' });
+    expect(view.render().innerHTML).toBe('<p>hi</p>');
+  });
+
+  it('defaults the template to an empty string', () => {
+    const view = new HomeView({});
+    expect(view.render().innerHTML).toBe('');
+  });
+
+  it('defaults the tagName to "section"', () => {
+    const view = new HomeView({});
+    expect(view.getElement().tagName).toBe('SECTION');
+  });
+
+  it('setRouteParams/getRouteParams/getRouteParam/hasRouteParam manage route params', () => {
+    const view = new HomeView({});
+    expect(view.hasRouteParam('id')).toBe(false);
+    expect(view.getRouteParam('id')).toBeUndefined();
+
+    view.setRouteParams({ id: '42' });
+
+    expect(view.hasRouteParam('id')).toBe(true);
+    expect(view.getRouteParam('id')).toBe('42');
+    expect(view.getRouteParams()).toEqual({ id: '42' });
+  });
+
+  it('getRouteParams() returns a copy, not a live reference', () => {
+    const view = new HomeView({});
+    view.setRouteParams({ id: '1' });
+    const params = view.getRouteParams();
+    params.id = 'mutated';
+    expect(view.getRouteParam('id')).toBe('1');
+  });
+
+  it('onEnter and onExit are present as no-op hooks', () => {
+    const view = new HomeView({});
+    expect(() => view.onEnter()).not.toThrow();
+    expect(() => view.onExit()).not.toThrow();
+  });
+});

package/templates/base/src/core/base-classes/view/view.ts.hbs

@@ -7,71 +7,47 @@ export interface ViewOptions extends BaseComponentOptions {
 export abstract class View<T extends HTMLElement = HTMLElement> extends BaseComponent<T> {
   public viewName: string;
   protected routeParams: Record<string, string> = {};
+  private _template: string;
 
   constructor({
-      template,
-      tagName = 'section',
-      mountTarget = '#app',
-      viewName
-    }: ViewOptions) {
-    super({template, mountTarget, tagName});
+    template,
+    tagName = 'section',
+    mountTarget = '#app',
+    viewName,
+    trustLevel,
+  }: ViewOptions) {
+    super({ mountTarget, tagName, trustLevel });
+    this._template = template ?? '';
     this.viewName = viewName || this.getKebabCaseViewName();
   }
 
-   /**
-   * Set route parameters for this view instance
-   * Called by the router when the view is instantiated
-   */
+  protected override generateTemplate(): string {
+    return this._template;
+  }
+
   public setRouteParams(params: Record<string, string>): void {
     this.routeParams = { ...params };
   }
 
-  /**
-   * Get all route parameters
-   */
   public getRouteParams(): Record<string, string> {
     return { ...this.routeParams };
   }
 
-  /**
-   * Get a specific route parameter
-   */
   public getRouteParam(key: string): string | undefined {
     return this.routeParams[key];
   }
 
-  /**
-   * Check if a route parameter exists and has a value
-   */
   public hasRouteParam(key: string): boolean {
     return key in this.routeParams && this.routeParams[key] !== undefined;
   }
 
-  public shouldUpdateMetaContent(): boolean {
-    return true;
-  }
-  
-  public onEnter(): void {
-    console.log(`${this.viewName} mounted with params:`, this.routeParams);
-  }
-
-  public onExit(): void {
-    console.log(`${this.viewName} unmounted`);
-  }
-
-  public override render(): HTMLElement {
-    this.onEnter();
-    return super.render();
-  }
-
-  public override destroy(): void {
-    super.destroy();
-    this.onExit();
-  }
-
   private getKebabCaseViewName(): string {
     const className = this.constructor.name;
     const baseName = className.replace(/View$/, '');
     return baseName.replace(/([a-z0-9])([A-Z])/g, '$1-$2').toLowerCase();
   }
+
+  // Navigation hooks — called by router only, never by render lifecycle
+  public onEnter(): void {}
+  public onExit(): void {}
 }

package/templates/base/src/core/config.ts.hbs

@@ -0,0 +1,7 @@
+import langs from '../../config/languages.json' with { type: 'json' };
+import nutinConfig from '../../nutin.config.js';
+
+export const CONFIG = {
+  langs,
+  i18n: nutinConfig.i18n,
+} as const;

package/templates/base/src/core/index.ts.hbs

@@ -3,6 +3,3 @@ export * from './base-classes/index.js';
 
 // Core functionalities
 export * from './services/index.js';
-
-// Helper functions
-export * from './utils/index.js';

package/templates/base/src/core/internals.d.ts.hbs

@@ -0,0 +1,27 @@
+declare interface NavigationEventMap {
+  'navigate': { path: string };
+  'reload': {};
+}
+
+declare interface LifecycleEventMap {
+  'before-render': {};
+  'after-render': {};
+  'before-destroy': {};
+  'after-destroy': {};
+  'view-mount': { viewName: string };
+  'view-unmount': { viewName: string };
+}
+
+declare interface I18nEventMap {
+  'language-changed': {
+    lang: string;
+  };
+}
+
+declare interface FrameworkEventMap extends NavigationEventMap, LifecycleEventMap, I18nEventMap {}
+
+declare interface AppEventMap {}
+
+declare interface EventMap extends FrameworkEventMap, AppEventMap {}
+
+declare type EventKey = keyof EventMap;

package/templates/base/src/core/nutin-config.d.ts.hbs

@@ -0,0 +1,4 @@
+declare module '*/nutin.config.js' {
+  const nutinConfig: { i18n: boolean; [key: string]: unknown };
+  export default nutinConfig;
+}

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

@@ -127,11 +127,75 @@ describe('EventBus', () => {
   });
   it('should reset all service instances', () => {
     const eventBus1 = EventBus.getInstance();
-      
+
     EventBus.testingResetAll();
-      
+
     const eventBus2 = EventBus.getInstance();
-      
+
     expect(eventBus1).not.toBe(eventBus2);
   });
+
+  it('should only invoke a once() handler on the first emit', () => {
+    let callCount = 0;
+    eventBus.once('user-login', () => { callCount++; });
+
+    eventBus.emit('user-login', { userId: '1' });
+    expect(callCount).toBe(1);
+
+    eventBus.emit('user-login', { userId: '2' });
+    expect(callCount).toBe(1);
+  });
+
+  it('should auto-unsubscribe a once() handler from _subscriptions after it fires', () => {
+    eventBus.once('user-login', () => {});
+    expect(eventBus._subscriptions.length).toBe(1);
+
+    eventBus.emit('user-login', {});
+    expect(eventBus._subscriptions.length).toBe(0);
+  });
+
+  it('should not remove a once() subscription before it has fired', () => {
+    eventBus.once('user-login', () => {});
+    eventBus.emit('notification', {});
+    expect(eventBus._subscriptions.length).toBe(1);
+  });
+
+  it('should let a once() handler and a regular subscriber on the same event coexist', () => {
+    let onceCalls = 0;
+    let regularCalls = 0;
+    eventBus.once('notification', () => { onceCalls++; });
+    eventBus.subscribe('notification', () => { regularCalls++; });
+
+    eventBus.emit('notification', {});
+    expect(onceCalls).toBe(1);
+    expect(regularCalls).toBe(1);
+
+    eventBus.emit('notification', {});
+    expect(onceCalls).toBe(1);
+    expect(regularCalls).toBe(2);
+  });
+
+  it('off(event) with no callback removes every handler for that event', () => {
+    let callsA = 0;
+    let callsB = 0;
+    eventBus.subscribe('notification', () => { callsA++; });
+    eventBus.subscribe('notification', () => { callsB++; });
+
+    eventBus.off('notification');
+    eventBus.emit('notification', {});
+
+    expect(callsA).toBe(0);
+    expect(callsB).toBe(0);
+    expect(eventBus.handlers['notification']).toBeUndefined();
+  });
+
+  it('off(event) with no callback does not affect other events', () => {
+    let called = false;
+    eventBus.subscribe('user-login', () => { called = true; });
+
+    eventBus.off('notification');
+    eventBus.emit('user-login', {});
+
+    expect(called).toBe(true);
+  });
 });

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

@@ -2,7 +2,7 @@ import { Service } from "../../index.js";
 
 export type IEventBus = InstanceType<typeof EventBus>;
 
-type Subscription<K extends EventKey = EventKey> = {
+export type Subscription<K extends EventKey = EventKey> = {
   event: K;
   callback: (data: EventMap[K]) => void;
   once?: boolean;
@@ -58,7 +58,10 @@ export class EventBus extends Service<EventBus> {
     if (!handlers) return;
 
     if (callback) {
-      this.handlers[event] = handlers.filter(h => h !== callback);
+      (this.handlers as Record<
+        EventKey,
+        Array<(data: EventMap[K]) => void>
+      >)[event] = handlers.filter(h => h !== callback);
     } else {
       delete this.handlers[event];
     }
@@ -76,8 +79,10 @@ export class EventBus extends Service<EventBus> {
     if (!this.handlers[event]) {
       this.handlers[event] = [];
     }
-    this.handlers[event]!.push(callback);
-    this._subscriptions.push({ event, callback, once });
+    (
+      this.handlers as Record<EventKey, Array<(data: EventMap[K]) => void>>
+    )[event].push(callback);
+    this._subscriptions.push({ event, callback, once } as Subscription);
   }
 
   private cleanupEventListeners = (): void => {

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

@@ -0,0 +1,3 @@
+export * from './event-bus.js';
+export * from './lifecycle.facade.js';
+export * from './navigation.facade.js';

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);