@playstack/render
Render cache purge requests and durable change coordination with explicit targeting, safe outcomes and optional Redis persistence.
Reference: @playstack/render@0.1.0-beta.5 · TypeScript
Pro. Covered by the Playstack Pro License. Registry access is required; check preview availability before installing. See package access.
@playstack/render submits a cache purge for one explicitly configured Render web
service. It accepts a server-only credential, transport and clock without importing
Next, Redis or queue adapters.
Install
After confirming preview access, install the package at your application's shared Playstack version:
npm install --save-exact @playstack/render@0.1.0-beta.5Check the peer requirements below before choosing a runtime or provider.
Request a purge
import { createRenderPurgeClient } from '@playstack/render'
const render = createRenderPurgeClient({
apiKey: renderApiKey,
serviceId: renderSiteServiceId,
fetch: globalThis.fetch,
clock: { nowMs: Date.now },
})
const receipt = await render.purgeCache({ signal: shutdownSignal })The client makes one bodyless POST to the fixed official API endpoint with redirect refusal and a per-invocation deadline. It never infers the site target from the worker's own service ID. Its default whole-call timeout is 15 seconds, including response disposal, with a maximum of 60 seconds.
Acceptance and safe failures
Only observed HTTP 202 returns an accepted receipt. A service purge covers all of its edge entries; it does not select routes or establish completed propagation. A caller must preserve changes arriving during a request and verify real content freshness separately. See Render's purge API.
RenderPurgeError exposes fixed codes, numeric status/rate metadata and
not_submitted, not_accepted or unknown outcomes. Configuration/pre-call
cancellation does not dispatch; timeouts, transport failures and cancellation
after invocation cannot prove that no request escaped. Bodies, URLs, credentials
and raw error causes are excluded. Known acceptance survives bad optional metadata
or cleanup failures. The client never automatically retries.
Validated rate counters and absolute reset/retry deadlines help caller scheduling.
Render's reset header is in epoch seconds; public resetAt/retryAt values use
epoch milliseconds. Deadlines are not silently shortened. Quotas are shared across
API endpoint groups/users, so coordinate more than just a service-local timer.
See Render rate limits.
Coordinate pending public changes
@playstack/render/coordination persists change generations independently of queue
wakeups. @playstack/render/coordination/redis supplies atomic Redis persistence
without bundling a Redis SDK. Native node-redis clients work directly;
createIoredisRenderPurgeClient() adapts existing ioredis/BullMQ clients.
import { createRenderPurgeCoordinator } from '@playstack/render/coordination'
import { RedisRenderPurgePersistence } from '@playstack/render/coordination/redis'
const persistence = new RedisRenderPurgePersistence(redis, {
namespace: 'public_content_prod',
serviceId: render.serviceId,
quotaScope: 'render_api_user',
})
const coordinator = createRenderPurgeCoordinator({ client: render, persistence })
await coordinator.publicContentChanged()
const result = await coordinator.processPending({ signal: workerShutdownSignal })Use a reliable post-commit signal handoff and an independent periodic worker sweep. The package does not install a scheduler or require a queue migration. A claim reserves cooldown before HTTP and captures a precise generation; accepted work acknowledges only that snapshot. New changes stay pending, while stale workers cannot clear a successor's lease. Generation/lease counters remain decimal strings, including above JavaScript's exact integer range.
Shared API-user scopes retain provider deadlines separately from normal spacing. A stale 429 may extend the deadline without changing the current owner. The final storage check can refuse an outstanding unsent permit, while factual completion of already-started work remains recordable. This is cooperative coordination, not remote recall or proof of physical request drainage.
An accepted result with recording: 'unconfirmed' means Render acceptance is known
but its durable acknowledgment is uncertain. Recovery inspects retained state;
it does not erase pending work or invent a new event identity to skip cooldowns.
Temporary or unclassified storage failures expose
coordination_storage_unavailable with retryable: true. Configuration/input
errors, malformed replies and native integrity refusals remain non-retryable,
including through coordinator wrapping. Messages are fixed and exclude raw Redis
diagnostics. Retrying coordination still observes persistent leases and cooldowns;
an uncertain write acknowledgment is not permission to repeat provider work
unconditionally. Hosts own bounded backoff and investigation of unavailable or
misconfigured storage.
Inspection reports the effective deadline across provider minima, ordinary spacing and service/shared-quota leases. Another service's longer active lease is included. Inspection never replaces the atomic claim and final dispatch check.
Persist namespace/service/quota bindings together. Use a durable Redis deployment
with noeviction, bounded command behavior and reviewed access to its namespace.
Keys share a Cluster hash slot and must never be expired or reset during cleanup.
Existing expiring/corrupt state and mismatched scopes refuse before writes.
This new state contract needs an explicit cutover from application-owned keys;
no old-format reader or automatic migration is supplied.
Compose independently
Use a bounded non-retrying transport that honors cancellation; promise deadlines do not prove physical socket drainage or remote cancellation. Hosts own shutdown, durable pending changes, retries and service credentials.
The separate Render Next adapter provides explicit Pages Router final-response policy and production-server lifecycle without requiring a purge client, Redis page cache or queue migration. Cache Next continues to handle the origin cache and revalidation without becoming a dependency of this edge-purge client. Revalidate any origin cache before purging the edge to avoid repopulating it with stale origin content.
Local Node/Workers and packed consumer qualification does not replace a real Render staging test. Warm an edge HIT, mutate content, observe accepted purge and verify updated HTML/data before production activation. Yalc/registry publication and host configuration remain operator actions.
API entry points and requirements
Reference snapshot: @playstack/render@0.1.0-beta.5. Import only the entry point your runtime needs. Paths below are relative to the installed package; use Go to Definition in your editor to inspect exact parameters, return types and overloads. Do not import the declaration-file paths directly.
| Public entry point | Declaration file |
|---|---|
@playstack/render | ./dist/index.d.ts |
@playstack/render/errors | ./dist/errors.d.ts |
@playstack/render/package.json | No TypeScript declaration (asset or metadata export). |
@playstack/render/coordination | ./dist/coordination.d.ts |
@playstack/render/coordination/redis | ./dist/coordination-redis.d.ts |
Node.js engine requirement: >=20. This is not a claim that every entry point works in browsers or Workers.
Peer dependencies
This package declares no peer dependencies. Its ordinary dependencies are resolved by the package manager.
For a complete first program, start with Getting started. For API lookup and partial-example conventions, see Reading the reference. Provider failures, lifecycle requirements and application responsibilities remain described in the guide above; types alone do not establish production safety.