Add `Image.fromHash()` factory method

[bass9030]

Description of problem

Before 9.0.0, Image and ImageResolver were separate. If you only had an image hash, you could resolve the image URL by passing the hash to ImageResolver:

let imageURI = await hitomi.ImageResolver.getImageUri({
    hash: hash,
    hasAvif: true,
    hasWebp: true,
    hasJxl: false,
}, "avif");

Since 9.0.0, ImageResolver has been merged into Image. URLs can now only be resolved through methods such as Image.resolveUrl() or Image.fetch(). However, the Image constructor is marked as @internal, so there is currently no public way to resolve an image URL when only the image hash is available.

Description of idea

It would be helpful to expose a public API such as Image.fromHash() (or an equivalent factory method) that creates an Image instance from only the image hash. This would restore the previous capability without exposing the internal constructor.

// example
let hash = "somthinghash1234";
let hasAvif = true;
let image = hitomi.Image.fromHash(hash, hasAvif);
let imageBuffer = await image.fetch(Extension.Avif, false);

Additional context

[H2Owater425]

Thanks for the feature suggestion.

I understand that this was technically possible before by using type casting, since the old resolver only read a few fields from the image object.

However, the public ImageUriResolver.getImageUrl type always required an Image object, so resolving an image URL from only a hash was not an officially supported API.

I'm hesitant to add the suggested public API because it would create an incomplete Image instance without reliable width, height, name, thumbnail availability, or format availability metadata.

Could you share the concrete use case where only the hash is available but the gallery/file metadata is not? If there is a strong use case, a dedicated resolver API may be a better fit than constructing an Image from partial data.

[bass9030]

I am currently building a mirror site for personal use using this library.

On the website, images are requested through endpoints such as /image/{hash}. In previous versions of the library, the backend would calculate the image URL from the hash using ImageResolver and then proxy the image back to the client.

However, this changed after version 9.0.0, when the two instances were merged. Since Image and ImageResolver have been unified, there is no longer a way to use ImageResolver independently.

I also tried serializing the Image instance, but after deserializing it, methods such as Image.fetch are no longer available, making it impossible to obtain the image URL.

I also considered reconstructing a new instance by passing all the necessary data (such as name, width, height, etc.), but as mentioned in the issue above, the constructor is marked as @internal, so creating a new instance is not possible either.

To summarize, I think there are two possible ways to support this use case:

1. Provide a lightweight resolver API that can derive the image URL from the hash alone.
2. Provide a public API that can restore a fully functional Image instance—including methods such as fetch—from serialized data.

I would appreciate it if you could choose the approach that best aligns with the library's intended design.

[H2Owater425]

Thank you for providing the additional context.

Unfortunately, I still think resolving image URLs from only a hash is outside the responsibility of this library.

A hash-only proxy may be a valid application-level design choice, but the library cannot treat a hash alone as a complete Image.

From the library's perspective, an Image should contain reliable metadata and use that to determine how it can be resolved or fetched.

If you still want to work with partial data, you can use the current implementation through JavaScript runtime workarounds until the API direction becomes clearer.

For example, you can bind Image.resolveUrl or Image.fetch to an object that provides the required fields:

await Image.prototype.resolveUrl.bind({
  hitomi: hitomi,
  hash: hash,
  hasAvif: hasAvif,
  hasWebp: hasWebp,
  hasJxl: hasJxl,
  hasThumbnail: hasThumbnail
})(Extension.Webp);

// or

const image = {
  hitomi: hitomi,
  hash: hash,
  hasAvif: hasAvif,
  hasWebp: hasWebp,
  hasJxl: hasJxl,
  hasThumbnail: hasThumbnail
};

await Image.prototype.fetch.bind(Object.assign({
	// @ts-expect-error
	request: Image.prototype.request.bind(image),
	resolveUrl: Image.prototype.resolveUrl.bind(image)
}, image))(Extension.Avif);

Alternatively, if you want to restore an Image instance, you can construct one manually:

new Image(
  // @ts-expect-error
  hitomi,
  width,
  height,
  hash,
  name,
  hasAvif,
  hasWebp,
  hasJxl,
  hasThumbnail
);

// or

Reflect.construct(Image, [
  hitomi,
  width,
  height,
  hash,
  name,
  hasAvif,
  hasWebp,
  hasJxl,
  hasThumbnail
]);

Please note that both approaches rely on internal implementation details and are not considered stable public APIs. This is similar to the previous approach of passing a partial Image instance to ImageUriResolver.getImageUrl.

I am still considering a proper serialization or hydration API for cases where the original gallery or file metadata is available. However, I do not plan to add Image.fromHash() or a public hash-only resolver at this time.

[bass9030]

Thanks for the explanation. I agree with the direction that the library should operate based on reliable metadata, and I understand that a hash alone can't guarantee the completeness of an Image.

I'll take note of the workarounds you mentioned. That said, since both rely on internal implementation details, I'll keep in mind that they could break at any point in a future minor version update.

One thing I'd like to ask is what form you're considering for the serialization/hydration API you mentioned. For example, are you thinking of something like a static factory method (e.g. Image.fromMetadata()) that restores an Image instance based on full gallery metadata? If so, would it be alright to keep this issue open for tracking purposes until that feature is ready?

I have no objection to your decision not to add Image.fromHash() or a hash-only resolver for now. Thanks for clarifying the direction.