sygnal 5.3.7 → 5.4.0

package/src/switchable.ts

@@ -1,14 +1,16 @@
-import xs, {Stream, resolveInteropDefault} from './extra/xstreamCompat';
-import * as dropRepeatsModule from 'xstream/extra/dropRepeats.js';
+import xs, {Stream} from './extra/xstreamCompat';
+import {dropRepeats} from './extra/xstreamExtras';
 import {h} from './cycle/dom/index';
+import {fail} from './extra/diagnostics/legacy';
 
-const dropRepeats = resolveInteropDefault(dropRepeatsModule);
 
 interface SwitchableOptions {
   switched?: string | string[];
   stateSourceName?: string;
 }
 
+const NAME_FIX = 'Pass a stream, a state key string, or a state => name function';
+
 export default function switchable(
   factories: Record<string, (sources: any) => any>,
   name$: any,
@@ -18,7 +20,7 @@ export default function switchable(
   const {switched = ['DOM'], stateSourceName = 'STATE'} = opts;
   const nameType = typeof name$;
 
-  if (!name$) throw new Error(`Missing 'name$' parameter for switchable()`);
+  if (!name$) fail('SYG419', 'switchable', "Missing 'name$' parameter", NAME_FIX);
   if (
     !(
       nameType === 'string' ||
@@ -26,9 +28,7 @@ export default function switchable(
       name$ instanceof Stream
     )
   ) {
-    throw new Error(
-      `Invalid 'name$' parameter for switchable(): expects Stream, String, or Function`
-    );
+    fail('SYG419', 'switchable', `Invalid 'name$' parameter: got ${nameType}`, NAME_FIX);
   }
 
   if (name$ instanceof Stream) {
@@ -51,7 +51,7 @@ export default function switchable(
           sources.state
         ).stream;
       if (!(state$ instanceof Stream))
-        throw new Error(`Could not find the state source: ${stateSourceName}`);
+        fail('SYG607', 'switchable', `State source '${stateSourceName}' not found`, 'Pass the state source in sources, or set stateSourceName');
       const _name$ = state$
         .map(mapFunction)
         .filter((name: any) => typeof name === 'string')
@@ -113,6 +113,8 @@ function _switchable(
     },
     {}
   );
+  // B-024: every factory was instantiated above; dispose them all with the switchable
+  switchedSinks.__dispose = () => sinks.forEach(([, s]) => s.__dispose?.());
 
   return switchedSinks;
 }

package/src/vike/types.ts

@@ -1,8 +1,11 @@
 /**
- * TypeScript declarations for vike-sygnal custom config settings.
+ * TypeScript declarations for 'sygnal/config' (also 'sygnal/vike' and
+ * 'sygnal/vike/config'): the Vike extension config (default export), and the
+ * custom config settings, which augment Vike's Config interface so users get
+ * autocomplete and type checking in their +config.ts files.
  *
- * These augment Vike's Config interface so users get autocomplete
- * and type checking in their +config.ts files.
+ *   import vikeSygnal from 'sygnal/config'
+ *   export default { extends: [vikeSygnal] }
  */
 
 declare global {
@@ -30,4 +33,18 @@ declare global {
   }
 }
 
-export {}
+/**
+ * The Sygnal extension for Vike: put it in `extends` of your root +config.
+ * (Declared here; the value is the package's vike/+config entry.)
+ */
+declare const vikeSygnal: {
+  name: 'sygnal'
+  clientRouting: boolean
+  hydrationCanBeAborted: boolean
+  onRenderHtml: string
+  onRenderClient: string
+  passToClient: string[]
+  meta: Record<string, any>
+}
+
+export default vikeSygnal

package/src/vite/plugin.d.ts

@@ -1,3 +1,56 @@
+export type DiagnosticsMode = 'off' | 'collect' | 'warn' | 'error'
+
+export interface DiagnosticsPluginOptions {
+  /**
+   * Runtime diagnostics mode in dev.
+   * @default 'warn'
+   */
+  mode?: DiagnosticsMode
+  /**
+   * Strict (canonical-form, SYG5xx) runtime checks: the dev snippet sets
+   * `globalThis.__SYGNAL_STRICT__ = true`. Also the default for `check.strict`.
+   * @default false
+   */
+  strict?: boolean
+  /** Diagnostic codes to drop, e.g. ['SYG105'] (runtime and static) */
+  ignore?: string[]
+}
+
+export interface CheckPluginOptions {
+  /**
+   * Also run sygnal-check's strict (SYG5xx) rules.
+   * @default the `diagnostics` strict setting
+   */
+  strict?: boolean
+  /**
+   * Files, directories or globs to check, relative to the Vite root.
+   * By default the existing ones of src/, pages/ and renderer/ (Vike apps),
+   * else the project root (node_modules, dist and other build output are
+   * skipped); a one-time notice is logged when the default finds no
+   * directory or when none of the given paths exists.
+   * @default ['src', 'pages', 'renderer'] (those that exist), else ['.']
+   */
+  include?: string[]
+  /**
+   * Codes to drop.
+   * @default the `diagnostics` ignore list
+   */
+  ignore?: string[]
+  /**
+   * Error-severity findings also open Vite's error overlay ('error');
+   * false: never. Every finding is printed in the terminal and logged in the
+   * browser console (sygnal-check's codes are currently all warnings or
+   * info, so in practice that is where they go). Warnings never use the
+   * overlay, because Vite's client reloads the page on the next HMR update
+   * while an overlay is open: 'warn' is still accepted, and treated as
+   * 'error' with a one-time notice. The overlay is sent only to the page that
+   * loads (not to every client), closed before each HMR update and sent
+   * again after the re-check.
+   * @default 'error'
+   */
+  overlay?: 'error' | 'warn' | false
+}
+
 export interface SygnalPluginOptions {
   /**
    * Disable automatic JSX configuration.
@@ -10,21 +63,61 @@ export interface SygnalPluginOptions {
    * @default false
    */
   disableHmr?: boolean
+
+  /**
+   * Runtime diagnostics in dev (`vite`, never `vite build`). In every file
+   * that imports `run` from 'sygnal' the plugin sets the dev flag and imports
+   * 'sygnal/diagnostics' (the runtime checks); the Vike and Astro client
+   * entries get the same. 'off' injects nothing. Any other mode than 'warn',
+   * or an ignore list, is passed as run()'s `diagnostics` option, unless the
+   * run() call sets that option itself.
+   * @default 'warn'
+   */
+  diagnostics?: DiagnosticsMode | DiagnosticsPluginOptions
+
+  /**
+   * Run sygnal-check (an optional dependency) in dev on startup and after
+   * every source change. Findings go to the terminal and the browser console;
+   * error-severity findings also to Vite's error overlay.
+   * Skipped silently when sygnal-check isn't installed.
+   * @default true
+   */
+  check?: boolean | CheckPluginOptions
+
+  /**
+   * Under Vitest, add the 'sygnal/diagnostics' entry to `test.setupFiles`
+   * so tests (e.g. renderComponent) get the runtime checks.
+   * @default true
+   */
+  vitestSetup?: boolean
 }
 
 /**
  * Sygnal Vite plugin.
  *
- * Auto-configures JSX transform and injects HMR boilerplate.
+ * Auto-configures the JSX transform and injects HMR boilerplate. In dev
+ * (`vite`) it also turns on runtime diagnostics with the dev checks and runs
+ * sygnal-check when installed; under Vitest it adds the dev checks to the
+ * test setup. Nothing is added to production builds.
  *
  * @example
  * ```js
  * import sygnal from 'sygnal/vite'
  * export default defineConfig({ plugins: [sygnal()] })
+ *
+ * // stricter dev setup
+ * sygnal({ diagnostics: { mode: 'error', strict: true }, check: { strict: true } })
  * ```
  */
 export default function sygnal(options?: SygnalPluginOptions): {
   name: string
   config: (config: any, env: { command: string }) => any
-  transform: (code: string, id: string) => { code: string; map: null } | null
+  configResolved: (config: any) => void
+  resolveId: {
+    order: 'pre'
+    handler: (source: string, importer: string | undefined, options?: any) => Promise<any>
+  }
+  load: (id: string) => string | null
+  configureServer: (server: any) => void
+  transform: (code: string, id: string, options?: { ssr?: boolean }) => { code: string; map: any } | null
 }