XIFty for Node.js

@xifty/xifty is the official Node.js package for XIFty.

It gives Node applications a typed, native bridge into XIFty’s metadata engine so you can inspect files and extract metadata without shelling out to external tools.

Install

npm install @xifty/xifty

What It Does

XIFty is built around four views of metadata:

• raw: direct extracted metadata values
• interpreted: decoded values with namespace meaning
• normalized: stable cross-format fields for application use
• report: issues and conflicts surfaced honestly

This package exposes the same model directly in Node.

Quick Example

const xifty = require("@xifty/xifty");

const result = xifty.extract("photo.jpg", { view: "normalized" });

console.log(result.input.detected_format);
console.log(result.normalized.fields);

Typical normalized use:

const fields = Object.fromEntries(
  result.normalized.fields.map((field) => [field.field, field.value.value]),
);

console.log(fields["device.make"]);
console.log(fields["device.model"]);
console.log(fields["captured_at"]);

API

xifty.version(): string

Returns the XIFty core version reported by the native library.

xifty.packageVersion(): string

Returns the npm package version.

xifty.probe(path: string): XiftyEnvelope

Detects the input format and returns a lightweight envelope describing the file.

Example:

const probe = xifty.probe("image.jpg");
console.log(probe.input);

xifty.extract(path: string, options?): XiftyEnvelope

Extracts metadata for the input file.

Supported view values:

• "full"
• "raw"
• "interpreted"
• "normalized"
• "report"

Example:

const normalized = xifty.extract("image.jpg", { view: "normalized" });
const report = xifty.extract("image.jpg", { view: "report" });

Numeric view selection is also supported for low-level consumers, but named views are the intended public API.

Output Shape

Every call returns a JSON-like envelope with the same top-level structure:

{
  schema_version,
  input,
  raw,
  interpreted,
  normalized,
  report
}

That shape is intentionally close to the core CLI and C ABI so behavior stays predictable across the XIFty ecosystem.

TypeScript

The public wrapper is written in TypeScript and ships declaration files.

Example:

import { extract } from "@xifty/xifty";

const result = extract("image.jpg", { view: "normalized" });

Why Use It

Use this package when you want:

• a native Node interface instead of shelling out to CLI tools
• stable normalized fields for app logic
• access to raw and interpreted metadata when provenance matters
• explicit issue/conflict reporting instead of silent lossy parsing

Common application fits:

• photo-library ingestion
• media indexing pipelines
• upload-time metadata extraction
• back-office asset processing

AWS Lambda

@xifty/xifty is the recommended XIFty runtime for AWS Lambda today.

The published package currently targets:

• linux-x64
• macos-arm64

That means the package is ready for nodejs22.x Lambda on x86_64, local Apple Silicon development, and common Linux server/CI environments.

For the first-party Lambda adoption path, start from:

• the core repo Lambda guide: docs/adoption/AWS_LAMBDA_NODE.md
• the checked-in SAM example: examples/aws-sam-node

Supported Platforms

Current published-package target:

• macos-arm64
• linux-x64

linux-x64 is the priority Linux target because it covers AWS Lambda nodejs22.x, most CI runners, and most general Linux servers.

Not supported right now:

• macos-x64
• windows-*
• linux-arm64
• other Linux architectures

If you install the package on an unsupported platform, it fails with a clear native-build error instead of silently pretending support.

Design Notes

• native seam: xifty-ffi
• Node bridge: node-addon-api
• package loader: node-gyp-build
• public surface: TypeScript + generated .d.ts

Those are implementation details, but they matter for reliability: this package is a thin wrapper over the same XIFty core used elsewhere, not a separate reimplementation.

Local Development

npm install
npm test
npm run coverage
node examples/basic_usage.js
node examples/gallery_ingest.js

Maintainer Notes

GitHub Actions no longer publish this package. The current release path is local maintainer publish from an authenticated npm CLI session.

Maintainer builds no longer assume a sibling ../XIFty checkout. The build scripts resolve XIFty core in this order:

1. XIFTY_CORE_DIR if you explicitly point at a local checkout
2. a cached checkout of https://github.com/XIFtySense/XIFty.git at main

You can override the cached source with:

• XIFTY_CORE_REPO
• XIFTY_CORE_REF
• XIFTY_CORE_CACHE_DIR

Useful commands:

npm run core:prepare
npm run verify:package
npm run verify:tarball
npm run build:prebuilds
npm run verify:linux-x64
npm run publish:local

The local publish path now assembles a release bundle with:

• the host macos-arm64 prebuild when run on Apple Silicon macOS
• a Lambda-compatible linux-x64 prebuild built in an Amazon Linux 2023 container

That means manual publish from a supported maintainer Mac produces a package that is ready for both local macOS use and AWS Lambda / Linux server use.

For release-sensitive local verification against a real fixture, point the packed-tarball smoke test at the file and require the fields you care about. Example:

XIFTY_SMOKE_FIXTURE=/Users/k/Projects/XIFty/fixtures/local/C0242.MP4 \
XIFTY_SMOKE_FIELDS=video.bitrate,audio.sample_rate \
XIFTY_SMOKE_NONZERO_FIELDS=video.bitrate,audio.sample_rate \
npm run verify:tarball