Unverified Commit c0dfeffa authored by MB's avatar MB Committed by GitHub

Add next/cache-handlers types entrypoint (#97592)

### What?

Exposes the `cacheHandlers` types (`CacheHandler`, `CacheEntry`) as
types-only exports from `next/cache`, so handlers can be checked against
the real interface:

```ts
import type { CacheHandler } from 'next/cache'
```

### Why?

Custom cache handler authors currently import `CacheHandler` and
`CacheEntry` from `next/dist/server/lib/cache-handlers/types` (an
internal path that can move between versions) or hand-copy the
interfaces, which drift silently across releases.

### Motivation

I'm working on a custom community cache handler and it'd be great to
import the types directly and keep testing against the source of truth,
rather than maintaining a hand-copied mirror that has to be re-checked
on every Next.js release.

Raised in discussion #96356.

### How?

- Adds a type-only `export type { CacheHandler, CacheEntry }` to
`packages/next/cache.d.ts`, re-exported from
`./dist/server/lib/cache-handlers/types`. No new subpath or
`package.json` `"files"` entries needed since `next/cache` already
ships.
- Docs: `cacheHandlers.mdx` now shows the public `next/cache` import
instead of the GitHub source links.
- Tests: a `satisfies CacheHandler` / `satisfies CacheEntry` fixture in
the `typescript-basic` typechecking suite (runs `tsc` against the
installed package), and the `use-cache-custom-handler` e2e fixture's
JSDoc now uses the public import.

(Originally proposed as a separate `next/cache-handlers` types-only
subpath, following the `next/types` pattern moved the export into
`next/cache` per review.)

Related: #96356

closes #97781 (only created to run deploy tests)
parent a1cc1eaf
...@@ -71,7 +71,11 @@ Note that `'use cache: private'` does not use cache handlers and cannot be custo ...@@ -71,7 +71,11 @@ Note that `'use cache: private'` does not use cache handlers and cannot be custo
## API Reference ## API Reference
A cache handler must implement the [`CacheHandler`](https://github.com/vercel/next.js/blob/canary/packages/next/src/server/lib/cache-handlers/types.ts) interface with the following methods: A cache handler must implement the `CacheHandler` interface with the following methods. The `CacheHandler` and `CacheEntry` types are exported from `next/cache`:
```ts
import type { CacheHandler, CacheEntry } from 'next/cache'
```
### `get()` ### `get()`
...@@ -227,7 +231,7 @@ const cacheHandler = { ...@@ -227,7 +231,7 @@ const cacheHandler = {
## CacheEntry Type ## CacheEntry Type
The [`CacheEntry`](https://github.com/vercel/next.js/blob/canary/packages/next/src/server/lib/cache-handlers/types.ts) object has the following structure: The `CacheEntry` object (exported from `next/cache`) has the following structure:
```ts ```ts
interface CacheEntry { interface CacheEntry {
......
export { unstable_cache } from 'next/dist/server/web/spec-extension/unstable-cache' export { unstable_cache } from 'next/dist/server/web/spec-extension/unstable-cache'
export type {
CacheHandler,
CacheEntry,
} from './dist/server/lib/cache-handlers/types'
export { export {
revalidatePath, revalidatePath,
revalidateTag, revalidateTag,
......
...@@ -6,7 +6,7 @@ const { AsyncLocalStorage } = require('node:async_hooks') ...@@ -6,7 +6,7 @@ const { AsyncLocalStorage } = require('node:async_hooks')
const snapshot = AsyncLocalStorage.snapshot() const snapshot = AsyncLocalStorage.snapshot()
/** /**
* @type {import('next/dist/server/lib/cache-handlers/types').CacheHandler} * @type {import('next/cache').CacheHandler}
*/ */
const cacheHandler = { const cacheHandler = {
async get(cacheKey, softTags) { async get(cacheKey, softTags) {
......
import type { CacheHandler, CacheEntry } from 'next/cache'
// eslint-disable-next-line @typescript-eslint/no-unused-expressions
;() => {
;({
value: new ReadableStream<Uint8Array>(),
tags: [],
stale: 0,
timestamp: 0,
expire: 0,
revalidate: 0,
}) satisfies CacheEntry
;({
async get(_cacheKey: string, _softTags: string[]) {
return undefined
},
async set(_cacheKey: string, _pendingEntry: Promise<CacheEntry>) {},
async refreshTags() {},
async getExpiration(_tags: string[]) {
return 0
},
async updateTags(_tags: string[], _durations?: { expire?: number }) {},
}) satisfies CacheHandler
}
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment