@chordsketch/node 0.2.0

package/index.d.ts

@@ -0,0 +1,72 @@
+// @chordsketch/node — TypeScript declarations.
+//
+// Mirrors the public API defined by `crates/napi/src/lib.rs` #[napi] items.
+// Keep in sync with the Rust source: every exported function and object
+// over there must have a matching declaration here.
+
+/**
+ * Rendering options accepted by the `*WithOptions` functions.
+ *
+ * Matches the `RenderOptions` struct in `crates/napi/src/lib.rs`.
+ */
+export interface RenderOptions {
+  /**
+   * Semitone transposition offset. Defaults to 0.
+   *
+   * Any integer is accepted, but values outside the i8 range (-128..=127)
+   * are clamped before the underlying renderer reduces modulo 12.
+   */
+  transpose?: number;
+
+  /**
+   * Configuration preset name (e.g. "guitar", "ukulele") or an inline
+   * RRJSON configuration string.
+   */
+  config?: string;
+}
+
+/**
+ * A single validation issue reported by `validate`.
+ */
+export interface ValidationError {
+  /** One-based line number of the issue within the input. */
+  line: number;
+  /** Column offset (byte) within the line, one-based. */
+  column: number;
+  /** Human-readable description of the issue. */
+  message: string;
+}
+
+/** Returns the version string baked into the compiled Rust crate. */
+export function version(): string;
+
+/** Renders the ChordPro source to plain text. */
+export function renderText(source: string): string;
+
+/**
+ * Renders the ChordPro source to plain text with rendering options applied.
+ */
+export function renderTextWithOptions(source: string, options: RenderOptions): string;
+
+/** Renders the ChordPro source to HTML. */
+export function renderHtml(source: string): string;
+
+/**
+ * Renders the ChordPro source to HTML with rendering options applied.
+ */
+export function renderHtmlWithOptions(source: string, options: RenderOptions): string;
+
+/** Renders the ChordPro source to a PDF document, returned as a Buffer. */
+export function renderPdf(source: string): Buffer;
+
+/**
+ * Renders the ChordPro source to a PDF document with rendering options
+ * applied.
+ */
+export function renderPdfWithOptions(source: string, options: RenderOptions): Buffer;
+
+/**
+ * Validates a ChordPro source document and returns a list of issues. An
+ * empty array indicates the document parses cleanly.
+ */
+export function validate(source: string): ValidationError[];

package/index.js

@@ -0,0 +1,88 @@
+// @chordsketch/node — platform resolver for the napi-rs native addon.
+//
+// Loads the right per-platform prebuilt binary package at runtime, matching
+// the napi-rs multi-package convention. The five platform packages declared
+// in `optionalDependencies` of package.json cover every target in the
+// `napi.targets` list of this package's manifest:
+//
+//   - @chordsketch/node-linux-x64-gnu       (linux x64)
+//   - @chordsketch/node-linux-arm64-gnu     (linux arm64)
+//   - @chordsketch/node-darwin-x64          (macOS x64)
+//   - @chordsketch/node-darwin-arm64        (macOS arm64 / Apple Silicon)
+//   - @chordsketch/node-win32-x64-msvc      (Windows x64)
+//
+// If you see "Unsupported platform" from this file, either the runtime
+// platform is not in the supported list (add a new target to napi.targets,
+// build + publish a prebuilt package, and extend this resolver) OR the
+// right optional dependency failed to install (check npm's error output
+// for the optional dep that was skipped).
+//
+// This file is committed deliberately rather than generated by `napi build`
+// so the publish job does not have to run the Rust build — it only needs
+// to move each platform's .node artifact into its platform subdirectory
+// under `npm/` before running `npm publish`. See docs/releasing.md for the
+// full flow.
+
+const { platform, arch } = process;
+
+let nativeBinding = null;
+let loadErrors = [];
+
+function tryLoad(pkg) {
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    return require(pkg);
+  } catch (err) {
+    loadErrors.push({ pkg, err });
+    return null;
+  }
+}
+
+switch (platform) {
+  case 'linux':
+    if (arch === 'x64') {
+      nativeBinding = tryLoad('@chordsketch/node-linux-x64-gnu');
+    } else if (arch === 'arm64') {
+      nativeBinding = tryLoad('@chordsketch/node-linux-arm64-gnu');
+    }
+    break;
+
+  case 'darwin':
+    if (arch === 'x64') {
+      nativeBinding = tryLoad('@chordsketch/node-darwin-x64');
+    } else if (arch === 'arm64') {
+      nativeBinding = tryLoad('@chordsketch/node-darwin-arm64');
+    }
+    break;
+
+  case 'win32':
+    if (arch === 'x64') {
+      nativeBinding = tryLoad('@chordsketch/node-win32-x64-msvc');
+    }
+    break;
+}
+
+if (!nativeBinding) {
+  if (loadErrors.length > 0) {
+    // A matching platform package exists in optionalDependencies but failed
+    // to load. Surface the first load error so the user sees the actual
+    // require() failure rather than a generic "unsupported platform".
+    const { pkg, err } = loadErrors[0];
+    const reason = err && err.message ? err.message : String(err);
+    throw new Error(
+      `Failed to load @chordsketch/node: native binding ${pkg} is installed ` +
+        `but could not be loaded (${reason}). This usually means the ` +
+        `optional dependency failed to install cleanly; try reinstalling ` +
+        `with \`npm install --force @chordsketch/node\`.`,
+    );
+  }
+  throw new Error(
+    `Unsupported platform: ${platform} ${arch}. ` +
+      `@chordsketch/node ships prebuilt binaries for linux/darwin (x64, arm64) ` +
+      `and win32 x64; other targets must build from source via ` +
+      `\`cargo build --release -p chordsketch-napi\`.`,
+  );
+}
+
+module.exports = nativeBinding;
+module.exports.default = nativeBinding;

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@chordsketch/node",
+  "version": "0.2.0",
+  "description": "Native Node.js addon for ChordPro parsing and rendering via napi-rs.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/koedame/chordsketch.git",
+    "directory": "crates/napi"
+  },
+  "homepage": "https://github.com/koedame/chordsketch",
+  "engines": {
+    "node": ">=15.12.0"
+  },
+  "keywords": [
+    "chordpro",
+    "music",
+    "chord",
+    "parser",
+    "lyrics",
+    "napi-rs",
+    "node-addon",
+    "n-api",
+    "native"
+  ],
+  "main": "index.js",
+  "types": "index.d.ts",
+  "files": [
+    "index.js",
+    "index.d.ts"
+  ],
+  "optionalDependencies": {
+    "@chordsketch/node-darwin-x64": "0.2.0",
+    "@chordsketch/node-darwin-arm64": "0.2.0",
+    "@chordsketch/node-linux-x64-gnu": "0.2.0",
+    "@chordsketch/node-linux-arm64-gnu": "0.2.0",
+    "@chordsketch/node-win32-x64-msvc": "0.2.0"
+  },
+  "napi": {
+    "binaryName": "chordsketch-napi",
+    "packageName": "@chordsketch/node",
+    "targets": [
+      "x86_64-apple-darwin",
+      "aarch64-apple-darwin",
+      "x86_64-unknown-linux-gnu",
+      "aarch64-unknown-linux-gnu",
+      "x86_64-pc-windows-msvc"
+    ]
+  },
+  "devDependencies": {
+    "@napi-rs/cli": "^3.4.0"
+  },
+  "scripts": {
+    "build": "napi build --release --manifest-path Cargo.toml",
+    "build:debug": "napi build --manifest-path Cargo.toml"
+  }
+}