第 11 讲｜数据获取：fetch 增强、unstable_cache、'use cache'

export const NEXT_PATCH_SYMBOL = Symbol.for('next-patch')

function isFetchPatched() {
  return (globalThis as Record<symbol, unknown>)[NEXT_PATCH_SYMBOL] === true
}

interface NextFetchRequestConfig {
  revalidate?: number | false; // 0 等价 no-store
  tags?: string[]; // 用于 revalidateTag
}

// 业务示例：商品详情接口
const res = await fetch(`https://api.example.com/products/${id}`, {
  next: {
    revalidate: 60, // 60 秒后台重新拉
    tags: [`product:${id}`, "product"], // 标签维度失效
  },
});

export function validateRevalidate(
  revalidateVal: unknown,
  route: string
): undefined | number {
  try {
    let normalizedRevalidate: number | undefined = undefined

    if (revalidateVal === false) {
      normalizedRevalidate = INFINITE_CACHE
    } else if (
      typeof revalidateVal === 'number' &&
      !isNaN(revalidateVal) &&
      revalidateVal > -1
    ) {
      normalizedRevalidate = revalidateVal
    } else if (typeof revalidateVal !== 'undefined') {
      throw new Error(
        `Invalid revalidate value "${revalidateVal}" on "${route}", must be a non-negative number or false`
      )
    }
    return normalizedRevalidate
  } catch (err: any) {
    // ...
    return undefined
  }
}

export function validateTags(tags: any[], description: string) {
  const validTags: string[] = []
  const invalidTags: Array<{
    tag: any
    reason: string
  }> = []

  for (let i = 0; i < tags.length; i++) {
    const tag = tags[i]

    if (typeof tag !== 'string') {
      invalidTags.push({ tag, reason: 'invalid type, must be a string' })
    } else if (tag.length > NEXT_CACHE_TAG_MAX_LENGTH) {
      invalidTags.push({
        tag,
        reason: `exceeded max length of ${NEXT_CACHE_TAG_MAX_LENGTH}`,
      })
    } else {
      // Encode so a non-ASCII tag can be safely serialized into the
      // `x-next-cache-tags` HTTP header without tripping Node's header
      // validation. Length is checked on the raw input above.
      validTags.push(encodeCacheTag(tag))
    }

    if (validTags.length > NEXT_CACHE_TAG_MAX_ITEMS) {
      console.warn(
        `Warning: exceeded max tag count for ${description}, dropped tags:`,
        tags.slice(i).join(', ')
      )
      break
    }
  }
  // ...
  return validTags
}

async function getUser(id: string) {
  const res = await fetch(`/api/user/${id}`, { next: { revalidate: 60 } });
  return res.json();
}

// Page 与 Layout 同时调用
// 实际只发 1 次 HTTP 请求

function trackFetchMetric(
  workStore: WorkStore,
  ctx: Omit<FetchMetric, 'end' | 'idx'>
) {
  if (!workStore.shouldTrackFetchMetrics) {
    return
  }

  workStore.fetchMetrics ??= []

  workStore.fetchMetrics.push({
    ...ctx,
    end: performance.timeOrigin + performance.now(),
    idx: workStore.nextFetchId || 0,
  })
}

export function unstable_cache<T extends Callback>(
  cb: T,
  keyParts?: string[],
  options: {
    /**
     * The revalidation interval in seconds.
     */
    revalidate?: number | false
    tags?: string[]
  } = {}
): T {

  // Stash the fixed part of the key at construction time. The invocation key will combine
  // the fixed key with the arguments when actually called
  // ...
  const fixedKey = `${cb.toString()}-${
    Array.isArray(keyParts) && keyParts.join(',')
  }`

  const cachedCb = async (...args: any[]) => {
    const workStore = workAsyncStorage.getStore()
    const workUnitStore = workUnitAsyncStorage.getStore()

    // We must be able to find the incremental cache otherwise we throw
    const maybeIncrementalCache:
      | import('../../lib/incremental-cache').IncrementalCache
      | undefined =
      workStore?.incrementalCache || (globalThis as any).__incrementalCache

    if (!maybeIncrementalCache) {
      throw new Error(
        `Invariant: incrementalCache missing in unstable_cache ${cb.toString()}`
      )
    }
    const incrementalCache = maybeIncrementalCache
    // ...
      // Construct the complete cache key for this function invocation
      const invocationKey = `${fixedKey}-${JSON.stringify(args)}`
      const cacheKey = await incrementalCache.generateCacheKey(invocationKey)

const getUser = unstable_cache(
  async (id: string) => db.user.findUnique({ where: { id } }),
  ["getUser"], // 推荐：避免不同 unstable_cache 的 closure 撞键
  { revalidate: 60, tags: ["users"] },
);

// 形态 A：函数级
async function getProducts() {
  "use cache";
  const res = await fetch("/api/products");
  return res.json();
}

// 形态 B：组件级
async function ProductList() {
  "use cache";
  const products = await db.product.findMany();
  return (
    <ul>
      {products.map((p) => (
        <li key={p.id}>{p.name}</li>
      ))}
    </ul>
  );
}

// 形态 C：文件级（顶部加指令）
("use cache");
export async function getProducts() {
  /* ... */
}

export type CacheLife = {
  // How long the client can cache a value without checking with the server.
  stale?: number
  // How frequently you want the cache to refresh on the server.
  // Stale values may be served while revalidating.
  revalidate?: number
  // In the worst case scenario, where you haven't had traffic in a while,
  // how stale can a value be until you prefer deopting to dynamic.
  // Must be longer than revalidate.
  expire?: number
}

type CacheLifeProfiles =
  | 'default'
  | 'seconds'
  | 'minutes'
  | 'hours'
  | 'days'
  | 'weeks'
  | 'max'
  | (string & {})

// next.config.js
module.exports = {
  experimental: {
    cacheLife: {
      // 自定义 5 分钟 profile
      "five-minutes": {
        stale: 60,
        revalidate: 300,
        expire: 600,
      },
    },
  },
};

async function getX() {
  "use cache";
  cacheLife("five-minutes");
  // ...
}

export function cacheTag(...tags: string[]): void {
  if (!process.env.__NEXT_USE_CACHE) {
    throw new Error(
      '`cacheTag()` is only available with the `cacheComponents` config.'
    )
  }

  const workUnitStore = workUnitAsyncStorage.getStore()

  switch (workUnitStore?.type) {
    case 'prerender':
    case 'prerender-client':
    case 'validation-client':
    case 'prerender-runtime':
    case 'prerender-ppr':
    case 'prerender-legacy':
    case 'request':
    case 'unstable-cache':
    case 'generate-static-params':
    case undefined:
      throw new Error(
        '`cacheTag()` can only be called inside a "use cache" function.'
      )
    case 'cache':
    case 'private-cache':
      break
    default:
      workUnitStore satisfies never
  }

  const validTags = validateTags(tags, '`cacheTag()`')

  if (!workUnitStore.tags) {
    workUnitStore.tags = validTags
  } else {
    workUnitStore.tags.push(...validTags)
  }
}

  if (profile.revalidate !== undefined) {
    // Track the explicit revalidate time.
    if (
      workUnitStore.explicitRevalidate === undefined ||
      workUnitStore.explicitRevalidate > profile.revalidate
    ) {
      workUnitStore.explicitRevalidate = profile.revalidate
    }
  }
  if (profile.expire !== undefined) {
    // Track the explicit expire time.
    if (
      workUnitStore.explicitExpire === undefined ||
      workUnitStore.explicitExpire > profile.expire
    ) {
      workUnitStore.explicitExpire = profile.expire
    }
  }
  if (profile.stale !== undefined) {
    // Track the explicit stale time.
    if (
      workUnitStore.explicitStale === undefined ||
      workUnitStore.explicitStale > profile.stale
    ) {
      workUnitStore.explicitStale = profile.stale
    }
  }

export interface CacheHandler {
  /**
   * Retrieve a cache entry for the given cache key, if available. Will return
   * undefined if there's no valid entry, or if the given soft tags are stale.
   */
  get(cacheKey: string, softTags: string[]): Promise<undefined | CacheEntry>

  /**
   * Store a cache entry for the given cache key. When this is called, the entry
   * may still be pending, i.e. its value stream may still be written to. So it
   * needs to be awaited first. If a `get` for the same cache key is called,
   * before the pending entry is complete, the cache handler must wait for the
   * `set` operation to finish, before returning the entry, instead of returning
   * undefined.
   */
  set(cacheKey: string, pendingEntry: Promise<CacheEntry>): Promise<void>

  /**
   * This function may be called periodically, but always before starting a new
   * request. If applicable, it should communicate with the tags service to
   * refresh the local tags manifest accordingly.
   */
  refreshTags(): Promise<void>

  /**
   * This function is called for each set of soft tags that are relevant at the
   * start of a request. The result is the maximum timestamp of a revalidate
   * event for the tags. Returns `0` if none of the tags were ever revalidated.
   * Returns `Infinity` if the soft tags are supposed to be passed into the
   * `get` method instead to be checked for expiration.
   */
  getExpiration(tags: string[]): Promise<Timestamp>

  /**
   * This function is called when tags are revalidated/expired. If applicable,
   * it should update the tags manifest accordingly.
   */
  updateTags(tags: string[], durations?: { expire?: number }): Promise<void>
}

export interface CacheEntry {
  /**
   * The ReadableStream can error and only have partial data so any cache
   * handlers need to handle this case and decide to keep the partial cache
   * around or not.
   */
  value: ReadableStream<Uint8Array>

  /**
   * The tags configured for the entry excluding soft tags
   */
  tags: string[]

  /**
   * This is for the client, not used to calculate cache entry expiration
   * [duration in seconds]
   */
  stale: number

  /**
   * When the cache entry was created [timestamp in milliseconds]
   */
  timestamp: Timestamp

  /**
   * How long the entry is allowed to be used (should be longer than revalidate)
   * [duration in seconds]
   */
  expire: number

  /**
   * How long until the entry should be revalidated [duration in seconds]
   */
  revalidate: number
}

// cache-handler.ts
import type {
  CacheHandler,
  CacheEntry,
} from "next/dist/server/lib/cache-handlers/types";

export default class RedisCacheHandler implements CacheHandler {
  async get(key: string, softTags: string[]) {
    // 从 Redis 读 entry，检查 softTags
    return undefined;
  }
  async set(key: string, pendingEntry: Promise<CacheEntry>) {
    const entry = await pendingEntry;
    // 把 entry.value 流读完写到 Redis
  }
  async refreshTags() {
    /* ... */
  }
  async getExpiration(tags: string[]) {
    return 0;
  }
  async updateTags(tags: string[]) {
    /* ... */
  }
}

// next.config.js
module.exports = {
  experimental: {
    cacheHandler: require.resolve("./cache-handler.ts"),
  },
};

// app/admin/products/[id]/edit/page.tsx
"use server";

export async function updateProduct(id: string, data: FormData) {
  await db.product.update({ where: { id }, data: parse(data) });

  // 失效 detail 与 list
  revalidateTag(`product:${id}`);
  revalidateTag("product:list");

  // 也可以按路径
  revalidatePath("/admin/products");
}

// 1. 列表页：fetch + tag
async function getProducts() {
  "use cache";
  cacheLife("hours");
  cacheTag("product:list");

  const res = await fetch("https://api.example.com/products", {
    next: { revalidate: 3600, tags: ["product:list"] },
  });
  return res.json() as Promise<Product[]>;
}

// 2. 详情页：fetch + per-id tag
async function getProduct(id: string) {
  const res = await fetch(`https://api.example.com/products/${id}`, {
    next: { revalidate: 60, tags: [`product:${id}`, "product:list"] },
  });
  return res.json() as Promise<Product>;
}

// 3. ORM 调用：unstable_cache
const getProductCount = unstable_cache(
  async () => db.product.count(),
  ["getProductCount"],
  { revalidate: 300, tags: ["product:list"] },
);

// 4. server action 修改商品
async function deleteProduct(id: string) {
  "use server";
  await db.product.delete({ where: { id } });
  revalidateTag(`product:${id}`);
  revalidateTag("product:list");
}

// 错的：cookies() 在 unstable_cache 里抛错
const getUserData = unstable_cache(async () => {
  const c = cookies(); // throws
});

// 对的：用户 ID 当 keyParts
const getUserData = unstable_cache(
  async (userId: string) => fetchUserData(userId),
  ["getUserData"],
  { revalidate: 60 },
);

cd learning/nextjs-40-lectures/fixtures/lecture-11
pnpm install --ignore-workspace
pnpm dev
# 浏览器打开 http://localhost:3011/