deepseek-harness/packages/util/lazy-require/README.md

---

description: "Caller-relative lazy loading for CommonJS-compatible Host dependencies whose initialization is not needed during application startup."

kind: "package-library"

@deepseek-ai/dsh-lazy-require

English | 中文

Summary

dsh-lazy-require keeps a CommonJS-compatible Host dependency unloaded until its first real operation. Resolution remains relative to the consuming package, and one successful module value is reused for the rest of the process realm.

Table of Contents

• Use this package
• Understand the implementation
• Further Exploration
• Model Experience
• Known Limitations and Deferred Work
• Dev Note

---

Use this package

Pass the dependency's literal specifier and the caller's import.meta.url:

import { createLazyRequire } from '@deepseek-ai/dsh-lazy-require'

interface NativeModule { open(): void }
const requireNative = createLazyRequire<NativeModule>('native-package', import.meta.url)

Calling requireNative() loads the dependency once. A failed load is not cached.

---

Understand the implementation

Implementation internals — click to expand

The utility creates Node's `require` from the supplied caller URL and caches only a successful return value. The explicit caller URL preserves package-local dependency resolution after publication. ### Source map | File | Role | |---|---| | [`src/index.ts`](src/index.ts) | Caller-relative loader and successful-result cache |

---

Further Exploration

• Utility package map — adjacent shared primitives.
• NPM release sequences — published dependency classification and first-use loading policy.

---

Model Experience

None, as this Host utility registers no model-facing behavior.

KV Cache effect

None.

Known Limitations and Deferred Work

• CommonJS-compatible dependencies only — ESM-only packages require an asynchronous factory owned by their caller.
• WebWorker packaging needs an explicit request — the static packer does not discover dependencies named only in createLazyRequire() calls. A package used in a Preview image must keep the dependency reachable through a supported literal request until the packer recognizes this helper.

No runtime invariant companion is published because the loader holds no independently observable mutable relationship.

Dev Note

None.