@itxtech/fdnext-core provides platform-independent parsing with no runtime network dependency. It includes DecodePack JSON rules, a compiler, default resources, and a shared runtime.
This guide covers embedding fdnext in Node.js, browsers, and servers. HTTP API owns routes, query parameters, response structures, and CORS behavior.
pnpm add @itxtech/fdnext-coreUse the installed CLI with pnpm exec fdnext part decode MT29F64G08CBABA --lang eng. See CLI usage for output formats and options. Rule diagnostics are covered in DecodePack maintenance tools.
| Entry point | Purpose |
|---|---|
@itxtech/fdnext-core |
Engine, input/output types, capabilities, and JSON schemas |
@itxtech/fdnext-core/runtime |
HTTP dispatch/fetch, CORS, and external link providers |
@itxtech/fdnext-core/node-http |
Node request/response to Fetch API bridge |
@itxtech/fdnext-core/cli |
CLI integration |
@itxtech/fdnext-core/decodepack |
Rule compilation, checks, explanation, default packs, and shared tables |
import { createEngine } from "@itxtech/fdnext-core";
// Create once at startup and reuse for all requests.
const engine = createEngine();
console.log(engine.decodePart({ query: "MT29F64G08CBABA", lang: "eng" }));
console.log(engine.decodeIdentifier({ query: "2C64444BA900", lang: "eng" }));Keep one long-lived FdnextEngine per process, application, Worker isolate, or browser runtime. Do not call createEngine() for every HTTP request, decode, or search.
To replace default resources, for example for a data refresh, load your own FdnextResourceBundle (loadResourcesFromYourStore below is an application-provided loader):
import { createEngine, type FdnextResourceBundle } from "@itxtech/fdnext-core";
const resources: FdnextResourceBundle = await loadResourcesFromYourStore();
const engine = createEngine({ resources });Use PreparedCatalog only when multiple engines with genuinely different configurations must share immutable resource parsing and search indexes:
import { createEngine, prepareCatalog } from "@itxtech/fdnext-core";
const catalog = prepareCatalog(resources);
const primaryEngine = createEngine({ catalog });
const chineseEngine = createEngine({ catalog, fallbackLang: "chs" });prepareCatalog() caches by resource object identity. Treat resources as immutable after preparation. It is an optimization for multiple configurations, not a reason to create engines per request.
The core supports operation-level processors:
const engine = createEngine({
processors: [
{
beforeOperation(ctx) {
if (ctx.operation === "part.decode") {
console.log(ctx.query);
}
},
afterOperation(ctx, result) {
return result;
}
}
]
});
const response = engine.decodePart({ query: "MT29F64G08CBABA", lang: "eng" });Common SDK methods:
engine.decodePart(input)/engine.searchParts(input)engine.decodeIdentifier(input)/engine.searchIdentifiers(input)engine.getCapabilities()
@itxtech/fdnext-core/runtime provides shared dispatch, HTTP routing, and external link providers. Node.js and Workers adapters call this runtime rather than maintaining separate routes.
import { createRuntime } from "@itxtech/fdnext-core/runtime";
const runtime = createRuntime({
externalLinkProviders: [
{
id: "docs",
resolveLinks(ctx) {
if (ctx.facts.vendor === "micron") {
return [{
id: "micron.home",
label: "Micron",
url: "https://www.micron.com/",
category: "vnd",
priority: 10
}];
}
return [];
}
}
]
});
const response = await runtime.dispatch({
operation: "part.decode",
input: { query: "MT29F64G08CBABA", lang: "eng" },
meta: { adapter: "custom" }
});External links appear in result.links or search items[].links:
interface ExternalLink {
id: string;
label: string;
url: string;
category?: "vnd" | "ds" | "mkt" | "ref" | "tl" | "com" | "ads";
image?: string;
hint?: string;
fieldKey?: string;
priority?: number;
}The runtime drops links without id/label/url, permits only http:, https:, and mailto: URLs, and sorts by priority.
The fdnext executable ships with @itxtech/fdnext-core; no separate CLI package is needed. In a repository checkout, use pnpm cli instead of pnpm exec fdnext.
pnpm exec fdnext --help
pnpm exec fdnext --version
pnpm exec fdnext part decode MT62F1G64D4EK-023 --lang eng
pnpm exec fdnext part search MT62 --lang eng --limit 5
pnpm exec fdnext id decode 2C64444BA900 --lang eng --controller-group if:sata
pnpm exec fdnext id search 2C64 --limit 5 --id-scheme nand.flash_id
pnpm exec fdnext capabilities --lang eng --format json
pnpm exec fdnext decodepack explain part BWCA2KZC-64G --format textUse --help at any level, such as fdnext part --help or fdnext part decode --help. No arguments show help successfully. --version (or -V) prints only the version and must be used alone. Help and version do not load the engine resources.
| Output option | Behavior |
|---|---|
--format auto (default) |
Text when stdout is a terminal; JSON otherwise |
--format text |
Plain text, including when redirected or captured by an LLM tool |
--format json |
Complete existing JSON result, without a banner or ANSI formatting |
pnpm exec fdnext part decode MT62F1G64D4EK-023 --lang eng --format text > result.txt
pnpm exec fdnext part search MT62 --limit 5 --format json > result.jsonText output preserves field labels, keys, units, raw values, candidates, relations, warnings, and links without truncating lists. It suppresses duplicate summary projections and UI importance hints. Section labels are English; --lang selects the engine's field translations (bundled languages: eng, chs, with the engine's normal fallback behavior). Text layout may evolve; use JSON and its versioned result schema for machine parsing.
stdout contains the requested result. The project banner appears in help, and on stderr for text commands only when both stdout and stderr are terminals. --no-banner suppresses it. There is no automatic banner for redirected results, explicit JSON, or embedded calls. A downstream reader closing its pipe early is handled without a stack trace.
| Exit code | Meaning |
|---|---|
0 |
Query completed, or help/version displayed |
1 |
Runtime failure, or decodepack check found rule errors |
2 |
Invalid CLI arguments; stderr identifies the problem and the relevant help command |
Query statuses such as not_found, ambiguous, unsupported, and invalid_input remain part of the result and do not change a completed query's exit code. Runtime errors go to stderr. A failed rule check still writes its findings to stdout.
Named options accept --name value or --name=value, before or after the command. Search limits must be positive safe integers; omission returns all matches. --controller-group applies only to decode commands and supports repeated or comma-separated group IDs; all must stand alone. --spec-id applies to decodepack explain part. Use -- before a query starting with -.
Existing positional options remain supported: [lang] for part decode and capabilities, [lang] [limit] for part search, [lang] [idScheme] for ID decode, [lang] [limit] [idScheme] for ID search, and [specId] / [idScheme] for DecodePack explanations. Supplying the same option by name and position is an error. Unknown options, unsupported options, extra arguments, invalid schemes/groups, and malformed limits now fail instead of being ignored.
For in-process calls, reuse an engine and optionally capture output:
import { createEngine } from "@itxtech/fdnext-core";
import { runCliCommand } from "@itxtech/fdnext-core/cli";
const engine = createEngine();
const code = runCliCommand(["part", "decode", "MT62F1G64D4EK-023", "--lang", "eng"], {
engine,
format: "text",
stdout: (text) => process.stdout.write(text),
stderr: (text) => process.stderr.write(text)
});runCliCommand() remains synchronous, defaults to JSON independently of the host terminal, and returns an exit code without exiting the process. An explicit --format overrides the option. The executable supplies terminal state; embedding callers need not. Importing /cli has no command-execution side effects. Runtime failures return 1 with a diagnostic instead of throwing.
fdnext.result.v2 abbreviates link categories: vendor → vnd, datasheet → ds, marketplace → mkt, reference → ref, tool → tl, and community → com. It adds ads for advertising, self-promotion, and service referrals. ds/ref describe reference uses; other resources are not automatically technical evidence. Category and hint are independent. Keep advertising visibly labeled and exclude it from general result copying; links may be exported separately. Old category names are outside the v2 schema, so update providers and strict consumers together, not just display labels.
Successful PN/FID decodes include summary: { brief: FieldValue[], full: ResultBlock[] }. brief orders key fields by device type; full retains all parameter and component groups. Both preserve field keys, translations, units, and values. DRAM includes type, density, width, speed, and voltage. Managed NAND retains device and component capacities separately; MCP DRAM has its own dram block; 3D XPoint retains Deck semantics.
Summaries select only visible fields actually returned. They do not infer missing capacities, component counts, or supplies. full matches blocks; relations/warnings remain separate and are not replaced by summaries. Read marking and full PN identity from device and input.query. subtitle also includes DRAM speed/voltage, managed interfaces/protocols, and XPoint Deck information.
Bundle fdnext with Vite, Webpack, Rollup, or esbuild:
- Use
createEngine()and its decode/search/capabilities methods for local browser queries./runtimeis for HTTP adapters. - Create and reuse one engine at startup, not on each component render or query.
- Default FDB/MDB, translations, and PN search resources are embedded. No extra JSON download or hosting is required.
- Custom PN resource structures and deduplication are covered in Search resources (Chinese).
- Default PN and typed identifier decoders are included. Pass
decoders/identifierDecodersonly to select or replace rules. /decodepackprovides check/explain/compile tooling; ordinary frontend queries do not need it directly.- SDK
searchParts()/searchIdentifiers()withoutlimitreturn all matches for in-memory pagination. A positive integer enables top-K truncation. Default PN search includes prefix and substring matches. - HTTP search limits are defined in Common parameters.
- Add custom DecodePack fields to search with
createEngine({ partSearchProjection: ["fields.<key>"] }). Default search dependencies remain included.
The core npm package ships resources embedded in its bundle, without separate raw resources/*.json files. Use the default engine above.
Only host your own resource JSON when replacing the default databases or translations. Assemble these application-owned files into FdnextResourceBundle; the core npm package does not supply them separately. This example uses /fdnext-resources/:
import { createEngine } from "@itxtech/fdnext-core";
async function loadJson(path: string) {
const res = await fetch(path);
if (!res.ok) throw new Error(`${res.status} ${res.statusText}: ${path}`);
return res.json();
}
const [flashDatabase, packageMarkings, managedNandParts, dramParts, chs, eng] = await Promise.all([
loadJson("/fdnext-resources/fdb.json"),
loadJson("/fdnext-resources/mdb.json"),
loadJson("/fdnext-resources/managed-nand-pn.json"),
loadJson("/fdnext-resources/dram-pn.json"),
loadJson("/fdnext-resources/lang/chs.json"),
loadJson("/fdnext-resources/lang/eng.json")
]);
const engine = createEngine({
resources: {
partIndex: {
rawNand: flashDatabase,
managedNand: managedNandParts,
dram: dramParts
},
identifierIndex: {
nandFlash: flashDatabase
},
markingIndex: {
packageMarkings
},
vendorIndex: {},
translationIndex: { chs, eng }
}
});@itxtech/fdnext-server uses native node:http. It bridges Node requests/responses and the Fetch API through @itxtech/fdnext-core/node-http; the shared runtime handles routes.
pnpm install
pnpm server:devTo use an external resource directory:
pnpm -C packages/server dev -- --resources ./resourcesSupply the directory yourself; it is not included in npm packages. Required files are fdb.json, mdb.json, lang/chs.json, and lang/eng.json. Optional files are managed-nand-pn.json, dram-pn.json, and controller-groups.json.
Build and run the production entry:
pnpm -C packages/server build
pnpm server:startUse the root Dockerfile.
After building, use the root ecosystem.config.cjs:
pm2 start ecosystem.config.cjs
pm2 status
pm2 logs fdnext-serverpnpm add @itxtech/fdnext-server
pnpm exec fdnext-server --host 0.0.0.0 --port 8080| Option | Default | Meaning |
|---|---|---|
--host |
0.0.0.0 |
Bind address |
--port |
8080 |
Listening port |
--resources |
Embedded resources | Application-supplied resource directory |
import { createHttpServer } from "@itxtech/fdnext-server";
const app = createHttpServer({
host: "0.0.0.0",
port: 8080,
cors: { origins: ["https://app.example.com"] },
searchLimit: 300
});
await app.listen();
// app.server is a node:http Server; app.engine exposes SDK operations.Add resourceDir: "./resources" to replace embedded resources. Explicit cors / searchLimit override environment configuration; see HTTP API for variable semantics and HTTP behavior.
Standard bundles embed a short Git commitHash and the current UTC buildTime in ISO 8601 format with milliseconds (YYYY-MM-DDTHH:mm:ss.sssZ). CI and serverless builds can override these with FDNEXT_COMMIT_HASH and FDNEXT_BUILD_TIME. Time overrides are normalized to the same format; invalid values fail the build. Servers/CLIs run from source without injected metadata use process startup time in that format.
Both core and Worker adapter builds inject this metadata so a global-scope Date fallback does not record the Unix epoch as the build time.
Cloudflare Workers covers the Worker entry, Wrangler, and Dashboard configuration.