@enslo/sd-metadata 1.3.0 → 1.4.1

package/README.ja.md

@@ -153,7 +153,7 @@ if (result.status === 'success') {
 > 本番環境では `@latest` の代わりに特定のバージョンを指定してください：
 >
 > ```text
-> https://cdn.jsdelivr.net/npm/@enslo/sd-metadata@1.3.0/dist/index.js
+> https://cdn.jsdelivr.net/npm/@enslo/sd-metadata@1.4.1/dist/index.js
 > ```
 
 ### 応用例
@@ -226,9 +226,9 @@ switch (result.status) {
 </details>
 
 <details>
-<summary>未対応メタデータの保持</summary>
+<summary>未対応メタデータの扱い</summary>
 
-未対応ツールのメタデータを含む画像を変換する際も、元のメタデータを保持できます：
+未対応ツールのメタデータを含む画像を扱う場合：
 
 ```typescript
 import { read, write } from '@enslo/sd-metadata';
@@ -236,12 +236,16 @@ import { read, write } from '@enslo/sd-metadata';
 const source = read(unknownImage);
 // source.status === 'unrecognized'
 
-// 元のメタデータチャンク/セグメントをそのまま保持
-const result = write(targetImage, source, { force: true });
-
+// ターゲット画像に書き込み
+// - 同じフォーマット（例：PNG → PNG）：メタデータそのまま保持
+// - 異なるフォーマット（例：PNG → JPEG）：warning付きでメタデータ削除
+const result = write(targetImage, source);
 if (result.ok) {
-  // 元のメタデータが新しい画像に保持される
-  console.log('メタデータの保持に成功しました');
+  saveFile('output.png', result.value);
+  if (result.warning) {
+    // クロスフォーマット変換によりメタデータが削除された場合
+    console.warn('メタデータが削除されました:', result.warning.reason);
+  }
 }
 ```
 
@@ -346,7 +350,7 @@ if (result.status === 'success') {
 - `{ status: 'invalid', message? }` - 破損または非対応の画像フォーマット
   - `message`: オプションのエラー説明
 
-### `write(data: Uint8Array, metadata: ParseResult, options?: WriteOptions): WriteResult`
+### `write(data: Uint8Array, metadata: ParseResult): WriteResult`
 
 画像ファイルにメタデータを書き込みます。
 
@@ -355,13 +359,12 @@ if (result.status === 'success') {
 - `data` - ターゲット画像ファイルデータ（PNG、JPEG、またはWebP）
 - `metadata` - `read()` から得られた `ParseResult`
   - `status: 'success'` または `'empty'` - 直接書き込み可能
-  - `status: 'unrecognized'` - `force: true` オプションが必要
-- `options` - オプション設定：
-  - `force?: boolean` - 未対応メタデータの書き込みを有効化（元データをそのまま保持）
+  - `status: 'unrecognized'` - 同じフォーマット：そのまま書き込み、異なるフォーマット：warning付きでメタデータ削除
 
 **戻り値:**
 
-- `{ ok: true, value: Uint8Array }` - 書き込み成功（新しい画像データを返す）
+- `{ ok: true, value: Uint8Array, warning?: WriteWarning }` - 書き込み成功
+  - `warning` はメタデータが意図的に削除された場合に設定される（例：未対応のクロスフォーマット変換）
 - `{ ok: false, error: { type, message? } }` - 失敗。`type` は以下のいずれか：
   - `'unsupportedFormat'`: 対象画像がPNG、JPEG、WebP以外の場合
   - `'conversionFailed'`: メタデータ変換に失敗（例：互換性のないフォーマット）

package/README.md

@@ -153,7 +153,7 @@ if (result.status === 'success') {
 > For production use, pin to a specific version instead of `@latest`:
 >
 > ```text
-> https://cdn.jsdelivr.net/npm/@enslo/sd-metadata@1.3.0/dist/index.js
+> https://cdn.jsdelivr.net/npm/@enslo/sd-metadata@1.4.1/dist/index.js
 > ```
 
 ### Advanced Examples
@@ -226,9 +226,9 @@ switch (result.status) {
 </details>
 
 <details>
-<summary>Preserving Unrecognized Metadata</summary>
+<summary>Handling Unrecognized Metadata</summary>
 
-When converting images with metadata from unsupported tools, you can still preserve the original metadata:
+When working with metadata from unsupported tools:
 
 ```typescript
 import { read, write } from '@enslo/sd-metadata';
@@ -236,12 +236,16 @@ import { read, write } from '@enslo/sd-metadata';
 const source = read(unknownImage);
 // source.status === 'unrecognized'
 
-// Preserve all original metadata chunks/segments
-const result = write(targetImage, source, { force: true });
-
+// Write to target image
+// - Same format (e.g., PNG → PNG): metadata preserved as-is
+// - Cross-format (e.g., PNG → JPEG): metadata dropped with warning
+const result = write(targetImage, source);
 if (result.ok) {
-  // Original metadata preserved in the new image
-  console.log('Metadata preserved successfully');
+  saveFile('output.png', result.value);
+  if (result.warning) {
+    // Metadata was dropped during cross-format conversion
+    console.warn('Metadata was dropped:', result.warning.reason);
+  }
 }
 ```
 
@@ -346,7 +350,7 @@ Reads and parses metadata from an image file.
 - `{ status: 'invalid', message? }` - Corrupted or unsupported image format
   - `message`: Optional error description
 
-### `write(data: Uint8Array, metadata: ParseResult, options?: WriteOptions): WriteResult`
+### `write(data: Uint8Array, metadata: ParseResult): WriteResult`
 
 Writes metadata to an image file.
 
@@ -355,13 +359,12 @@ Writes metadata to an image file.
 - `data` - Target image file data (PNG, JPEG, or WebP)
 - `metadata` - `ParseResult` from `read()`
   - `status: 'success'` or `'empty'` - Can write directly
-  - `status: 'unrecognized'` - Requires `force: true` option
-- `options` - Optional settings:
-  - `force?: boolean` - Enables writing unrecognized metadata (preserves original data as-is)
+  - `status: 'unrecognized'` - Same format: writes as-is; Cross-format: drops metadata with warning
 
 **Returns:**
 
-- `{ ok: true, value: Uint8Array }` - Successfully written (returns new image data)
+- `{ ok: true, value: Uint8Array, warning?: WriteWarning }` - Successfully written
+  - `warning` is set when metadata was intentionally dropped (e.g., unrecognized cross-format)
 - `{ ok: false, error: { type, message? } }` - Failed. `type` is one of:
   - `'unsupportedFormat'`: Target image is not PNG, JPEG, or WebP
   - `'conversionFailed'`: Metadata conversion failed (e.g., incompatible format)

package/dist/index.d.ts

@@ -1,20 +1,3 @@
-/**
- * Result type for explicit error handling
- */
-type Result<T, E> = {
-    ok: true;
-    value: T;
-} | {
-    ok: false;
-    error: E;
-};
-/**
- * Helper functions for Result type
- */
-declare const Result: {
-    ok: <T, E>(value: T) => Result<T, E>;
-    error: <T, E>(error: E) => Result<T, E>;
-};
 /**
  * PNG text chunk (tEXt or iTXt)
  */
@@ -31,6 +14,10 @@ type MetadataSegmentSource = {
 } | {
     type: 'exifMake';
     prefix?: string;
+} | {
+    type: 'exifSoftware';
+} | {
+    type: 'exifDocumentName';
 } | {
     type: 'jpegCom';
 };
@@ -330,9 +317,16 @@ declare function read(data: Uint8Array): ParseResult;
  */
 
 /**
- * Result of the write operation
+ * Warning types for write operations
+ */
+type WriteWarning = {
+    type: 'metadataDropped';
+    reason: 'unrecognizedCrossFormat';
+};
+/**
+ * Error types for write operations
  */
-type WriteResult = Result<Uint8Array, {
+type WriteError = {
     type: 'unsupportedFormat';
 } | {
     type: 'conversionFailed';
@@ -340,36 +334,32 @@ type WriteResult = Result<Uint8Array, {
 } | {
     type: 'writeFailed';
     message: string;
-}>;
+};
 /**
- * Options for write operation
+ * Result of the write operation
+ *
+ * Success case may include a warning when metadata was intentionally dropped.
  */
-interface WriteOptions {
-    /**
-     * Force blind conversion for unrecognized formats
-     *
-     * When true, converts raw chunks/segments between formats even when
-     * the generating software is unknown. Enables format conversion for
-     * unknown/future tools without parser implementation.
-     *
-     * When false (default), returns error for unrecognized formats.
-     *
-     * @default false
-     */
-    force?: boolean;
-}
+type WriteResult = {
+    ok: true;
+    value: Uint8Array;
+    warning?: WriteWarning;
+} | {
+    ok: false;
+    error: WriteError;
+};
 /**
  * Write metadata to an image
  *
  * Automatically detects the target image format and converts the metadata
- * if necessary.
+ * if necessary. For unrecognized metadata with cross-format conversion,
+ * metadata is dropped and a warning is returned.
  *
  * @param data - Target image file data
- * @param metadata - ParseResult from `read()` (must be 'success' or contain raw data)
- * @param options - Write options (e.g., { force: true } for blind conversion)
- * @returns New image data with embedded metadata
+ * @param metadata - ParseResult from `read()`
+ * @returns New image data with embedded metadata (or warning if metadata was dropped)
  */
-declare function write(data: Uint8Array, metadata: ParseResult, options?: WriteOptions): WriteResult;
+declare function write(data: Uint8Array, metadata: ParseResult): WriteResult;
 
 /**
  * WebUI (A1111) format writer for sd-metadata
@@ -491,4 +481,4 @@ declare function formatAsWebUI(metadata: GenerationMetadata): string;
  */
 declare function formatRaw(raw: RawMetadata): string;
 
-export { type CharacterPrompt, type GenerationMetadata, type HiresSettings, type ITXtChunk, type MetadataSegment, type MetadataSegmentSource, type ModelSettings, type ParseResult, type PngTextChunk, type RawMetadata, type SamplingSettings, type TExtChunk, type UpscaleSettings, type WriteOptions, type WriteResult, formatAsWebUI, formatRaw, read, write, writeAsWebUI };
+export { type CharacterPrompt, type GenerationMetadata, type HiresSettings, type ITXtChunk, type MetadataSegment, type MetadataSegmentSource, type ModelSettings, type ParseResult, type PngTextChunk, type RawMetadata, type SamplingSettings, type TExtChunk, type UpscaleSettings, type WriteResult, type WriteWarning, formatAsWebUI, formatRaw, read, write, writeAsWebUI };