@sequenceholdings/artifact-studio 0.2.6 → 0.3.0

package/dist/next/streams.js

@@ -0,0 +1,132 @@
+import { isNextArtifactRelativePath } from './protocol.js';
+/** One pull grants one <=64KiB chunk; unread responses cannot fill a message queue. */
+export function createNextArtifactStreams({ send }) {
+    const active = new Map();
+    const instanceId = globalThis.crypto.randomUUID();
+    let sequence = 0;
+    function open({ path, options, signal }) {
+        if (!isNextArtifactRelativePath({ path }) || !path.startsWith('/api/'))
+            return Promise.reject(new Error('Artifact stream requires an /api/ path'));
+        if (signal?.aborted)
+            return Promise.reject(new DOMException('Artifact stream aborted', 'AbortError'));
+        if (active.size >= 32)
+            return Promise.reject(new Error('Too many Artifact streams'));
+        const id = `artifact-next-stream-${instanceId}-${++sequence}`;
+        return new Promise((resolve, reject) => {
+            let controller;
+            let ready = false;
+            let credit = false;
+            let totalBytes = 0;
+            let resolvePull;
+            const timeout = setTimeout(() => fail(new Error('Artifact stream timed out')), 120_000);
+            const onAbort = () => fail(new DOMException('Artifact stream aborted', 'AbortError'));
+            function cleanup({ cancel }) {
+                active.delete(id);
+                clearTimeout(timeout);
+                signal?.removeEventListener('abort', onAbort);
+                resolvePull?.();
+                if (cancel) {
+                    try {
+                        send({ type: 'artifact-studio-bridge-cancel', id });
+                    }
+                    catch { /* The parent has already disconnected. */ }
+                }
+            }
+            function fail(error) {
+                if (!active.has(id))
+                    return;
+                cleanup({ cancel: true });
+                controller?.error(error);
+                reject(error);
+            }
+            const stream = new ReadableStream({
+                start(value) { controller = value; },
+                pull() {
+                    if (!active.has(id) || credit)
+                        return;
+                    credit = true;
+                    return new Promise((done) => {
+                        resolvePull = done;
+                        try {
+                            send({ type: 'artifact-studio-stream-pull', id });
+                        }
+                        catch {
+                            fail(new Error('Artifact stream disconnected'));
+                        }
+                    });
+                },
+                cancel() { cleanup({ cancel: true }); },
+            }, { highWaterMark: 0 });
+            function receiveReady(payload) {
+                if (ready || typeof payload.status !== 'number' || !Number.isInteger(payload.status) || payload.status < 200 || payload.status > 599) {
+                    fail(new Error('Invalid Artifact stream response'));
+                    return;
+                }
+                ready = true;
+                const headers = new Headers();
+                const rawHeaders = payload.headers;
+                if (typeof rawHeaders === 'object' && rawHeaders !== null && 'content-type' in rawHeaders && typeof rawHeaders['content-type'] === 'string') {
+                    try {
+                        headers.set('content-type', rawHeaders['content-type']);
+                    }
+                    catch {
+                        fail(new Error('Invalid Artifact stream headers'));
+                        return;
+                    }
+                }
+                const nullBody = [204, 205, 304].includes(payload.status);
+                resolve(new Response(nullBody ? null : stream, { status: payload.status, headers }));
+                if (nullBody) {
+                    controller?.close();
+                    cleanup({ cancel: true });
+                }
+            }
+            function receiveChunk(payload) {
+                const chunk = payload.chunk instanceof ArrayBuffer ? new Uint8Array(payload.chunk) : payload.chunk instanceof Uint8Array ? payload.chunk : null;
+                if (!ready || !credit || !chunk || chunk.byteLength > 65_536 || totalBytes + chunk.byteLength > 64 * 1024 * 1024) {
+                    fail(new Error('Invalid or oversized Artifact stream chunk'));
+                    return;
+                }
+                credit = false;
+                totalBytes += chunk.byteLength;
+                controller?.enqueue(chunk);
+                resolvePull?.();
+                resolvePull = undefined;
+            }
+            function receive(payload) {
+                if (payload.event === 'error') {
+                    fail(new Error(typeof payload.error === 'string' ? payload.error : 'Artifact stream failed'));
+                }
+                else if (payload.event === 'ready')
+                    receiveReady(payload);
+                else if (payload.event === 'chunk')
+                    receiveChunk(payload);
+                else if (payload.event === 'done') {
+                    if (!ready) {
+                        fail(new Error('Artifact stream ended before response'));
+                        return;
+                    }
+                    cleanup({ cancel: false });
+                    controller?.close();
+                }
+            }
+            active.set(id, { receive, fail });
+            signal?.addEventListener('abort', onAbort, { once: true });
+            try {
+                send({ type: 'artifact-studio-stream-open', id, path, options: options ?? {}, flowControl: 'pull' });
+            }
+            catch {
+                fail(new Error('Artifact stream could not be opened'));
+            }
+        });
+    }
+    return {
+        open,
+        receive({ payload }) {
+            if (payload.type === 'artifact-studio-stream' && typeof payload.id === 'string')
+                active.get(payload.id)?.receive(payload);
+        },
+        dispose() { for (const stream of active.values())
+            stream.fail(new Error('Artifact bridge disposed')); },
+    };
+}

package/dist/next/theme.d.ts

@@ -0,0 +1,10 @@
+import type { NextArtifactTheme } from './protocol.js';
+/** Apply a host snapshot without requiring React or reading the DOM during SSR. */
+export declare function createNextArtifactThemeApplier({ root }: {
+    root: HTMLElement;
+}): {
+    apply({ theme }: {
+        theme: NextArtifactTheme;
+    }): void;
+    dispose(): void;
+};

package/dist/next/theme.js

@@ -0,0 +1,45 @@
+/** Apply a host snapshot without requiring React or reading the DOM during SSR. */
+export function createNextArtifactThemeApplier({ root }) {
+    const originalClass = root.classList.contains('dark');
+    const originalTheme = root.getAttribute('data-theme');
+    const originalTokens = root.getAttribute('data-tokens');
+    const originalProperties = new Map();
+    let applied = new Set();
+    function attribute({ name, value }) {
+        if (value === null)
+            root.removeAttribute(name);
+        else
+            root.setAttribute(name, value);
+    }
+    function restoreProperty({ name }) {
+        const original = originalProperties.get(name);
+        if (original?.value)
+            root.style.setProperty(name, original.value, original.priority);
+        else
+            root.style.removeProperty(name);
+    }
+    return {
+        apply({ theme }) {
+            root.classList.toggle('dark', theme.dark);
+            attribute({ name: 'data-theme', value: theme.theme ?? originalTheme });
+            attribute({ name: 'data-tokens', value: theme.tokens ?? originalTokens });
+            for (const name of applied)
+                if (!(name in theme.vars))
+                    restoreProperty({ name });
+            for (const [name, value] of Object.entries(theme.vars)) {
+                if (!originalProperties.has(name))
+                    originalProperties.set(name, { value: root.style.getPropertyValue(name), priority: root.style.getPropertyPriority(name) });
+                root.style.setProperty(name, value);
+            }
+            applied = new Set(Object.keys(theme.vars));
+        },
+        dispose() {
+            root.classList.toggle('dark', originalClass);
+            attribute({ name: 'data-theme', value: originalTheme });
+            attribute({ name: 'data-tokens', value: originalTokens });
+            for (const name of applied)
+                restoreProperty({ name });
+            applied.clear();
+        },
+    };
+}

package/dist/next/transport.d.ts

@@ -0,0 +1,15 @@
+export interface NextArtifactMessageEvent {
+    origin: string;
+    source: unknown;
+    data: unknown;
+}
+/** Transport injection keeps SSR import/construction free from browser globals. */
+export interface NextArtifactMessageTransport {
+    readonly parent: object;
+    listen(listener: (event: NextArtifactMessageEvent) => void): () => void;
+    send(input: {
+        message: unknown;
+        targetOrigin: string;
+    }): void;
+}
+export declare function createNextArtifactWindowTransport(): NextArtifactMessageTransport;

package/dist/next/transport.js

@@ -0,0 +1,13 @@
+export function createNextArtifactWindowTransport() {
+    if (typeof window === 'undefined' || window.parent === window)
+        throw new Error('Connect the Artifact bridge inside its Atlas iframe');
+    const target = window.parent;
+    return {
+        parent: target,
+        listen(listener) {
+            window.addEventListener('message', listener);
+            return () => window.removeEventListener('message', listener);
+        },
+        send({ message, targetOrigin }) { target.postMessage(message, targetOrigin); },
+    };
+}

package/dist/next-build.d.ts

@@ -0,0 +1,29 @@
+import type { ArtifactStudioNextManifest } from './manifest.js';
+import type { SourceProvenance, SourceSpec } from './source-resolver.js';
+export declare function planNextProject({ root, manifest, environment }: {
+    root: string;
+    manifest: ArtifactStudioNextManifest;
+    environment: string;
+}): Promise<number>;
+export declare function nextSourceRepository({ spec, root }: {
+    spec: SourceSpec;
+    root: string;
+}): string;
+export declare function resolveNextRepositoryId({ spec, repository, baseUrl, token }: {
+    spec: SourceSpec;
+    repository: string;
+    baseUrl: string;
+    token: string;
+}): Promise<string>;
+export declare function submitNextBuild({ root, manifest, projectId, baseUrl, getToken, provenance, repository, repositoryId, channel, out }: {
+    root: string;
+    manifest: ArtifactStudioNextManifest;
+    projectId: string;
+    baseUrl: string;
+    getToken: () => Promise<string>;
+    provenance: SourceProvenance;
+    repository: string;
+    repositoryId?: string;
+    channel: 'active' | 'preview';
+    out?: string;
+}): Promise<number>;

package/dist/next-build.js

@@ -0,0 +1,129 @@
+import { execFileSync } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { mkdir, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { setTimeout as delay } from 'node:timers/promises';
+import { z } from 'zod';
+import { getJson, postJson } from './api.js';
+import { resolveRepo } from './git-service-client.js';
+import { readArtifactStudioSource } from './project.js';
+import { validateNextProject } from './next-project.js';
+const operationSchema = z.object({
+    operation: z.object({
+        id: z.string().min(1), status: z.string().min(1), kind: z.string().optional(),
+        error: z.union([z.string(), z.object({ message: z.string() })]).nullable().optional(),
+    }),
+    deployment: z.object({ id: z.string(), version: z.string() }).nullable().optional(),
+});
+export async function planNextProject({ root, manifest, environment }) {
+    await validateNextProject({ root, manifest, installed: false });
+    const source = await readArtifactStudioSource(root);
+    console.log(`[seq-studio] plan ${manifest.artifact.project_id} -> ${environment}`);
+    console.log(`  runtime: Next.js ${manifest.runtime.next}, React ${manifest.runtime.react}, Node ${manifest.runtime.node}`);
+    console.log(`  source: ${source.sourceHash} (${source.files.length} files)`);
+    console.log('  action: submit immutable source to Atlas for an isolated build and governed deployment');
+    console.log('  local validation only: Atlas validates environment bindings, permissions and policy before building');
+    return 0;
+}
+export function nextSourceRepository({ spec, root }) {
+    if (spec.kind === 'git-service')
+        return `${spec.namespace}/${spec.name}`;
+    if (spec.kind === 'git-url')
+        return spec.url;
+    let origin;
+    try {
+        origin = execFileSync('git', ['config', '--get', 'remote.origin.url'], { cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+    }
+    catch {
+        throw new Error('Next.js builds require a source repository. Create/clone a repository with seq-studio repos and commit the application before building.');
+    }
+    if (/^[\w.-]+@[\w.-]+:[\w./-]+$/.test(origin))
+        return origin;
+    try {
+        const url = new URL(origin);
+        if (url.protocol === 'https:' && !url.username && !url.password && !url.search && !url.hash)
+            return origin;
+    }
+    catch { /* Refuse opaque/local origins; do not include potential credentials in diagnostics. */ }
+    throw new Error('The Git origin must be a credential-free HTTPS or SSH repository URL. Store Git credentials in your credential manager.');
+}
+export async function resolveNextRepositoryId({ spec, repository, baseUrl, token }) {
+    if (spec.kind === 'git-service') {
+        return (await resolveRepo({ baseUrl, token, namespace: spec.namespace, name: spec.name })).id;
+    }
+    try {
+        const url = new URL(repository);
+        const match = /^\/api\/git-service\/repos\/([a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12})\/git\/?$/i.exec(url.pathname);
+        if (url.origin === new URL(baseUrl).origin && match)
+            return match[1];
+    }
+    catch { /* Opaque labels/SSH origins are valid preview provenance but cannot attest a release. */ }
+    throw new Error('Official Next.js releases require a Git Service repository in this Atlas environment. Push the reviewed revision, then run artifact deploy --repo <namespace>/<name> --ref main --env <env>.');
+}
+/** A verified repository build names a commit; anything else uploads the committed source snapshot. */
+function nextBuildRequestBody({ manifest, files, commit, provenance, repository, repositoryId, channel }) {
+    if (repositoryId)
+        return { repositoryId, commit, idempotencyKey: randomUUID(), channel };
+    return {
+        manifest,
+        files: files.map(({ path, content, encoding }) => ({ path, content, encoding: encoding ?? 'utf8' })),
+        git: { commit, ...(provenance.gitBranch ? { branch: provenance.gitBranch } : {}), dirty: provenance.gitDirty !== false, repository },
+        idempotencyKey: randomUUID(), channel,
+    };
+}
+export async function submitNextBuild({ root, manifest, projectId, baseUrl, getToken, provenance, repository, repositoryId, channel, out }) {
+    if (!provenance.gitCommit || !/^[a-f0-9]{40}$/i.test(provenance.gitCommit)) {
+        throw new Error('Commit the application source before requesting a hosted build. Use artifact dev for uncommitted local development.');
+    }
+    await validateNextProject({ root, manifest, installed: false });
+    const source = await readArtifactStudioSource(root);
+    if (channel === 'active' && !repositoryId)
+        throw new Error('An official release requires a verified Git Service repository.');
+    const path = `/api/artifact-studio/projects/${encodeURIComponent(projectId)}/next`;
+    const body = nextBuildRequestBody({ manifest, files: source.files, commit: provenance.gitCommit, provenance, repository, repositoryId, channel });
+    const response = operationSchema.parse(await postJson({ baseUrl, token: await getToken(), path: `${path}/builds${repositoryId ? '/from-repository' : ''}`, body }));
+    console.log(`[seq-studio] Atlas build ${response.operation.id} (${channel}) from ${provenance.gitCommit.slice(0, 12)}`);
+    console.log(`${baseUrl}/artifact-studio/projects/${projectId}`);
+    const controller = new AbortController();
+    const onSignal = () => controller.abort();
+    process.once('SIGINT', onSignal);
+    process.once('SIGTERM', onSignal);
+    let current = response;
+    let previousStatus = '';
+    try {
+        while (!controller.signal.aborted) {
+            if (current.operation.status !== previousStatus) {
+                previousStatus = current.operation.status;
+                console.log(`[seq-studio] ${previousStatus}`);
+            }
+            if (current.operation.status === 'failed' || current.operation.status === 'cancelled') {
+                const error = current.operation.error;
+                throw new Error(typeof error === 'string' ? error : error?.message ?? `Atlas build ${current.operation.status}. Inspect its build logs in Artifact Studio.`);
+            }
+            if (current.operation.status === 'succeeded') {
+                const completed = { ...current, deployment: current.deployment ?? response.deployment };
+                if (out) {
+                    await mkdir(dirname(out), { recursive: true });
+                    await writeFile(out, JSON.stringify(completed, null, 2) + '\n');
+                }
+                console.log(channel === 'active' ? '[seq-studio] application deployed by Atlas.' : '[seq-studio] hosted preview ready in Artifact Studio.');
+                if (completed.deployment)
+                    console.log(`${baseUrl}/artifact-studio/projects/${projectId}/deployments/${completed.deployment.id}`);
+                return 0;
+            }
+            try {
+                await delay(1500, undefined, { signal: controller.signal });
+            }
+            catch {
+                break;
+            }
+            current = operationSchema.parse(await getJson({ baseUrl, token: await getToken(), path: `${path}/operations/${encodeURIComponent(response.operation.id)}` }));
+        }
+        console.log('[seq-studio] Stopped waiting. The Atlas build continues; inspect or cancel it in Artifact Studio.');
+        return 0;
+    }
+    finally {
+        process.removeListener('SIGINT', onSignal);
+        process.removeListener('SIGTERM', onSignal);
+    }
+}

package/dist/next-cache/adapter-runtime.d.ts

@@ -0,0 +1,51 @@
+import { type CacheLookup, type NextCacheNamespace, type NextCacheStore } from './store.js';
+export interface NextCacheOptions {
+    store: NextCacheStore;
+    namespace: NextCacheNamespace;
+    maxEntryBytes?: number;
+    maxEntryAgeMs?: number;
+    streamTimeoutMs?: number;
+    /** Framework timestamps use performance.timeOrigin + performance.now(). */
+    now?: () => number;
+    onCacheError?: (event: {
+        operation: 'read' | 'write' | 'invalidate';
+    }) => void;
+}
+export interface ObservedLookup extends CacheLookup {
+    observedAt: number;
+}
+/** What a later set() needs from a lookup. Retained tickets never keep the entry payload. */
+export type ObservedWriteTicket = Pick<ObservedLookup, 'ticket' | 'observedAt'>;
+/**
+ * The ticket a later set() should use after this lookup. The earliest ticket is kept while the store
+ * would still accept it, since its observedAt is the fence against renders that began before it. Once
+ * the store has moved past it (an invalidation or another commit changed incarnation, epoch or version,
+ * or it outlived MAX_CACHE_WRITE_AGE_MS) a regeneration using it would be rejected, so this lookup's
+ * ticket replaces it; its later observedAt then fences out renders that began before the change.
+ */
+export declare function nextWriteTicket({ retained, lookup, now }: {
+    retained: ObservedWriteTicket | undefined;
+    lookup: ObservedLookup;
+    now: number;
+}): ObservedWriteTicket;
+export declare class CacheAdapterRuntime {
+    readonly store: NextCacheStore;
+    readonly namespace: NextCacheNamespace;
+    readonly maxEntryBytes: number;
+    readonly maxEntryAgeMs: number;
+    readonly streamTimeoutMs: number;
+    readonly now: () => number;
+    private readonly onCacheError?;
+    constructor(options: NextCacheOptions);
+    report(operation: 'read' | 'write' | 'invalidate'): void;
+    read({ key, tags }: {
+        key: string;
+        tags: string[];
+    }): Promise<ObservedLookup | undefined>;
+    invalidate({ tags, durations }: {
+        tags: string[];
+        durations?: {
+            expire?: number;
+        };
+    }): Promise<void>;
+}

package/dist/next-cache/adapter-runtime.js

@@ -0,0 +1,73 @@
+import { cacheNamespacePrefix, MAX_CACHE_ENTRY_AGE_MS, MAX_CACHE_ENTRY_BYTES, MAX_CACHE_WRITE_AGE_MS, } from './store.js';
+/**
+ * The ticket a later set() should use after this lookup. The earliest ticket is kept while the store
+ * would still accept it, since its observedAt is the fence against renders that began before it. Once
+ * the store has moved past it (an invalidation or another commit changed incarnation, epoch or version,
+ * or it outlived MAX_CACHE_WRITE_AGE_MS) a regeneration using it would be rejected, so this lookup's
+ * ticket replaces it; its later observedAt then fences out renders that began before the change.
+ */
+export function nextWriteTicket({ retained, lookup, now }) {
+    const current = { ticket: lookup.ticket, observedAt: lookup.observedAt };
+    if (!retained)
+        return current;
+    const unchanged = retained.ticket.incarnation === lookup.ticket.incarnation
+        && retained.ticket.epoch === lookup.ticket.epoch && retained.ticket.version === lookup.ticket.version;
+    return unchanged && now - retained.ticket.startedAt <= MAX_CACHE_WRITE_AGE_MS ? retained : current;
+}
+export class CacheAdapterRuntime {
+    store;
+    namespace;
+    maxEntryBytes;
+    maxEntryAgeMs;
+    streamTimeoutMs;
+    now;
+    onCacheError;
+    constructor(options) {
+        cacheNamespacePrefix(options.namespace);
+        this.store = options.store;
+        this.namespace = { ...options.namespace };
+        this.maxEntryBytes = options.maxEntryBytes ?? MAX_CACHE_ENTRY_BYTES;
+        this.maxEntryAgeMs = options.maxEntryAgeMs ?? MAX_CACHE_ENTRY_AGE_MS;
+        this.streamTimeoutMs = options.streamTimeoutMs ?? 10_000;
+        if (!Number.isSafeInteger(this.maxEntryBytes) || this.maxEntryBytes < 1 || this.maxEntryBytes > MAX_CACHE_ENTRY_BYTES
+            || !Number.isSafeInteger(this.maxEntryAgeMs) || this.maxEntryAgeMs < 1 || this.maxEntryAgeMs > MAX_CACHE_ENTRY_AGE_MS
+            || !Number.isSafeInteger(this.streamTimeoutMs) || this.streamTimeoutMs < 1 || this.streamTimeoutMs > 60_000) {
+            throw new Error('Invalid Next cache adapter limits');
+        }
+        this.now = options.now ?? (() => performance.timeOrigin + performance.now());
+        this.onCacheError = options.onCacheError;
+    }
+    report(operation) {
+        // Observability must not throw or expose payloads, tags, keys or credentials.
+        try {
+            this.onCacheError?.({ operation });
+        }
+        catch { /* Ignore telemetry failure. */ }
+    }
+    async read({ key, tags }) {
+        const observedAt = this.now();
+        try {
+            return { ...await this.store.read({ namespace: this.namespace, key, tags }), observedAt };
+        }
+        catch {
+            this.report('read');
+            return undefined;
+        }
+    }
+    async invalidate({ tags, durations }) {
+        try {
+            // A duration without expire means stale indefinitely. Entries are bounded by
+            // maxEntryAgeMs, so this upper bound preserves that behavior without infinity.
+            const expireAfterMs = durations ? Math.min(this.maxEntryAgeMs, (durations.expire ?? this.maxEntryAgeMs / 1000) * 1000) : 0;
+            if (durations?.expire !== undefined && (!Number.isFinite(durations.expire) || durations.expire < 0)) {
+                throw new Error('Invalid cache invalidation duration');
+            }
+            await this.store.invalidate({ namespace: this.namespace, tags, expireAfterMs: Math.ceil(expireAfterMs) });
+        }
+        catch {
+            this.report('invalidate');
+            // A mutation must never be reported successful when invalidation is uncertain.
+            throw new Error('Next cache invalidation did not complete');
+        }
+    }
+}

package/dist/next-cache/component-handler.d.ts

@@ -0,0 +1,3 @@
+import type { NextComponentCacheHandler } from './components.js';
+declare const handler: NextComponentCacheHandler;
+export { handler as default };

package/dist/next-cache/component-handler.js

@@ -0,0 +1,10 @@
+import { getArtifactNextRuntimeCache } from './runtime.js';
+const handler = {
+    get: (key, tags) => getArtifactNextRuntimeCache().cacheComponents.get(key, tags),
+    set: (key, pending) => getArtifactNextRuntimeCache().cacheComponents.set(key, pending),
+    refreshTags: () => getArtifactNextRuntimeCache().cacheComponents.refreshTags(),
+    getExpiration: (tags) => getArtifactNextRuntimeCache().cacheComponents.getExpiration(tags),
+    updateTags: (tags, durations) => getArtifactNextRuntimeCache().cacheComponents.updateTags(tags, durations),
+};
+// Next's configuration loader requires a default export from handler modules.
+export { handler as default };

package/dist/next-cache/components.d.ts

@@ -0,0 +1,20 @@
+import { type NextCacheOptions } from './adapter-runtime.js';
+/** Next.js 16.3 Cache Components contract; no unstable Next internal imports. */
+export interface NextComponentCacheEntry {
+    value: ReadableStream<Uint8Array>;
+    tags: string[];
+    stale: number;
+    timestamp: number;
+    expire: number;
+    revalidate: number;
+}
+export interface NextComponentCacheHandler {
+    get(key: string, softTags: string[]): Promise<NextComponentCacheEntry | undefined>;
+    set(key: string, pendingEntry: Promise<NextComponentCacheEntry>): Promise<void>;
+    refreshTags(): Promise<void>;
+    getExpiration(tags: string[]): Promise<number>;
+    updateTags(tags: string[], durations?: {
+        expire?: number;
+    }): Promise<void>;
+}
+export declare function createComponentCacheHandler(options: NextCacheOptions): NextComponentCacheHandler;

package/dist/next-cache/components.js

@@ -0,0 +1,113 @@
+import { z } from 'zod';
+import { CacheAdapterRuntime, nextWriteTicket } from './adapter-runtime.js';
+import { createCacheStream, deserializeCacheValue, readCacheStream, serializeCacheValue } from './serialization.js';
+import { normalizeCacheTags } from './store.js';
+const metadataSchema = z.object({
+    tags: z.array(z.string()), stale: z.number().finite().nonnegative(),
+    timestamp: z.number().finite().nonnegative(), expire: z.number().finite(),
+    revalidate: z.number().finite(),
+});
+const recordSchema = metadataSchema.extend({ format: z.literal('component-v1'), bytes: z.instanceof(Uint8Array) });
+function discardStream(value) {
+    void value.cancel().catch(() => { });
+}
+async function awaitEntry({ pending, timeoutMs }) {
+    let timer;
+    try {
+        return await Promise.race([pending, new Promise((_, reject) => {
+                timer = setTimeout(() => reject(new Error('Pending Next cache entry timed out')), timeoutMs);
+            })]);
+    }
+    catch (error) {
+        void pending.then((entry) => discardStream(entry.value), () => { });
+        throw error;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+export function createComponentCacheHandler(options) {
+    const runtime = new CacheAdapterRuntime(options);
+    // Process-wide and bounded to 512 keys, so it holds write tickets only, never cached payloads.
+    const tickets = new Map();
+    const pendingSets = new Map();
+    async function persist({ key, pending, lookup }) {
+        let stream;
+        try {
+            const entry = await awaitEntry({ pending, timeoutMs: runtime.streamTimeoutMs });
+            stream = entry.value;
+            if (!lookup) {
+                discardStream(entry.value);
+                return;
+            }
+            const metadata = metadataSchema.parse(entry);
+            const ttlMs = Math.min(runtime.maxEntryAgeMs, Math.ceil(metadata.timestamp + metadata.expire * 1000 - runtime.now()));
+            // Do not let an older render consume a newer generation's write ticket.
+            if (metadata.timestamp < lookup.observedAt || ttlMs <= 0) {
+                discardStream(entry.value);
+                return;
+            }
+            const tags = normalizeCacheTags(metadata.tags);
+            const bytes = await readCacheStream({ stream: entry.value, maxBytes: runtime.maxEntryBytes, timeoutMs: runtime.streamTimeoutMs });
+            const payload = serializeCacheValue({ value: { ...metadata, format: 'component-v1', bytes }, limits: { maxBytes: runtime.maxEntryBytes } });
+            await runtime.store.commit({ namespace: runtime.namespace, key: `component:${key}`, ticket: lookup.ticket, payload, tags, ttlMs });
+        }
+        catch {
+            if (stream && !stream.locked)
+                discardStream(stream);
+            runtime.report('write');
+        }
+    }
+    return {
+        async get(key, softTags) {
+            try {
+                await pendingSets.get(key);
+                const lookup = await runtime.read({ key: `component:${key}`, tags: normalizeCacheTags(softTags) });
+                if (!lookup)
+                    return undefined;
+                // Payload-free: a hit that is never re-rendered must not pin its serialized entry here. A ticket
+                // left by an earlier hit is replaced once the store has moved past it (invalidation, another
+                // commit, or age), so the first regeneration after an invalidation can actually commit.
+                const retained = tickets.get(key);
+                const next = nextWriteTicket({ retained, lookup, now: runtime.now() });
+                if (next !== retained) {
+                    if (!retained && tickets.size >= 512)
+                        tickets.delete(tickets.keys().next().value ?? '');
+                    tickets.set(key, next);
+                }
+                if (!lookup.entry)
+                    return undefined;
+                const record = recordSchema.parse(deserializeCacheValue({ serialized: lookup.entry.payload, limits: { maxBytes: runtime.maxEntryBytes } }));
+                if (record.expire <= 0 || runtime.now() >= record.timestamp + record.expire * 1000)
+                    return undefined;
+                return { tags: record.tags, stale: record.stale, timestamp: record.timestamp,
+                    expire: record.expire, revalidate: lookup.entry.stale ? -1 : record.revalidate,
+                    value: createCacheStream({ bytes: record.bytes }) };
+            }
+            catch {
+                runtime.report('read');
+                return undefined;
+            }
+        },
+        async set(key, pendingEntry) {
+            const lookup = tickets.get(key);
+            tickets.delete(key);
+            if (pendingSets.has(key) || pendingSets.size >= 128) {
+                await persist({ key, pending: pendingEntry });
+                return;
+            }
+            const pending = persist({ key, pending: pendingEntry, lookup });
+            pendingSets.set(key, pending);
+            try {
+                await pending;
+            }
+            finally {
+                if (pendingSets.get(key) === pending)
+                    pendingSets.delete(key);
+            }
+        },
+        async refreshTags() { },
+        async getExpiration() { return Infinity; }, // Next passes soft tags into get().
+        async updateTags(tags, durations) { await runtime.invalidate({ tags, durations }); },
+    };
+}