mirror of
https://github.com/sass/sass.git
synced 2024-09-21 02:27:30 +00:00
[Containing URL] Update types
This commit is contained in:
Natalie Weizenbaum
parent
f61b9165c3
commit
5498410990
36
js-api-doc/importer.d.ts
vendored
36
js-api-doc/importer.d.ts
vendored
@ -62,6 +62,11 @@ export interface FileImporter<
|
||||
* This should *only* be used for determining whether or not to load
|
||||
* [import-only files](https://sass-lang.com/documentation/at-rules/import#import-only-files).
|
||||
*
|
||||
* @param options.containingUrl - The canonical URL of the source file that's
|
||||
* loading `url`, if it has one. Unlike for {@link Importer.canonicalize},
|
||||
* this is always available as long as the containing file has a canonical
|
||||
* URL.
|
||||
*
|
||||
* @returns An absolute `file:` URL if this importer recognizes the `url`.
|
||||
* This may be only partially resolved: the compiler will automatically look
|
||||
* for [partials](https://sass-lang.com/documentation/at-rules/use#partials),
|
||||
@ -85,7 +90,7 @@ export interface FileImporter<
|
||||
*/
|
||||
findFileUrl(
|
||||
url: string,
|
||||
options: {fromImport: boolean}
|
||||
options: {fromImport: boolean, containingUrl?: URL}
|
||||
): PromiseOr<URL | null, sync>;
|
||||
|
||||
/** @hidden */
|
||||
@ -226,6 +231,11 @@ export interface Importer<sync extends 'sync' | 'async' = 'sync' | 'async'> {
|
||||
* This should *only* be used for determining whether or not to load
|
||||
* [import-only files](https://sass-lang.com/documentation/at-rules/import#import-only-files).
|
||||
*
|
||||
* @param options.containingUrl - The canonical URL of the source file that's
|
||||
* loading `url`, if it has one. This is only passed when `url` is either
|
||||
* relative or an absolute URL whose scheme is declared as non-canonical by
|
||||
* {@link nonCanonicalScheme}.
|
||||
*
|
||||
* @returns An absolute URL if this importer recognizes the `url`, or `null`
|
||||
* if it doesn't. If this returns `null`, other importers or {@link
|
||||
* Options.loadPaths | load paths} may handle the load.
|
||||
@ -242,7 +252,7 @@ export interface Importer<sync extends 'sync' | 'async' = 'sync' | 'async'> {
|
||||
*/
|
||||
canonicalize(
|
||||
url: string,
|
||||
options: {fromImport: boolean}
|
||||
options: {fromImport: boolean, containingUrl?: URL}
|
||||
): PromiseOr<URL | null, sync>;
|
||||
|
||||
/**
|
||||
@ -272,6 +282,28 @@ export interface Importer<sync extends 'sync' | 'async' = 'sync' | 'async'> {
|
||||
|
||||
/** @hidden */
|
||||
findFileUrl?: never;
|
||||
|
||||
/**
|
||||
* One or more URL schemes that this importer supports, but will never return
|
||||
* from {@link canonicalize}. When an absolute URL with one of these schemes
|
||||
* is passed to {@link canonicalize}, the URL of the stylesheet that contains
|
||||
* it will be available as well.
|
||||
*
|
||||
* This restriction is in place to ensure that canonical URLs are always
|
||||
* resolved the same way regardless of context, and thus that they're truly
|
||||
* canonical.
|
||||
*
|
||||
* These values must be valid lowercase URL schemes.
|
||||
*
|
||||
* @example An plugin for the fictional NetCram bundler might support a
|
||||
* `netcram:` URL scheme. It would declare `nonCanonicalScheme: "netcram"` so
|
||||
* that when a user wrote `@use "netcram:colorful"`, it would be able to load
|
||||
* different versions of the `colorful` library depending where the `@use` was
|
||||
* located. Its `canonicalize()` function would then return a normal `file:`
|
||||
* URL as the canonical URL for these files, representing their locations on
|
||||
* disk.
|
||||
*/
|
||||
nonCanonicalScheme?: string | string[];
|
||||
}
|
||||
|
||||
/**
|
||||
|
||||
@ -33,14 +33,19 @@ string `string`:
|
||||
* Let `fromImport` be `true` if the importer is being run for an `@import` and
|
||||
`false` otherwise.
|
||||
|
||||
* Let `url` be the result of calling `findFileUrl` with `string` and
|
||||
`fromImport`. If it returns a promise, wait for it to complete and use its
|
||||
value instead, or rethrow its error if it rejects.
|
||||
* Let `containingUrl` be the canonical URL of the [current source file] if it
|
||||
has one, or undefined otherwise.
|
||||
|
||||
* Let `url` be the result of calling `findFileUrl` with `string`,
|
||||
`fromImport`, and `containingUrl`. If it returns a promise, wait for it to
|
||||
complete and use its value instead, or rethrow its error if it rejects.
|
||||
|
||||
* If `url` is null, return null.
|
||||
|
||||
* If `url`'s scheme is not `file`, throw an error.
|
||||
|
||||
[current source file]: ../spec.md#current-source-file
|
||||
|
||||
* Let `resolved` be the result of [resolving `url`].
|
||||
|
||||
[resolving `url`]: ../modules.md#resolving-a-file-url
|
||||
@ -65,7 +70,7 @@ export interface FileImporter<
|
||||
> {
|
||||
findFileUrl(
|
||||
url: string,
|
||||
options: {fromImport: boolean}
|
||||
options: {fromImport: boolean, containingUrl?: URL}
|
||||
): PromiseOr<URL | null, sync>;
|
||||
|
||||
canonicalize?: never;
|
||||
@ -80,9 +85,18 @@ string `string`:
|
||||
* Let `fromImport` be `true` if the importer is being run for an `@import` and
|
||||
`false` otherwise.
|
||||
|
||||
* Let `url` be the result of calling `canonicalize` with `url` and `fromImport`.
|
||||
If it returns a promise, wait for it to complete and use its value instead, or
|
||||
rethrow its error if it rejects.
|
||||
* If `string` is a relative URL, or if it's an absolute URL whose scheme is
|
||||
non-canonical for this importer, let `containingUrl` be the canonical URL of
|
||||
the [current source file]. Otherwise, or if the current source file has no
|
||||
canonical URL, let `containingUrl` be undefined.
|
||||
|
||||
* Let `url` be the result of calling `canonicalize` with `string`, `fromImport`,
|
||||
and `containingUrl`. If it returns a promise, wait for it to complete and use
|
||||
its value instead, or rethrow its error if it rejects.
|
||||
|
||||
* If the scheme of `url` is [non-canonical] for this importer, throw an error.
|
||||
|
||||
[non-canonical]: #noncanonicalscheme
|
||||
|
||||
* If `url` is null, return null.
|
||||
|
||||
@ -104,13 +118,32 @@ string `string`:
|
||||
export interface Importer<sync extends 'sync' | 'async' = 'sync' | 'async'> {
|
||||
canonicalize(
|
||||
url: string,
|
||||
options: {fromImport: boolean}
|
||||
options: {fromImport: boolean; containingUrl?: URL}
|
||||
): PromiseOr<URL | null, sync>;
|
||||
|
||||
load(canonicalUrl: URL): PromiseOr<ImporterResult | null, sync>;
|
||||
|
||||
findFileUrl?: never;
|
||||
}
|
||||
```
|
||||
|
||||
#### `nonCanonicalScheme`
|
||||
|
||||
The set of URL schemes that are considered *non-canonical* for this importer. If
|
||||
this is a single string, treat it as a list containing that string.
|
||||
|
||||
Before beginning compilation, throw an error if any element of this is empty or
|
||||
contains a character other than a lowercase ASCII letter, an ASCII numeral,
|
||||
U+002B (`+`), U+002D (`-`), or U+002E (`.`).
|
||||
|
||||
> Uppercase letters are normalized to lowercase in the `URL` constructor, so for
|
||||
> simplicity and efficiency we only allow lowercase here.
|
||||
|
||||
```ts
|
||||
nonCanonicalScheme?: string | string[];
|
||||
```
|
||||
|
||||
```
|
||||
} // Importer
|
||||
```
|
||||
|
||||
### `ImporterResult`
|
||||
|
||||
Loading…
Reference in New Issue
Block a user