@poveste/shared 0.3.3 → 0.5.0

package/README.md

@@ -0,0 +1,9 @@
+# @poveste/shared
+
+Shared utilities used across the Poveste packages.
+
+Internal to [Poveste](https://github.com/poveste-dev/poveste): it is installed as a
+dependency of `poveste` and there is nothing to install or configure directly. Install
+[`poveste`](https://www.npmjs.com/package/poveste) instead.
+
+[Documentation](https://poveste.dev)

package/dist/setup.d.ts

@@ -9,5 +9,5 @@ export type SetupModule = Record<string, unknown> | undefined;
  * consumer build. Passing the namespace through a call forces it to be
  * materialized, so the lookup happens at runtime where it belongs.
  */
-export declare function getSetupHook<T>(mod: SetupModule, name: string): T | undefined;
+export declare function getSetupHook<T>(mod: SetupModule, name: string | string[]): T | undefined;
 //# sourceMappingURL=setup.d.ts.map

package/dist/setup.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"setup.d.ts","sourceRoot":"","sources":["../src/setup.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAA;AAE7D;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,GAAG,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS,CAG7E"}
+{"version":3,"file":"setup.d.ts","sourceRoot":"","sources":["../src/setup.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAA;AAE7D;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,GAAG,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,CAgBxF"}

package/dist/setup.js

@@ -9,6 +9,15 @@
  * materialized, so the lookup happens at runtime where it belongs.
  */
 export function getSetupHook(mod, name) {
-    const hook = mod?.[name];
-    return typeof hook === 'function' ? hook : undefined;
+    const names = typeof name === 'string' ? [name] : name;
+    const present = names.filter(candidate => typeof mod?.[candidate] === 'function');
+    // Earlier names win, so a plugin lists its established hook first and a newer
+    // alias after it: an existing setup file keeps the exact behaviour it had.
+    // Running both instead would apply the same setup twice, which for Vue means
+    // a second `app.use()` for every plugin the user registers.
+    if (present.length > 1) {
+        console.warn(`[poveste] Setup file exports ${present.length} interchangeable setup hooks (${present.join(', ')}). `
+            + `Only ${present[0]} runs. Keep one — they are aliases, not separate hooks.`);
+    }
+    return present.length > 0 ? mod[present[0]] : undefined;
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@poveste/shared",
   "type": "module",
-  "version": "0.3.3",
+  "version": "0.5.0",
   "description": "Shared utilities for Poveste",
   "author": {
     "name": "Sorin Gitlan"
@@ -34,7 +34,7 @@
     "pathe": "^1.1.2",
     "picocolors": "^1.1.1",
     "unhead": "^3.1.0",
-    "@poveste/vendors": "^0.3.3"
+    "@poveste/vendors": "^0.5.0"
   },
   "devDependencies": {
     "typescript": "5.6.3",

package/src/__tests__/setup.spec.ts

@@ -0,0 +1,60 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { getSetupHook } from '../setup.js'
+
+afterEach(() => {
+  vi.restoreAllMocks()
+})
+
+describe('getSetupHook', () => {
+  it('reads a hook by a single name', () => {
+    const hook = () => {}
+    expect(getSetupHook({ setupVanilla: hook }, 'setupVanilla')).toBe(hook)
+  })
+
+  it('ignores a non-function export of the right name', () => {
+    expect(getSetupHook({ setupVanilla: 'not a function' }, 'setupVanilla')).toBeUndefined()
+    expect(getSetupHook({ setupVanilla: undefined }, 'setupVanilla')).toBeUndefined()
+  })
+
+  it('tolerates a missing module', () => {
+    expect(getSetupHook(undefined, 'setupVanilla')).toBeUndefined()
+  })
+
+  it.each([
+    ['the established name', 'setupVue3'],
+    ['the unnumbered alias', 'setupVue'],
+  ])('finds a hook exported under %s', (_label, name) => {
+    const hook = () => {}
+    expect(getSetupHook({ [name]: hook }, ['setupVue3', 'setupVue'])).toBe(hook)
+  })
+
+  it('returns undefined when none of the names are exported', () => {
+    expect(getSetupHook({ setupSvelte5: () => {} }, ['setupVue3', 'setupVue'])).toBeUndefined()
+  })
+
+  describe('when a setup file exports more than one alias', () => {
+    // The whole point of the alias is that existing files keep working, so the
+    // established name has to win regardless of the order they are declared in.
+    it('runs the earlier name in the list, not the first declared', () => {
+      const legacy = () => {}
+      const renamed = () => {}
+      expect(getSetupHook({ setupVue: renamed, setupVue3: legacy }, ['setupVue3', 'setupVue'])).toBe(legacy)
+    })
+
+    it('warns, naming which one actually runs', () => {
+      const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
+      getSetupHook({ setupVue3: () => {}, setupVue: () => {} }, ['setupVue3', 'setupVue'])
+
+      expect(warn).toHaveBeenCalledOnce()
+      const message = warn.mock.calls[0][0] as string
+      expect(message).toContain('setupVue3, setupVue')
+      expect(message).toContain('Only setupVue3 runs')
+    })
+
+    it('stays quiet when only one is exported', () => {
+      const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
+      getSetupHook({ setupVue: () => {} }, ['setupVue3', 'setupVue'])
+      expect(warn).not.toHaveBeenCalled()
+    })
+  })
+})

package/src/setup.ts

@@ -10,7 +10,20 @@ export type SetupModule = Record<string, unknown> | undefined
  * consumer build. Passing the namespace through a call forces it to be
  * materialized, so the lookup happens at runtime where it belongs.
  */
-export function getSetupHook<T>(mod: SetupModule, name: string): T | undefined {
-  const hook = mod?.[name]
-  return typeof hook === 'function' ? hook as T : undefined
+export function getSetupHook<T>(mod: SetupModule, name: string | string[]): T | undefined {
+  const names = typeof name === 'string' ? [name] : name
+  const present = names.filter(candidate => typeof mod?.[candidate] === 'function')
+
+  // Earlier names win, so a plugin lists its established hook first and a newer
+  // alias after it: an existing setup file keeps the exact behaviour it had.
+  // Running both instead would apply the same setup twice, which for Vue means
+  // a second `app.use()` for every plugin the user registers.
+  if (present.length > 1) {
+    console.warn(
+      `[poveste] Setup file exports ${present.length} interchangeable setup hooks (${present.join(', ')}). `
+      + `Only ${present[0]} runs. Keep one — they are aliases, not separate hooks.`,
+    )
+  }
+
+  return present.length > 0 ? mod![present[0]] as T : undefined
 }