@photostax/core 0.1.0

package/README.md

@@ -0,0 +1,158 @@
+# @photostax/core
+
+**Node.js binding for the photostax library — access Epson FastFoto repositories from TypeScript/JavaScript.**
+
+[![npm](https://img.shields.io/npm/v/@photostax/core.svg)](https://www.npmjs.com/package/@photostax/core)
+[![License](https://img.shields.io/badge/license-MIT%20OR%20Apache--2.0-blue)](../../LICENSE-MIT)
+
+## Overview
+
+Epson FastFoto scanners produce multiple files per scanned photo:
+
+| File Pattern | Description |
+|--------------|-------------|
+| `<name>.jpg` or `<name>.tif` | Original front scan |
+| `<name>_a.jpg` or `<name>_a.tif` | Enhanced version (color-corrected) |
+| `<name>_b.jpg` or `<name>_b.tif` | Back of the photo |
+
+This library groups these files into `PhotoStack` objects and provides access to their metadata from EXIF, XMP, and a sidecar database.
+
+## Installation
+
+```bash
+npm install @photostax/core
+```
+
+## Quick Start
+
+```typescript
+import { PhotostaxRepository } from '@photostax/core';
+
+// Open a directory containing FastFoto scans
+const repo = new PhotostaxRepository('/path/to/photos');
+
+// Scan for all photo stacks
+const stacks = repo.scan();
+
+for (const stack of stacks) {
+  console.log(`Photo: ${stack.id}`);
+  console.log(`  Original: ${stack.original}`);
+  console.log(`  Enhanced: ${stack.enhanced}`);
+  console.log(`  Back: ${stack.back}`);
+  console.log(`  EXIF Make: ${stack.metadata.exifTags['Make']}`);
+}
+```
+
+## API Overview
+
+### PhotostaxRepository
+
+The main class for accessing photo stacks.
+
+| Method | Description |
+|--------|-------------|
+| `scan()` | Discover all photo stacks in the repository |
+| `getStack(id)` | Get a specific stack by ID |
+| `readImage(path)` | Read raw image bytes as Buffer |
+| `writeMetadata(id, metadata)` | Write metadata to a stack |
+| `search(query)` | Find stacks matching a query |
+
+### PhotoStack
+
+```typescript
+interface PhotoStack {
+  id: string;                  // Base filename identifier
+  original: string | null;     // Path to original scan
+  enhanced: string | null;     // Path to enhanced scan
+  back: string | null;         // Path to back scan
+  metadata: Metadata;
+}
+```
+
+### Metadata
+
+```typescript
+interface Metadata {
+  exifTags: Record<string, string>;    // EXIF tags from image
+  xmpTags: Record<string, string>;     // XMP metadata
+  customTags: Record<string, unknown>; // Custom JSON metadata
+}
+```
+
+### SearchQuery
+
+```typescript
+interface SearchQuery {
+  text?: string;                       // Free-text search
+  exifFilters?: KeyValueFilter[];      // EXIF tag filters
+  customFilters?: KeyValueFilter[];    // Custom tag filters
+  hasBack?: boolean;                   // Filter by back scan presence
+  hasEnhanced?: boolean;               // Filter by enhanced scan presence
+}
+```
+
+### Utility Functions
+
+| Function | Description |
+|----------|-------------|
+| `isNativeAvailable()` | Check if native addon loaded successfully |
+| `getNativeLoadError()` | Get error if native addon failed to load |
+
+## Building from Source
+
+### Prerequisites
+
+- [Rust toolchain](https://rustup.rs/) (1.70+)
+- [Node.js 18+](https://nodejs.org/) with npm
+- Python 3.x (for node-gyp)
+- C++ compiler (Visual Studio Build Tools on Windows, GCC/Clang on Unix)
+
+### Build Steps
+
+```bash
+# Clone the repository
+git clone https://github.com/JeromySt/photostax.git
+cd photostax/bindings/typescript
+
+# Install dependencies
+npm install
+
+# Build the native addon
+npm run build
+
+# Run tests
+npm test
+```
+
+### Development Build
+
+For faster iteration during development:
+
+```bash
+npm run build:debug
+```
+
+## Supported Platforms
+
+Pre-built binaries are published for:
+
+| Platform | Architectures |
+|----------|---------------|
+| Windows | x64, arm64 |
+| macOS | x64, arm64 |
+| Linux | x64, arm64, musl |
+
+## File Format Support
+
+| Format | Extensions | EXIF | XMP |
+|--------|------------|------|-----|
+| JPEG | `.jpg`, `.jpeg` | ✓ | Embedded |
+| TIFF | `.tif`, `.tiff` | ✓ | Embedded or sidecar |
+
+## License
+
+Licensed under either of [Apache License, Version 2.0](../../LICENSE-APACHE) or [MIT license](../../LICENSE-MIT) at your option.
+
+---
+
+[← Back to main README](../../README.md) | [FFI Documentation](../../ffi/README.md)

package/index.d.ts

@@ -0,0 +1,131 @@
+/* tslint:disable */
+/* eslint-disable */
+
+/* auto-generated by NAPI-RS */
+
+/**
+ * Metadata associated with a photo stack.
+ *
+ * Combines EXIF tags (from image files), XMP tags (embedded or sidecar),
+ * and custom tags (from the sidecar database) into a unified view.
+ */
+export interface JsMetadata {
+  /** Standard EXIF tags from the image file (Make, Model, DateTime, etc.) */
+  exifTags: Record<string, string>
+  /** XMP/Dublin Core metadata tags */
+  xmpTags: Record<string, string>
+  /** Custom application metadata stored in the sidecar database */
+  customTags: Record<string, any>
+}
+/**
+ * A unified representation of a single scanned photo from an Epson FastFoto scanner.
+ *
+ * Groups the original scan, enhanced version, and back-of-photo image into
+ * a single logical unit with associated metadata.
+ */
+export interface JsPhotoStack {
+  /** Unique identifier derived from the base filename */
+  id: string
+  /** Path to the original front scan (may be null) */
+  original?: string
+  /** Path to the enhanced/color-corrected scan (may be null) */
+  enhanced?: string
+  /** Path to the back-of-photo scan (may be null) */
+  back?: string
+  /** Combined metadata from all sources */
+  metadata: JsMetadata
+}
+/** A key-value pair for search filters. */
+export interface JsKeyValue {
+  /** The tag name to filter on */
+  key: string
+  /** The value substring to search for */
+  value: string
+}
+/**
+ * Query parameters for searching photo stacks.
+ *
+ * All filters use AND logic - a stack must match all specified criteria.
+ */
+export interface JsSearchQuery {
+  /** Free-text search across ID and all metadata */
+  text?: string
+  /** EXIF tag filters (all must match) */
+  exifFilters?: Array<JsKeyValue>
+  /** Custom tag filters (all must match) */
+  customFilters?: Array<JsKeyValue>
+  /** Filter by presence of back scan */
+  hasBack?: boolean
+  /** Filter by presence of enhanced scan */
+  hasEnhanced?: boolean
+}
+/** Options for creating a PhotostaxRepository. */
+export interface RepositoryOptions {
+  /**
+   * Whether to recurse into subdirectories (default: false).
+   *
+   * Set to `true` when the photo library uses FastFoto's folder-based
+   * organisation (e.g. `1984_Mexico/`, `SteveJones/`).
+   */
+  recursive?: boolean
+}
+/**
+ * A repository for accessing Epson FastFoto photo stacks from a local directory.
+ *
+ * Provides methods to scan, retrieve, and modify photo stacks and their metadata.
+ */
+export declare class PhotostaxRepository {
+  /**
+   * Create a new repository rooted at the given directory path.
+   *
+   * @param directoryPath - Path to the directory containing FastFoto photo files
+   * @param options - Optional configuration (e.g. `{ recursive: true }`)
+   * @throws Error if the path is invalid
+   */
+  constructor(directoryPath: string, options?: RepositoryOptions | undefined | null)
+  /**
+   * Scan the repository and return all discovered photo stacks.
+   *
+   * Groups files by FastFoto naming convention and enriches each stack
+   * with EXIF, XMP, and sidecar metadata.
+   *
+   * @returns Array of photo stacks found in the repository
+   * @throws Error if the directory cannot be accessed
+   */
+  scan(): Array<JsPhotoStack>
+  /**
+   * Retrieve a single photo stack by its ID.
+   *
+   * @param id - The stack identifier (base filename without suffix)
+   * @returns The photo stack with the given ID
+   * @throws Error if the stack is not found or cannot be accessed
+   */
+  getStack(id: string): JsPhotoStack
+  /**
+   * Read the raw bytes of an image file.
+   *
+   * @param path - Path to the image file (from a PhotoStack)
+   * @returns Buffer containing the image bytes
+   * @throws Error if the file cannot be read
+   */
+  readImage(path: string): Buffer
+  /**
+   * Write metadata tags to a photo stack.
+   *
+   * XMP tags are written to the image file (or sidecar for TIFF).
+   * Custom and EXIF tags are stored in the sidecar database.
+   *
+   * @param stackId - The ID of the stack to update
+   * @param metadata - The metadata to write
+   * @throws Error if the stack is not found or metadata cannot be written
+   */
+  writeMetadata(stackId: string, metadata: JsMetadata): void
+  /**
+   * Search for photo stacks matching the given query.
+   *
+   * @param query - Search criteria (all filters are AND'd together)
+   * @returns Array of matching photo stacks
+   * @throws Error if the repository cannot be scanned
+   */
+  search(query: JsSearchQuery): Array<JsPhotoStack>
+}

package/index.js

@@ -0,0 +1,315 @@
+/* tslint:disable */
+/* eslint-disable */
+/* prettier-ignore */
+
+/* auto-generated by NAPI-RS */
+
+const { existsSync, readFileSync } = require('fs')
+const { join } = require('path')
+
+const { platform, arch } = process
+
+let nativeBinding = null
+let localFileExisted = false
+let loadError = null
+
+function isMusl() {
+  // For Node 10
+  if (!process.report || typeof process.report.getReport !== 'function') {
+    try {
+      const lddPath = require('child_process').execSync('which ldd').toString().trim()
+      return readFileSync(lddPath, 'utf8').includes('musl')
+    } catch (e) {
+      return true
+    }
+  } else {
+    const { glibcVersionRuntime } = process.report.getReport().header
+    return !glibcVersionRuntime
+  }
+}
+
+switch (platform) {
+  case 'android':
+    switch (arch) {
+      case 'arm64':
+        localFileExisted = existsSync(join(__dirname, 'photostax.android-arm64.node'))
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./photostax.android-arm64.node')
+          } else {
+            nativeBinding = require('@photostax/core-android-arm64')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      case 'arm':
+        localFileExisted = existsSync(join(__dirname, 'photostax.android-arm-eabi.node'))
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./photostax.android-arm-eabi.node')
+          } else {
+            nativeBinding = require('@photostax/core-android-arm-eabi')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      default:
+        throw new Error(`Unsupported architecture on Android ${arch}`)
+    }
+    break
+  case 'win32':
+    switch (arch) {
+      case 'x64':
+        localFileExisted = existsSync(
+          join(__dirname, 'photostax.win32-x64-msvc.node')
+        )
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./photostax.win32-x64-msvc.node')
+          } else {
+            nativeBinding = require('@photostax/core-win32-x64-msvc')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      case 'ia32':
+        localFileExisted = existsSync(
+          join(__dirname, 'photostax.win32-ia32-msvc.node')
+        )
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./photostax.win32-ia32-msvc.node')
+          } else {
+            nativeBinding = require('@photostax/core-win32-ia32-msvc')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      case 'arm64':
+        localFileExisted = existsSync(
+          join(__dirname, 'photostax.win32-arm64-msvc.node')
+        )
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./photostax.win32-arm64-msvc.node')
+          } else {
+            nativeBinding = require('@photostax/core-win32-arm64-msvc')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      default:
+        throw new Error(`Unsupported architecture on Windows: ${arch}`)
+    }
+    break
+  case 'darwin':
+    localFileExisted = existsSync(join(__dirname, 'photostax.darwin-universal.node'))
+    try {
+      if (localFileExisted) {
+        nativeBinding = require('./photostax.darwin-universal.node')
+      } else {
+        nativeBinding = require('@photostax/core-darwin-universal')
+      }
+      break
+    } catch {}
+    switch (arch) {
+      case 'x64':
+        localFileExisted = existsSync(join(__dirname, 'photostax.darwin-x64.node'))
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./photostax.darwin-x64.node')
+          } else {
+            nativeBinding = require('@photostax/core-darwin-x64')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      case 'arm64':
+        localFileExisted = existsSync(
+          join(__dirname, 'photostax.darwin-arm64.node')
+        )
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./photostax.darwin-arm64.node')
+          } else {
+            nativeBinding = require('@photostax/core-darwin-arm64')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      default:
+        throw new Error(`Unsupported architecture on macOS: ${arch}`)
+    }
+    break
+  case 'freebsd':
+    if (arch !== 'x64') {
+      throw new Error(`Unsupported architecture on FreeBSD: ${arch}`)
+    }
+    localFileExisted = existsSync(join(__dirname, 'photostax.freebsd-x64.node'))
+    try {
+      if (localFileExisted) {
+        nativeBinding = require('./photostax.freebsd-x64.node')
+      } else {
+        nativeBinding = require('@photostax/core-freebsd-x64')
+      }
+    } catch (e) {
+      loadError = e
+    }
+    break
+  case 'linux':
+    switch (arch) {
+      case 'x64':
+        if (isMusl()) {
+          localFileExisted = existsSync(
+            join(__dirname, 'photostax.linux-x64-musl.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./photostax.linux-x64-musl.node')
+            } else {
+              nativeBinding = require('@photostax/core-linux-x64-musl')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        } else {
+          localFileExisted = existsSync(
+            join(__dirname, 'photostax.linux-x64-gnu.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./photostax.linux-x64-gnu.node')
+            } else {
+              nativeBinding = require('@photostax/core-linux-x64-gnu')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        }
+        break
+      case 'arm64':
+        if (isMusl()) {
+          localFileExisted = existsSync(
+            join(__dirname, 'photostax.linux-arm64-musl.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./photostax.linux-arm64-musl.node')
+            } else {
+              nativeBinding = require('@photostax/core-linux-arm64-musl')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        } else {
+          localFileExisted = existsSync(
+            join(__dirname, 'photostax.linux-arm64-gnu.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./photostax.linux-arm64-gnu.node')
+            } else {
+              nativeBinding = require('@photostax/core-linux-arm64-gnu')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        }
+        break
+      case 'arm':
+        if (isMusl()) {
+          localFileExisted = existsSync(
+            join(__dirname, 'photostax.linux-arm-musleabihf.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./photostax.linux-arm-musleabihf.node')
+            } else {
+              nativeBinding = require('@photostax/core-linux-arm-musleabihf')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        } else {
+          localFileExisted = existsSync(
+            join(__dirname, 'photostax.linux-arm-gnueabihf.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./photostax.linux-arm-gnueabihf.node')
+            } else {
+              nativeBinding = require('@photostax/core-linux-arm-gnueabihf')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        }
+        break
+      case 'riscv64':
+        if (isMusl()) {
+          localFileExisted = existsSync(
+            join(__dirname, 'photostax.linux-riscv64-musl.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./photostax.linux-riscv64-musl.node')
+            } else {
+              nativeBinding = require('@photostax/core-linux-riscv64-musl')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        } else {
+          localFileExisted = existsSync(
+            join(__dirname, 'photostax.linux-riscv64-gnu.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./photostax.linux-riscv64-gnu.node')
+            } else {
+              nativeBinding = require('@photostax/core-linux-riscv64-gnu')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        }
+        break
+      case 's390x':
+        localFileExisted = existsSync(
+          join(__dirname, 'photostax.linux-s390x-gnu.node')
+        )
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./photostax.linux-s390x-gnu.node')
+          } else {
+            nativeBinding = require('@photostax/core-linux-s390x-gnu')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      default:
+        throw new Error(`Unsupported architecture on Linux: ${arch}`)
+    }
+    break
+  default:
+    throw new Error(`Unsupported OS: ${platform}, architecture: ${arch}`)
+}
+
+if (!nativeBinding) {
+  if (loadError) {
+    throw loadError
+  }
+  throw new Error(`Failed to load native binding`)
+}
+
+const { PhotostaxRepository } = nativeBinding
+
+module.exports.PhotostaxRepository = PhotostaxRepository

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@photostax/core",
+  "version": "0.1.0",
+  "description": "Unified photo stack library for Epson FastFoto repositories - Node.js binding",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "napi": {
+    "name": "photostax",
+    "triples": {
+      "defaults": true
+    }
+  },
+  "license": "MIT OR Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/JeromySt/photostax"
+  },
+  "scripts": {
+    "build": "napi build --platform --release",
+    "build:debug": "napi build --platform",
+    "test": "jest",
+    "prepublishOnly": "napi prepublish -t npm"
+  },
+  "devDependencies": {
+    "@napi-rs/cli": "^2.0.0",
+    "@types/jest": "^29.0.0",
+    "@types/node": "^20.0.0",
+    "jest": "^29.0.0",
+    "ts-jest": "^29.0.0",
+    "typescript": "^5.0.0"
+  },
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "*.node"
+  ],
+  "keywords": [
+    "epson",
+    "fastfoto",
+    "photo",
+    "scanner",
+    "exif",
+    "metadata",
+    "tiff",
+    "jpeg"
+  ],
+  "optionalDependencies": {
+    "@photostax/core-win32-x64-msvc": "0.1.0",
+    "@photostax/core-darwin-x64": "0.1.0",
+    "@photostax/core-linux-x64-gnu": "0.1.0"
+  }
+}