Changelog

Latest updates and improvements across hypequery packages and docs.

[Upcoming]

Serve and CLI Updates

This release pushes the current object-style hypequery path further forward: query({ ... }) + serve({ queries }) is now the clearer default for new integrations, and the underlying serve runtime and CLI scaffolding both support that direction more directly.

What changed

• @hypequery/serve now supports object-style auth and tenant metadata more completely. Object-style query definitions can carry runtime metadata such as:

  • requiresAuth
  • auth
  • tenant
  • requiredRoles
  • requiredScopes
  • custom

  That metadata is preserved when queries are defined with query({ ... }), reused through serve({ queries }), and surfaced through runtime inspection/endpoint descriptions.

• Object-style auth requirements are enforced through the serve runtime, including public routes and role/scope-based authorization. This closes a gap between the newer object-style API and the older builder-first flow.

• Object-style tenant overrides now apply through the serve runtime, so per-query tenant behavior works in the newer API without requiring a fallback to builder-first patterns.

• @hypequery/cli now scaffolds the current main path by default. Generated query templates use:

  • initServe(...)
  • object-style query({ ... })
  • serve({ queries })

  instead of centering the older builder-first serve style in generated starter code.

• The docs and migration path now line up with the shipped API direction. The current object-style runtime API is documented as the primary path, while the older builder-first serve docs are preserved under v0.1.x for teams that are still migrating.

• Docs search is now better at finding code/API terms like dictGet, withScalar, and similar technical keywords that appear primarily in examples and code snippets.

Why it matters

• New projects start on the current query/serve API instead of scaffolding into a style they immediately need to migrate away from.
• Existing users get a clearer migration path from the v0.1.x serve flow to the current object-style runtime API.
• The newer query/serve API is now closer to feature parity for auth and tenant concerns, reducing the need to fall back to older patterns.

[1.5.0]

Breaking Changes

• DateTime type mapping correction: DateTime, DateTime64, Date, and Date32 columns are now correctly typed as string instead of Date. This matches the actual runtime behavior of @clickhouse/client when using JSON output formats (like JSONEachRow), which return DateTime values as strings to preserve sub-millisecond precision that JavaScript Date objects cannot represent.

  Migration guide:

  // Before (would fail at runtime):
  const results = await db.table('products').select(['created_at']).execute();
  results[0].created_at.toISOString(); // TypeError: toISOString is not a function
  
  // After (correctly typed):
  const results = await db.table('products').select(['created_at']).execute();
  // TypeScript now correctly knows created_at is a string
  const date = new Date(results[0].created_at); // Convert to Date when needed
  date.toISOString(); // Works!

  Why this change: Previously, TypeScript indicated these fields were Date objects, but at runtime they were actually strings. This caused type mismatches and runtime errors. The fix surfaces this at compile time, preventing bugs.

[1.4.0]

Features

• add an experimental caching layer that plugs into every execute() call: supports cache-first, network-first, and stale-while-revalidate modes, per-query overrides, tag invalidation, in-flight dedupe, cache-aware logging metadata, and a CacheController API for warming or inspecting hit stats. Ships with a memory LRU provider plus serialization helpers and provider hooks for custom stores.

• expand the example dashboard with a cache demo page (/cache), refresh/invalidate buttons, warming + stats API routes, and environment toggles so developers can see cache hits/misses/stale hits in real time.

Fixes / Improvements

• ensure cached entries default cacheTimeMs to ttlMs + staleTtlMs, fix namespace parsing in the memory provider so tag invalidation works even when the host contains a protocol, and run mergeCacheOptionsPartial/initializeCacheRuntime helpers to keep query-builder lean.

• simplify the example dashboard configuration by removing the Upstash fallback, documenting provider requirements (tag hooks/TTL handling), and adding /api/cache/* endpoints to warm caches and inspect hit rates.

• make npm run test fast again (unit + type tests only) while moving integration tests behind npm run test:integration, and streamline withRelation so chained relationships reuse a single join applier.

[1.3.2]

Features

• teach expressions and select clauses their result types, so aliased expressions (e.g. rawAs<number, 'avg_total'>) flow through to the query output and expression helpers know whether they produce booleans, numbers, etc.

• refactor the query builder around a single state object: joins now widen the visible-table set (including aliases), predicates/order/group/having all read from that state, and the new selectConst() helper locks in literal column inference for downstream clauses. Runtime/type tests and docs were updated to cover alias-aware joins, HAVING-on-alias flows, and withCTE pipelines.

[1.3.0]

Features

• add predicate-builder callbacks (with ClickHouse function + logical helpers) to where/orWhere, enabling predicates like hasAny(tags, ['foo','bar']) without raw SQL; columns/arrays are inferred automatically and expr.raw() provides an escape hatch for edge cases