Molecule.dev

@molecule/app-query-memory

Provider bond · query · App (browser) · v1.0.1 · Apache-2.0

Dependency-free in-memory bond for @molecule/app-query — a Map of documents with freshness, in-flight sharing and observers

npm install @molecule/app-query-memory

npm · Source on GitHub · Implements @molecule/app-query

How it works

@molecule/app-query-memory is a provider bond on the app (browser) side: it implements the query core interface (@molecule/app-query) with a concrete vendor or library behind it.

Your code calls the core; you wire this provider once at startup. Swapping vendors later is one line in that wiring, not a rewrite.

import { getQueryClient, setProvider } from '@molecule/app-query'
import { provider } from '@molecule/app-query-memory'

setProvider(provider)
const client = getQueryClient()
await client.fetch({ key: ['profile'], fetch: (signal) => api.get('/me', { signal }) })

Works with: @molecule/app-query

Reference

In-memory bond for @molecule/app-query.

A Map of documents with freshness, shared in-flight fetches, observers and garbage collection, and nothing else: no dependency, a few kilobytes. The right bond when the app has no other reason to ship a query library; the @molecule/app-query-tanstack bond is the same contract over TanStack Query for apps that already use it or want its devtools.

Quick Start

import { getQueryClient, setProvider } from '@molecule/app-query'
import { provider } from '@molecule/app-query-memory'

setProvider(provider)
const client = getQueryClient()
await client.fetch({ key: ['profile'], fetch: (signal) => api.get('/me', { signal }) })

Type

provider

Installation

npm install @molecule/app-query-memory @molecule/app-query

API

Interfaces

MemoryQueryConfig

Provider-specific configuration options. The in-memory bond needs none beyond the core's QueryClientConfig; the type exists so createProvider has the same shape as every other bond's.

interface MemoryQueryConfig {
  /** Reserved. */
  readonly _?: never
}

Functions

createProvider(_config)

Creates an in-memory query provider.

function createProvider(_config?: MemoryQueryConfig): QueryProvider
  • _config — Provider configuration (none today).

Returns: A query provider.

Constants

provider

Default in-memory provider instance.

const provider: QueryProvider

Core Interface

Implements @molecule/app-query interface.

Bond Wiring

Setup function to register this provider with the core interface:

import { setProvider } from '@molecule/app-query'
import { provider } from '@molecule/app-query-memory'

export function setupQueryMemory(): void {
  setProvider(provider)
}

Injection Notes

Requirements

Peer dependencies:

  • @molecule/app-query ^1.0.0

Runtime Dependencies

  • @molecule/app-query

  • Documents are dropped gcMs after their last observer leaves (default 30 minutes) — a cache, not a store: nothing survives a reload.

  • subscribe() refetches a stale document while still emitting the stale data first, so a component paints at once and updates when the fresh copy lands.

  • Swapping to @molecule/app-query-tanstack changes no application code: both pass the same behavioural suite.

E2E Tests

Integration checklist — drive the real UI (live preview, no mocks), adapt each item to this app's actual screens/flows, and check every box off one by one. A box you can't check is an integration bug to fix — not a skip:

  • Opening a detail page after hovering its link shows no loading state (the document was warmed) and the page is the right one.
  • Opening the same page twice fetches it once (check the network panel).
  • Going back to a page painted earlier paints at once, from memory.
  • After the app invalidates a key (an edit, a refresh action), the next view shows the new data.
  • With the browser's data-saver on, hovering links fetches nothing.