@invisibleloop/pulse 0.1.21

package/src/spec/schema.test.js

@@ -0,0 +1,291 @@
+/**
+ * Spec schema tests — run with: node src/spec/schema.test.js
+ */
+import { validateSpec, getStreamOrder, getViewSegments } from './schema.js'
+
+let passed = 0
+let failed = 0
+
+function test(label, fn) {
+  try {
+    fn()
+    console.log(`  ✓ ${label}`)
+    passed++
+  } catch (e) {
+    console.log(`  ✗ ${label}`)
+    console.log(`    ${e.message}`)
+    failed++
+  }
+}
+
+function assert(condition, msg) {
+  if (!condition) throw new Error(msg || 'Assertion failed')
+}
+
+function assertErrors(spec, ...expectedFragments) {
+  const { valid, errors } = validateSpec(spec)
+  assert(!valid, 'Expected spec to be invalid but it passed')
+  for (const fragment of expectedFragments) {
+    const found = errors.some(e => e.includes(fragment))
+    assert(found, `Expected error containing "${fragment}" but got:\n    ${errors.join('\n    ')}`)
+  }
+}
+
+function assertValid(spec) {
+  const { valid, errors } = validateSpec(spec)
+  assert(valid, `Expected spec to be valid but got errors:\n  ${errors.join('\n  ')}`)
+}
+
+// ---------------------------------------------------------------------------
+
+console.log('\nSpec validation\n')
+
+test('rejects non-object', () => {
+  assertErrors(null, 'must be a plain object')
+  assertErrors('string', 'must be a plain object')
+})
+
+test('route is optional (derived server-side by convention)', () => {
+  const { valid } = validateSpec({ state: {}, view: () => '' })
+  assert(valid, 'spec without route should be valid for client-side use')
+})
+
+test('rejects route that does not start with /', () => {
+  assertErrors({ route: 'contact', state: {}, view: () => '' }, 'must start with "/"')
+})
+
+test('requires state', () => {
+  assertErrors({ route: '/contact', view: () => '' }, 'spec.state is required')
+})
+
+test('requires view', () => {
+  assertErrors({ route: '/contact', state: {} }, 'spec.view is required')
+})
+
+test('accepts function view', () => {
+  assertValid({ route: '/contact', state: {}, view: () => '<div/>' })
+})
+
+test('accepts segmented view', () => {
+  assertValid({
+    route: '/contact',
+    state: {},
+    view: {
+      header: () => '<header/>',
+      form:   () => '<form/>'
+    }
+  })
+})
+
+test('rejects view segment that is not a function', () => {
+  assertErrors(
+    { route: '/contact', state: {}, view: { header: '<header/>' } },
+    'spec.view.header must be a function'
+  )
+})
+
+test('rejects stream referencing undefined segment', () => {
+  assertErrors(
+    {
+      route: '/contact',
+      state: {},
+      view:  { header: () => '' },
+      stream: { shell: ['header', 'missing'] }
+    },
+    'spec.stream references "missing"'
+  )
+})
+
+test('rejects stream.shell that is not an array', () => {
+  assertErrors(
+    { route: '/contact', state: {}, view: () => '', stream: { shell: 'header' } },
+    'spec.stream.shell must be an array'
+  )
+})
+
+test('rejects mutations with non-function values', () => {
+  assertErrors(
+    { route: '/x', state: {}, view: () => '', mutations: { inc: 'not a function' } },
+    'spec.mutations.inc must be a function'
+  )
+})
+
+test('rejects action missing run', () => {
+  assertErrors(
+    {
+      route: '/x', state: {}, view: () => '',
+      actions: { send: { onSuccess: () => {}, onError: () => {} } }
+    },
+    'spec.actions.send.run must be'
+  )
+})
+
+test('rejects action missing onSuccess', () => {
+  assertErrors(
+    {
+      route: '/x', state: {}, view: () => '',
+      actions: { send: { run: async () => {}, onError: () => {} } }
+    },
+    'spec.actions.send.onSuccess must be'
+  )
+})
+
+test('rejects unknown validation rule', () => {
+  assertErrors(
+    {
+      route: '/x', state: {}, view: () => '',
+      validation: { 'fields.email': { required: true, unknown: true } }
+    },
+    'unknown is not a recognised rule'
+  )
+})
+
+test('accepts full valid spec', () => {
+  assertValid({
+    route: '/contact',
+    stream: {
+      shell:    ['header', 'form'],
+      deferred: ['recent']
+    },
+    server: {
+      recent: async () => []
+    },
+    state: {
+      fields: { name: '', email: '', message: '' },
+      status: 'idle'
+    },
+    validation: {
+      'fields.name':    { required: true, minLength: 2 },
+      'fields.email':   { required: true, format: 'email' },
+      'fields.message': { required: true, minLength: 10, maxLength: 1000 }
+    },
+    view: {
+      header: () => '<header/>',
+      form:   (state) => `<form>${state.status}</form>`,
+      recent: (state, server) => `<aside>${server.recent.length}</aside>`
+    },
+    mutations: {
+      updateField: (state, e) => ({ fields: { ...state.fields, [e.target.name]: e.target.value } })
+    },
+    actions: {
+      sendMessage: {
+        validate:  true,
+        run:       async (state) => {},
+        onSuccess: () => ({ status: 'success' }),
+        onError:   () => ({ status: 'error' })
+      }
+    },
+    meta: { title: 'Contact Us' }
+  })
+})
+
+// ---------------------------------------------------------------------------
+
+console.log('\nRaw content specs (contentType)\n')
+
+test('accepts a valid raw content spec', () => {
+  assertValid({
+    route:       '/feed.xml',
+    contentType: 'application/rss+xml; charset=utf-8',
+    render:      (ctx, server) => `<rss/>`
+  })
+})
+
+test('raw spec does not require state or view', () => {
+  const { valid } = validateSpec({
+    route:       '/sitemap.xml',
+    contentType: 'application/xml',
+    render:      () => `<?xml?>`
+  })
+  assert(valid, 'raw spec without state/view should be valid')
+})
+
+test('raw spec accepts server data', () => {
+  assertValid({
+    route:       '/feed.json',
+    contentType: 'application/json',
+    server:      { posts: async () => [] },
+    render:      (ctx, server) => JSON.stringify(server.posts)
+  })
+})
+
+test('rejects raw spec missing render', () => {
+  assertErrors(
+    { route: '/feed.xml', contentType: 'application/rss+xml' },
+    'spec.render is required'
+  )
+})
+
+test('rejects raw spec with empty contentType', () => {
+  assertErrors(
+    { route: '/feed.xml', contentType: '', render: () => '' },
+    'spec.contentType must be a non-empty string'
+  )
+})
+
+// ---------------------------------------------------------------------------
+
+console.log('\ngetViewSegments\n')
+
+test('function view returns ["default"]', () => {
+  const segments = getViewSegments({ view: () => '' })
+  assert(segments.length === 1 && segments[0] === 'default', `Got ${segments}`)
+})
+
+test('segmented view returns keys', () => {
+  const segments = getViewSegments({ view: { header: () => '', form: () => '' } })
+  assert(segments.includes('header') && segments.includes('form'), `Got ${segments}`)
+})
+
+// ---------------------------------------------------------------------------
+
+console.log('\ngetStreamOrder\n')
+
+test('no stream config — all segments in shell', () => {
+  const order = getStreamOrder({ view: { header: () => '', form: () => '' } })
+  assert(order.shell.includes('header'), 'header should be in shell')
+  assert(order.deferred.length === 0, 'deferred should be empty')
+})
+
+test('stream config is respected', () => {
+  const order = getStreamOrder({
+    view:   { header: () => '', form: () => '', recent: () => '' },
+    stream: { shell: ['header', 'form'], deferred: ['recent'] }
+  })
+  assert(order.shell.includes('header'), 'header in shell')
+  assert(order.shell.includes('form'), 'form in shell')
+  assert(order.deferred.includes('recent'), 'recent in deferred')
+})
+
+// ---------------------------------------------------------------------------
+// guard
+// ---------------------------------------------------------------------------
+
+test('accepts a valid guard function', () => {
+  const { valid, errors } = validateSpec({
+    route: '/admin',
+    state: {},
+    view:  () => '<main id="main-content">Admin</main>',
+    guard: async (ctx) => { if (!ctx.cookies.session) return { redirect: '/login' } },
+  })
+  assert(valid, `Expected valid spec, got errors: ${errors.join(', ')}`)
+})
+
+test('rejects guard that is not a function', () => {
+  assertErrors(
+    { route: '/admin', state: {}, view: () => '', guard: '/login' },
+    'spec.guard must be a function'
+  )
+})
+
+test('rejects guard that is an object', () => {
+  assertErrors(
+    { route: '/admin', state: {}, view: () => '', guard: { redirect: '/login' } },
+    'spec.guard must be a function'
+  )
+})
+
+// ---------------------------------------------------------------------------
+
+console.log(`\n${passed + failed} tests: ${passed} passed, ${failed} failed\n`)
+if (failed > 0) process.exit(1)

package/src/store/index.js

@@ -0,0 +1,102 @@
+/**
+ * Pulse — Global Store
+ *
+ * The store is a single shared data layer declared in pulse.store.js.
+ * Its server fetchers run once per request and the results are available to
+ * any page that declares which keys it uses via spec.store.
+ *
+ * Store mutations (store.mutations) allow synchronous client-side updates that
+ * broadcast to all subscribed pages without a server round-trip.
+ */
+
+/**
+ * Validate a store definition.
+ * Returns { valid: true } or { valid: false, errors: string[] }
+ *
+ * @param {unknown} store
+ * @returns {{ valid: boolean, errors: string[] }}
+ */
+export function validateStore(store) {
+  const errors = []
+
+  if (!store || typeof store !== 'object' || Array.isArray(store)) {
+    return { valid: false, errors: ['Store must be a plain object'] }
+  }
+
+  if (store.state !== undefined) {
+    if (typeof store.state !== 'object' || Array.isArray(store.state)) {
+      errors.push('store.state must be a plain object')
+    }
+  }
+
+  if (store.server !== undefined) {
+    if (typeof store.server !== 'object' || Array.isArray(store.server)) {
+      errors.push('store.server must be a plain object of async functions')
+    } else {
+      for (const [key, fn] of Object.entries(store.server)) {
+        if (typeof fn !== 'function') {
+          errors.push(`store.server.${key} must be a function`)
+        }
+      }
+    }
+  }
+
+  if (store.hydrate !== undefined) {
+    if (typeof store.hydrate !== 'string' || !store.hydrate.startsWith('/')) {
+      errors.push('store.hydrate must be a string starting with "/"')
+    }
+  }
+
+  if (store.mutations !== undefined) {
+    if (typeof store.mutations !== 'object' || Array.isArray(store.mutations)) {
+      errors.push('store.mutations must be a plain object of functions')
+    } else {
+      for (const [key, fn] of Object.entries(store.mutations)) {
+        if (typeof fn !== 'function') {
+          errors.push(`store.mutations.${key} must be a function`)
+        }
+      }
+    }
+  }
+
+  return { valid: errors.length === 0, errors }
+}
+
+/**
+ * Resolve all store server fetchers in parallel.
+ * Falls back to store.state values for keys not covered by server fetchers.
+ *
+ * @param {Object} store  - The store definition
+ * @param {Object} ctx    - The request context (params, query, cookies, etc.)
+ * @returns {Promise<Object>}
+ */
+export async function resolveStoreState(store, ctx) {
+  const base = store.state ? { ...store.state } : {}
+
+  if (!store.server) return base
+
+  const timeout = ctx.fetcherTimeout ?? null
+
+  const entries = await Promise.all(
+    Object.entries(store.server).map(async ([key, fn]) => {
+      const value = timeout
+        ? await withTimeout(fn(ctx), timeout, `store.${key}`)
+        : await fn(ctx)
+      return [key, value]
+    })
+  )
+
+  return { ...base, ...Object.fromEntries(entries) }
+}
+
+function withTimeout(promise, ms, name) {
+  return Promise.race([
+    promise,
+    new Promise((_, reject) =>
+      setTimeout(
+        () => reject(new Error(`Store fetcher "${name}" timed out after ${ms}ms`)),
+        ms
+      )
+    )
+  ])
+}

package/src/store/store.test.js

@@ -0,0 +1,210 @@
+/**
+ * Pulse — Store tests
+ * run: node src/store/store.test.js
+ */
+
+import { validateStore, resolveStoreState } from './index.js'
+
+let passed = 0
+let failed = 0
+
+async function test(label, fn) {
+  try {
+    await fn()
+    console.log(`  ✓ ${label}`)
+    passed++
+  } catch (e) {
+    console.log(`  ✗ ${label}`)
+    console.log(`    ${e.message}`)
+    failed++
+  }
+}
+
+function assert(condition, msg) {
+  if (!condition) throw new Error(msg || 'Assertion failed')
+}
+
+function assertEqual(a, b, msg) {
+  if (a !== b) throw new Error(msg || `Expected ${JSON.stringify(a)} === ${JSON.stringify(b)}`)
+}
+
+// ---------------------------------------------------------------------------
+
+console.log('\nvalidateStore\n')
+
+await test('accepts a valid store with state and server', () => {
+  const { valid } = validateStore({
+    state:  { user: null },
+    server: { user: async () => null },
+  })
+  assert(valid, 'Expected valid store')
+})
+
+await test('accepts a store with only state', () => {
+  const { valid } = validateStore({ state: { theme: 'dark' } })
+  assert(valid)
+})
+
+await test('accepts a store with only server', () => {
+  const { valid } = validateStore({ server: { user: async () => null } })
+  assert(valid)
+})
+
+await test('accepts a store with mutations', () => {
+  const { valid } = validateStore({
+    state:     { count: 0 },
+    mutations: { increment: (s) => ({ count: s.count + 1 }) },
+  })
+  assert(valid)
+})
+
+await test('accepts a store with hydrate', () => {
+  const { valid } = validateStore({ state: {}, hydrate: '/pulse.store.js' })
+  assert(valid)
+})
+
+await test('rejects null', () => {
+  const { valid, errors } = validateStore(null)
+  assert(!valid)
+  assert(errors.length > 0)
+})
+
+await test('rejects a non-object', () => {
+  const { valid } = validateStore('not an object')
+  assert(!valid)
+})
+
+await test('rejects an array', () => {
+  const { valid } = validateStore([])
+  assert(!valid)
+})
+
+await test('rejects state that is an array', () => {
+  const { valid, errors } = validateStore({ state: [] })
+  assert(!valid)
+  assert(errors.some(e => e.includes('state')), `Expected state error in: ${errors}`)
+})
+
+await test('rejects state that is a string', () => {
+  const { valid } = validateStore({ state: 'bad' })
+  assert(!valid)
+})
+
+await test('rejects server that is an array', () => {
+  const { valid, errors } = validateStore({ server: ['fn'] })
+  assert(!valid)
+  assert(errors.some(e => e.includes('server')), `Expected server error in: ${errors}`)
+})
+
+await test('rejects a server entry that is not a function', () => {
+  const { valid, errors } = validateStore({ server: { user: 42 } })
+  assert(!valid)
+  assert(errors.some(e => e.includes('store.server.user')), `Expected named error in: ${errors}`)
+})
+
+await test('rejects mutations that is an array', () => {
+  const { valid, errors } = validateStore({ mutations: [() => {}] })
+  assert(!valid)
+  assert(errors.some(e => e.includes('mutations')), `Expected mutations error in: ${errors}`)
+})
+
+await test('rejects a mutation entry that is not a function', () => {
+  const { valid, errors } = validateStore({ mutations: { toggle: 'bad' } })
+  assert(!valid)
+  assert(errors.some(e => e.includes('store.mutations.toggle')), `Expected named error in: ${errors}`)
+})
+
+await test('rejects hydrate that does not start with /', () => {
+  const { valid, errors } = validateStore({ hydrate: 'pulse.store.js' })
+  assert(!valid)
+  assert(errors.some(e => e.includes('hydrate')), `Expected hydrate error in: ${errors}`)
+})
+
+await test('rejects hydrate that is not a string', () => {
+  const { valid } = validateStore({ hydrate: 42 })
+  assert(!valid)
+})
+
+await test('returns all errors for multiple violations', () => {
+  const { valid, errors } = validateStore({ state: [], server: { x: 'not-a-fn' } })
+  assert(!valid)
+  assert(errors.length >= 2, `Expected >= 2 errors, got ${errors.length}: ${errors.join(', ')}`)
+})
+
+// ---------------------------------------------------------------------------
+
+console.log('\nresolveStoreState\n')
+
+await test('returns state defaults when no server fetchers', async () => {
+  const result = await resolveStoreState({ state: { user: null, theme: 'dark' } }, {})
+  assertEqual(result.theme, 'dark')
+  assert(result.user === null)
+})
+
+await test('resolves server fetchers and returns their results', async () => {
+  const result = await resolveStoreState({
+    state:  { user: null, settings: {} },
+    server: {
+      user:     async () => ({ id: 1, name: 'Alice' }),
+      settings: async () => ({ theme: 'light' }),
+    },
+  }, {})
+  assertEqual(result.user.name, 'Alice')
+  assertEqual(result.settings.theme, 'light')
+})
+
+await test('server values override state defaults', async () => {
+  const result = await resolveStoreState({
+    state:  { user: 'default' },
+    server: { user: async () => 'from-server' },
+  }, {})
+  assertEqual(result.user, 'from-server')
+})
+
+await test('state defaults are preserved for keys not covered by server', async () => {
+  const result = await resolveStoreState({
+    state:  { user: null, nav: [1, 2, 3] },
+    server: { user: async () => ({ id: 1 }) },
+  }, {})
+  assertEqual(result.nav.length, 3)
+})
+
+await test('passes ctx to server fetchers', async () => {
+  let received
+  await resolveStoreState({
+    server: { data: async (ctx) => { received = ctx; return null } },
+  }, { cookies: { session: 'abc' } })
+  assertEqual(received.cookies.session, 'abc')
+})
+
+await test('returns empty object when store has no state and no server', async () => {
+  const result = await resolveStoreState({}, {})
+  assert(typeof result === 'object' && result !== null)
+  assertEqual(Object.keys(result).length, 0)
+})
+
+await test('timeout rejects if a fetcher exceeds fetcherTimeout', async () => {
+  let threw = false
+  try {
+    await resolveStoreState({
+      server: { slow: async () => new Promise(r => setTimeout(r, 200)) },
+    }, { fetcherTimeout: 20 })
+  } catch (e) {
+    threw = true
+    assert(e.message.includes('slow'), `Expected fetcher name in error: ${e.message}`)
+    assert(e.message.toLowerCase().includes('timed out'), `Expected timeout message: ${e.message}`)
+  }
+  assert(threw, 'Expected timeout to throw')
+})
+
+await test('no timeout when fetcherTimeout is not set', async () => {
+  const result = await resolveStoreState({
+    server: { fast: async () => 'ok' },
+  }, {})
+  assertEqual(result.fast, 'ok')
+})
+
+// ---------------------------------------------------------------------------
+
+console.log(`\n${passed} passed, ${failed} failed\n`)
+if (failed > 0) process.exit(1)