feat!: new syntax for providers

[ascorbic]

This PR introduces a major update focusing on improved type safety, better provider-specific support, and a more explicit approach to URL transformation. This can be tested by installing from pkg.pr.new: #133 (comment)

Key Changes

Provider-Specific Operations

• Added type-safe support for provider-specific operations and options
• Operations can now be passed separately from core transforms
• Improved TypeScript types for all provider operations

New Fallback System

• Replaced recursive URL delegation with explicit fallback providers
• Added fallback option to specify a provider for unrecognized URLs
• More predictable and controllable image optimization

Enhanced Type Safety

• Added generic type support across the API
• Improved TypeScript types for provider operations and options
• Better IntelliSense support for provider-specific features

API Refinements

• Cleaner separation between core and provider-specific operations

Documentation

• Added upgrade guide for migrating from v3
• Updated README with new examples and features
• Improved documentation for provider-specific features

Breaking Changes

See UPGRADING.md for a detailed migration guide and CHANGELOG.md for a complete list of changes.

[Copilot]

Copilot reviewed 109 out of 124 changed files in this pull request and generated 1 suggestion.

Files not reviewed (15)

• .vscode/settings.json: Language not supported
• .zed/settings.json: Language not supported
• data/paths.json: Language not supported
• data/subdomains.json: Language not supported
• demo/src/examples.json: Language not supported
• deno.json: Language not supported
• deno.jsonc: Language not supported
• src/parse.ts: Evaluated as low risk
• src/canonical.test.ts: Evaluated as low risk
• src/canonical.ts: Evaluated as low risk
• mod.ts: Evaluated as low risk
• src/async.ts: Evaluated as low risk
• src/detect.ts: Evaluated as low risk
• README.md: Evaluated as low risk
• src/providers/astro.test.ts: Evaluated as low risk

Comments skipped due to low confidence (3)

src/providers/astro.ts:47

• Ensure that src is a valid URL before setting it in the URL search params.

url.searchParams.set("href", src.toString());

src/providers/astro.ts:55

• Validate that src is not empty before proceeding.

const src = parsedUrl.searchParams.get("href");

src/extract.ts:35

• [nitpick] The provider names in the parsers object should be consistent. For example, 'cloudflare_images' should be 'cloudflareImages'.

export const parsers: URLExtractorMap = {

Copilot reviewed 128 out of 139 changed files in this pull request and generated no suggestions.

Files not reviewed (11)

• .vscode/settings.json: Language not supported
• .zed/settings.json: Language not supported
• data/paths.json: Language not supported
• data/subdomains.json: Language not supported
• demo/src/examples.json: Language not supported
• deno.json: Language not supported
• deno.jsonc: Language not supported
• demo/src/App.jsx: Evaluated as low risk
• e2e.test.ts: Evaluated as low risk
• mod.ts: Evaluated as low risk
• scripts/build_npm.ts: Evaluated as low risk

Comments skipped due to low confidence (3)

README.md:60

• The example code should use url.toString() for consistency with the previous example. It should be console.log(url.toString());

console.log(url);

src/async.ts:125

• Ensure that providerOperations is defined before accessing it to avoid potential runtime errors.

...providerOperations?.[cdn],

src/async.ts:126

• Ensure that providerOptions is defined before accessing it to avoid potential runtime errors.

...providerOptions?.[cdn] ?? {} as ProviderOptions[TCDN]);

[pkg-pr-new]

Open in Stackblitz

npm i https://pkg.pr.new/unpic@133

commit: 23b1781