@flighthq/image-codec 0.3.0-next.1392.f0bd0cc → 0.3.0-next.1422.b585c0c

package/dist/contract.d.ts

@@ -1,6 +1,8 @@
 export * from './decodeImage';
 export * from './detectImageMimeType';
 export * from './encodeImage';
+export * from './explainImageDecodeFailure';
+export * from './explainImageEncodeFailure';
 export * from './imageDecoderRegistry';
 export * from './imageEncoderRegistry';
 export * from './registerWebImageDecoders';

package/dist/contract.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"AAAA,cAAc,eAAe,CAAC;AAC9B,cAAc,uBAAuB,CAAC;AACtC,cAAc,eAAe,CAAC;AAC9B,cAAc,wBAAwB,CAAC;AACvC,cAAc,wBAAwB,CAAC;AACvC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,4BAA4B,CAAC"}
+{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"AAAA,cAAc,eAAe,CAAC;AAC9B,cAAc,uBAAuB,CAAC;AACtC,cAAc,eAAe,CAAC;AAC9B,cAAc,6BAA6B,CAAC;AAC5C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,wBAAwB,CAAC;AACvC,cAAc,wBAAwB,CAAC;AACvC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,4BAA4B,CAAC"}

package/dist/contract.js

@@ -1,6 +1,8 @@
 export * from './decodeImage';
 export * from './detectImageMimeType';
 export * from './encodeImage';
+export * from './explainImageDecodeFailure';
+export * from './explainImageEncodeFailure';
 export * from './imageDecoderRegistry';
 export * from './imageEncoderRegistry';
 export * from './registerWebImageDecoders';

package/dist/contract.js.map

@@ -1 +1 @@
-{"version":3,"file":"contract.js","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"AAAA,cAAc,eAAe,CAAC;AAC9B,cAAc,uBAAuB,CAAC;AACtC,cAAc,eAAe,CAAC;AAC9B,cAAc,wBAAwB,CAAC;AACvC,cAAc,wBAAwB,CAAC;AACvC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,4BAA4B,CAAC"}
+{"version":3,"file":"contract.js","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"AAAA,cAAc,eAAe,CAAC;AAC9B,cAAc,uBAAuB,CAAC;AACtC,cAAc,eAAe,CAAC;AAC9B,cAAc,6BAA6B,CAAC;AAC5C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,wBAAwB,CAAC;AACvC,cAAc,wBAAwB,CAAC;AACvC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,4BAA4B,CAAC"}

package/dist/explainImageDecodeFailure.d.ts

@@ -0,0 +1,3 @@
+import type { ImageDecodeFailureExplanation } from '@flighthq/types/contract';
+export declare function explainImageDecodeFailure(bytes: Readonly<Uint8Array>, mimeType?: string): ImageDecodeFailureExplanation | null;
+//# sourceMappingURL=explainImageDecodeFailure.d.ts.map

package/dist/explainImageDecodeFailure.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"explainImageDecodeFailure.d.ts","sourceRoot":"","sources":["../src/explainImageDecodeFailure.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,6BAA6B,EAAE,MAAM,0BAA0B,CAAC;AAO9E,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,QAAQ,CAAC,UAAU,CAAC,EAC3B,QAAQ,CAAC,EAAE,MAAM,GAChB,6BAA6B,GAAG,IAAI,CAKtC"}

package/dist/explainImageDecodeFailure.js

@@ -0,0 +1,13 @@
+import { detectImageMimeType } from './detectImageMimeType';
+import { getImageDecoder } from './imageDecoderRegistry';
+// Explains the two dispatcher failures that decodeImage represents with null. Returns null when the
+// same request can reach a registered decoder. This is a read-only query and never invokes the codec.
+export function explainImageDecodeFailure(bytes, mimeType) {
+    const type = mimeType ?? detectImageMimeType(bytes);
+    if (type === null)
+        return { mimeType: null, reason: 'mime-type-undetected' };
+    if (getImageDecoder(type) === null)
+        return { mimeType: type, reason: 'decoder-not-registered' };
+    return null;
+}
+//# sourceMappingURL=explainImageDecodeFailure.js.map

package/dist/explainImageDecodeFailure.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"explainImageDecodeFailure.js","sourceRoot":"","sources":["../src/explainImageDecodeFailure.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAEzD,oGAAoG;AACpG,sGAAsG;AACtG,MAAM,UAAU,yBAAyB,CACvC,KAA2B,EAC3B,QAAiB;IAEjB,MAAM,IAAI,GAAG,QAAQ,IAAI,mBAAmB,CAAC,KAAK,CAAC,CAAC;IACpD,IAAI,IAAI,KAAK,IAAI;QAAE,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,EAAE,sBAAsB,EAAE,CAAC;IAC7E,IAAI,eAAe,CAAC,IAAI,CAAC,KAAK,IAAI;QAAE,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,EAAE,wBAAwB,EAAE,CAAC;IAChG,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/explainImageEncodeFailure.d.ts

@@ -0,0 +1,3 @@
+import type { ImageEncodeFailureExplanation } from '@flighthq/types/contract';
+export declare function explainImageEncodeFailure(mimeType: string): ImageEncodeFailureExplanation | null;
+//# sourceMappingURL=explainImageEncodeFailure.d.ts.map

package/dist/explainImageEncodeFailure.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"explainImageEncodeFailure.d.ts","sourceRoot":"","sources":["../src/explainImageEncodeFailure.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,6BAA6B,EAAE,MAAM,0BAA0B,CAAC;AAM9E,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,MAAM,GAAG,6BAA6B,GAAG,IAAI,CAGhG"}

package/dist/explainImageEncodeFailure.js

@@ -0,0 +1,9 @@
+import { getImageEncoder } from './imageEncoderRegistry';
+// Explains the dispatcher failure that encodeImage represents with null. Returns null when an encoder
+// is registered for the requested MIME type. This is a read-only query and never invokes the codec.
+export function explainImageEncodeFailure(mimeType) {
+    if (getImageEncoder(mimeType) !== null)
+        return null;
+    return { mimeType, reason: 'encoder-not-registered' };
+}
+//# sourceMappingURL=explainImageEncodeFailure.js.map

package/dist/explainImageEncodeFailure.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"explainImageEncodeFailure.js","sourceRoot":"","sources":["../src/explainImageEncodeFailure.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAEzD,sGAAsG;AACtG,oGAAoG;AACpG,MAAM,UAAU,yBAAyB,CAAC,QAAgB;IACxD,IAAI,eAAe,CAAC,QAAQ,CAAC,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IACpD,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,wBAAwB,EAAE,CAAC;AACxD,CAAC"}

package/dist/index.d.ts

@@ -1,2 +1,2 @@
-export { clearImageDecoders, clearImageEncoders, decodeImage, decodeImagePremultiplied, detectImageMimeType, encodeImage, getImageDecoder, getImageDecoderMimeTypes, getImageEncoder, getImageEncoderMimeTypes, hasImageDecoder, hasImageEncoder, registerImageDecoder, registerImageEncoder, registerWebImageDecoders, registerWebImageEncoders, unregisterImageDecoder, unregisterImageEncoder, } from './contract';
+export { clearImageDecoders, clearImageEncoders, decodeImage, decodeImagePremultiplied, detectImageMimeType, encodeImage, explainImageDecodeFailure, explainImageEncodeFailure, getImageDecoder, getImageDecoderMimeTypes, getImageEncoder, getImageEncoderMimeTypes, hasImageDecoder, hasImageEncoder, registerImageDecoder, registerImageEncoder, registerWebImageDecoders, registerWebImageEncoders, unregisterImageDecoder, unregisterImageEncoder, } from './contract';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,kBAAkB,EAClB,kBAAkB,EAClB,WAAW,EACX,wBAAwB,EACxB,mBAAmB,EACnB,WAAW,EACX,eAAe,EACf,wBAAwB,EACxB,eAAe,EACf,wBAAwB,EACxB,eAAe,EACf,eAAe,EACf,oBAAoB,EACpB,oBAAoB,EACpB,wBAAwB,EACxB,wBAAwB,EACxB,sBAAsB,EACtB,sBAAsB,GACvB,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,kBAAkB,EAClB,kBAAkB,EAClB,WAAW,EACX,wBAAwB,EACxB,mBAAmB,EACnB,WAAW,EACX,yBAAyB,EACzB,yBAAyB,EACzB,eAAe,EACf,wBAAwB,EACxB,eAAe,EACf,wBAAwB,EACxB,eAAe,EACf,eAAe,EACf,oBAAoB,EACpB,oBAAoB,EACpB,wBAAwB,EACxB,wBAAwB,EACxB,sBAAsB,EACtB,sBAAsB,GACvB,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -1,2 +1,2 @@
-export { clearImageDecoders, clearImageEncoders, decodeImage, decodeImagePremultiplied, detectImageMimeType, encodeImage, getImageDecoder, getImageDecoderMimeTypes, getImageEncoder, getImageEncoderMimeTypes, hasImageDecoder, hasImageEncoder, registerImageDecoder, registerImageEncoder, registerWebImageDecoders, registerWebImageEncoders, unregisterImageDecoder, unregisterImageEncoder, } from './contract';
+export { clearImageDecoders, clearImageEncoders, decodeImage, decodeImagePremultiplied, detectImageMimeType, encodeImage, explainImageDecodeFailure, explainImageEncodeFailure, getImageDecoder, getImageDecoderMimeTypes, getImageEncoder, getImageEncoderMimeTypes, hasImageDecoder, hasImageEncoder, registerImageDecoder, registerImageEncoder, registerWebImageDecoders, registerWebImageEncoders, unregisterImageDecoder, unregisterImageEncoder, } from './contract';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,kBAAkB,EAClB,kBAAkB,EAClB,WAAW,EACX,wBAAwB,EACxB,mBAAmB,EACnB,WAAW,EACX,eAAe,EACf,wBAAwB,EACxB,eAAe,EACf,wBAAwB,EACxB,eAAe,EACf,eAAe,EACf,oBAAoB,EACpB,oBAAoB,EACpB,wBAAwB,EACxB,wBAAwB,EACxB,sBAAsB,EACtB,sBAAsB,GACvB,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,kBAAkB,EAClB,kBAAkB,EAClB,WAAW,EACX,wBAAwB,EACxB,mBAAmB,EACnB,WAAW,EACX,yBAAyB,EACzB,yBAAyB,EACzB,eAAe,EACf,wBAAwB,EACxB,eAAe,EACf,wBAAwB,EACxB,eAAe,EACf,eAAe,EACf,oBAAoB,EACpB,oBAAoB,EACpB,wBAAwB,EACxB,wBAAwB,EACxB,sBAAsB,EACtB,sBAAsB,GACvB,MAAM,YAAY,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flighthq/image-codec",
-  "version": "0.3.0-next.1392.f0bd0cc",
+  "version": "0.3.0-next.1422.b585c0c",
   "repository": {
     "type": "git",
     "url": "https://github.com/flighthq/flight.git",
@@ -36,7 +36,7 @@
     "clean:dist": "tsx ../../scripts/clean-package-dist.ts"
   },
   "dependencies": {
-    "@flighthq/types": "0.3.0-next.1392.f0bd0cc"
+    "@flighthq/types": "0.3.0-next.1422.b585c0c"
   },
   "devDependencies": {
     "typescript": "^5.3.0"

package/src/decodeImage.test.ts

@@ -53,7 +53,14 @@ describe('decodeImagePremultiplied', () => {
       fakeDecoded(),
     );
     registerImageDecoder('image/png', decoder);
-    await decodeImagePremultiplied(pngBytes);
+    await decodeImagePremultiplied(pngBytes, 'image/png');
+    expect(decoder).toHaveBeenCalledWith(pngBytes, { premultiplyAlpha: true });
+  });
+
+  it('auto-detects the MIME type when omitted', async () => {
+    const decoder = vi.fn(async () => fakeDecoded());
+    registerImageDecoder('image/png', decoder);
+    expect(await decodeImagePremultiplied(pngBytes)).toEqual(fakeDecoded());
     expect(decoder).toHaveBeenCalledWith(pngBytes, { premultiplyAlpha: true });
   });
 

package/src/explainImageDecodeFailure.test.ts

@@ -0,0 +1,37 @@
+import { vi } from 'vitest';
+
+import { explainImageDecodeFailure } from './explainImageDecodeFailure';
+import { clearImageDecoders, registerImageDecoder } from './imageDecoderRegistry';
+
+const pngBytes = new Uint8Array([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+
+afterEach(() => {
+  clearImageDecoders();
+});
+
+describe('explainImageDecodeFailure', () => {
+  it('distinguishes an undetected MIME type from a missing decoder', () => {
+    expect(explainImageDecodeFailure(new Uint8Array([0, 1, 2, 3]))).toEqual({
+      mimeType: null,
+      reason: 'mime-type-undetected',
+    });
+    expect(explainImageDecodeFailure(pngBytes)).toEqual({
+      mimeType: 'image/png',
+      reason: 'decoder-not-registered',
+    });
+  });
+
+  it('reports the explicit MIME type when its decoder is missing', () => {
+    expect(explainImageDecodeFailure(pngBytes, 'image/custom')).toEqual({
+      mimeType: 'image/custom',
+      reason: 'decoder-not-registered',
+    });
+  });
+
+  it('returns null without invoking a registered decoder', () => {
+    const decoder = vi.fn();
+    registerImageDecoder('image/png', decoder);
+    expect(explainImageDecodeFailure(pngBytes)).toBeNull();
+    expect(decoder).not.toHaveBeenCalled();
+  });
+});

package/src/explainImageEncodeFailure.test.ts

@@ -0,0 +1,24 @@
+import { vi } from 'vitest';
+
+import { explainImageEncodeFailure } from './explainImageEncodeFailure';
+import { clearImageEncoders, registerImageEncoder } from './imageEncoderRegistry';
+
+afterEach(() => {
+  clearImageEncoders();
+});
+
+describe('explainImageEncodeFailure', () => {
+  it('reports a missing encoder and its requested MIME type', () => {
+    expect(explainImageEncodeFailure('image/custom')).toEqual({
+      mimeType: 'image/custom',
+      reason: 'encoder-not-registered',
+    });
+  });
+
+  it('returns null without invoking a registered encoder', () => {
+    const encoder = vi.fn();
+    registerImageEncoder('image/png', encoder);
+    expect(explainImageEncodeFailure('image/png')).toBeNull();
+    expect(encoder).not.toHaveBeenCalled();
+  });
+});