mirror of
https://github.com/sass/sass.git
synced 2024-09-21 10:37:22 +00:00
Fix a duplicated file from a merge error
This commit is contained in:
parent
d124d288e2
commit
4d946dd445
@ -1,12 +0,0 @@
|
||||
## Draft 1.2
|
||||
|
||||
* Await method calls in example code.
|
||||
* Use `compiler.compile*()` methods in example code.
|
||||
|
||||
## Draft 1.1
|
||||
|
||||
* Remove unneeded returned/resolved value from `dispose`.
|
||||
|
||||
## Draft 1
|
||||
|
||||
* Initial draft
|
@ -1,226 +0,0 @@
|
||||
# Shared Resources in JavaScript API: Draft 1.1
|
||||
|
||||
*([Issue](https://github.com/sass/sass/issues/3296))*
|
||||
|
||||
This proposal adds an API design that allows for sharing resources across
|
||||
multiple invocations of the Sass compiler's JavaScript API. This will provide
|
||||
Sass's users with a more efficient way of running Sass compilations across
|
||||
multiple files.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
* [Summary](#summary)
|
||||
* [Design Decisions](#design-decisions)
|
||||
* [Splitting Sync and Async Compilers](#splitting-sync-and-async-compilers)
|
||||
* [Limited API interface](#limited-api-interface)
|
||||
* [Flexibility for interfaces on process management](#flexibility-for-interfaces-on-process-management)
|
||||
* [No shared state](#no-shared-state)
|
||||
* [Example](#example)
|
||||
* [Sync Compiler](#sync-compiler)
|
||||
* [Async Compiler](#async-compiler)
|
||||
* [API](#api)
|
||||
* [Types](#types)
|
||||
* [initCompiler()](#initcompiler)
|
||||
* [initAsyncCompiler()](#initasynccompiler)
|
||||
* [Compiler](#compiler)
|
||||
* [`compile()` and `compileString()`](#compile-and-compilestring)
|
||||
* [dispose()](#dispose)
|
||||
* [Async Compiler](#async-compiler-1)
|
||||
* [`compileAsync()` and `compileStringAsync()`](#compileasync-and-compilestringasync)
|
||||
* [dispose()](#dispose-1)
|
||||
|
||||
## Summary
|
||||
|
||||
Currently, the JavaScript API for Sass only accommodates a single compilation
|
||||
per process. In practice, we have observed build tools are compiling multiple
|
||||
times in response to a single user action. For instance, Vue.js authors using
|
||||
Vite will see a Sass compilation for each `<style lang="scss">` tag that appears
|
||||
in their codebase.
|
||||
|
||||
While processes can be spun up and down quickly, the combined time can add up to
|
||||
a noticeable impact on performance. The embedded client supports long running
|
||||
processes, and this proposal adds a method for the embedded host to manage the
|
||||
lifecycle of these processes through a Compiler interface.
|
||||
|
||||
### Design Decisions
|
||||
|
||||
#### Splitting Sync and Async Compilers
|
||||
|
||||
When creating a Compiler, users will need to choose either a compiler that
|
||||
provides access to synchronous or asynchronous compilation. While providing both
|
||||
simultaneously from a single Compiler would offer more flexibility, it also adds
|
||||
significant complexity to the API. In practice, we expect most users will only
|
||||
want to use one mode, generally in the mode that is the fastest for the
|
||||
implementation. If synchronous and asynchronous compilations are both needed,
|
||||
users can create multiple Compilers.
|
||||
|
||||
#### Limited API interface
|
||||
|
||||
Many build tools allow passing the Sass module as a parameter, which offers
|
||||
flexibility to users on what implementation of Sass is used. Because users may
|
||||
still want to use portions of the JavaScript API unrelated to compilation, we
|
||||
considered having the Compiler interface mirror the top level Sass interface,
|
||||
which would allow users to replace instances of the imported `sass` class with
|
||||
an instance of the compiler. However, this adds an additional cost to ongoing
|
||||
Sass development. The proposed API does not eliminate this as a possibility in
|
||||
the future.
|
||||
|
||||
#### Flexibility for interfaces on process management
|
||||
|
||||
In environments without access to a long-running compiler—for instance, the Dart
|
||||
Sass implementation—the Compiler interface will continue to perform a single
|
||||
compilation per process.
|
||||
|
||||
#### No shared state
|
||||
|
||||
This proposal does not change how a single compilation is done, and no state is
|
||||
shared across compilations. Options and importers must be set for each
|
||||
compilation. Future enhancements may introduce [shared state], but this proposal
|
||||
only adds the ability to run multiple compilations on a single process.
|
||||
|
||||
[shared state]: https://github.com/sass/sass/issues/3296
|
||||
|
||||
This also means that the proposal makes no assertions about whether file content
|
||||
has changed. It is also up to the user to determine when to start and stop a
|
||||
long-running compiler process.
|
||||
|
||||
### Example
|
||||
|
||||
#### Sync Compiler
|
||||
|
||||
```js
|
||||
import * as sass from 'sass';
|
||||
function setup() {
|
||||
const compiler = sass.initCompiler();
|
||||
const result1 = compiler.compileString('a {b: c}').css;
|
||||
const result2 = compiler.compileString('a {b: c}').css;
|
||||
compiler.dispose();
|
||||
|
||||
// throws error
|
||||
const result3 = compiler.compileString('a {b: c}').css;
|
||||
}
|
||||
```
|
||||
|
||||
#### Async Compiler
|
||||
|
||||
```js
|
||||
import * as sass from 'sass';
|
||||
async function setup() {
|
||||
const compiler = await sass.initAsyncCompiler();
|
||||
const result1 = await compiler.compileStringAsync('a {b: c}').css;
|
||||
const result2 = await compiler.compileStringAsync('a {b: c}').css;
|
||||
await compiler.dispose();
|
||||
|
||||
// throws error
|
||||
const result3 = await compiler.compileStringAsync('a {b: c}').css;
|
||||
}
|
||||
```
|
||||
|
||||
## API
|
||||
|
||||
### Types
|
||||
|
||||
```ts
|
||||
import {CompileResult} from '../spec/js-api/compile';
|
||||
import {Options, StringOptions} from '../spec/js-api/options';
|
||||
```
|
||||
|
||||
#### initCompiler()
|
||||
|
||||
Returns a synchronous [Compiler].
|
||||
|
||||
[Compiler]: #compiler
|
||||
|
||||
```ts
|
||||
export function initCompiler(): Compiler;
|
||||
```
|
||||
|
||||
#### initAsyncCompiler()
|
||||
|
||||
Resolves with an [Async Compiler].
|
||||
|
||||
[Async Compiler]: #async-compiler
|
||||
|
||||
```ts
|
||||
export function initAsyncCompiler(): Promise<AsyncCompiler>;
|
||||
```
|
||||
|
||||
#### Compiler
|
||||
|
||||
An instance of the synchronous Compiler.
|
||||
|
||||
```ts
|
||||
export interface Compiler {
|
||||
```
|
||||
|
||||
##### `compile()` and `compileString()`
|
||||
|
||||
Only synchronous compilation methods [`compile()`] and [`compileString()`] must be
|
||||
included, and must have with identical semantics to the [Sass interface].
|
||||
|
||||
[`compile()`]: ../spec/js-api/compile.d.ts.md#compile
|
||||
[`compilestring()`]: ../spec/js-api/compile.d.ts.md#compilestring
|
||||
[Sass interface]: ../spec/js-api/index.d.ts.md
|
||||
|
||||
```ts
|
||||
compile(path: string, options?: Options<'sync'>): CompileResult;
|
||||
compileString(source: string, options?: StringOptions<'sync'>): CompileResult;
|
||||
```
|
||||
|
||||
##### dispose()
|
||||
|
||||
When `dispose` is invoked on a Compiler:
|
||||
|
||||
* Any subsequent invocations of `compile` and `compileString` must throw an
|
||||
error.
|
||||
|
||||
```ts
|
||||
dispose(): void;
|
||||
}
|
||||
```
|
||||
|
||||
#### Async Compiler
|
||||
|
||||
An instance of the asynchronous Compiler.
|
||||
|
||||
```ts
|
||||
export interface AsyncCompiler {
|
||||
```
|
||||
|
||||
##### `compileAsync()` and `compileStringAsync()`
|
||||
|
||||
Only asynchronous compilation methods [`compileAsync()`] and
|
||||
[`compileStringAsync()`] must be included, and must have with identical
|
||||
semantics to the [Sass interface].
|
||||
|
||||
[`compileasync()`]: ../spec/js-api/compile.d.ts.md#compileasync
|
||||
[`compilestringasync()`]: ../spec/js-api/compile.d.ts.md#compilestringasync
|
||||
|
||||
```ts
|
||||
compileAsync(
|
||||
path: string,
|
||||
options?: Options<'async'>
|
||||
): Promise<CompileResult>;
|
||||
compileStringAsync(
|
||||
source: string,
|
||||
options?: StringOptions<'async'>
|
||||
): Promise<CompileResult>;
|
||||
```
|
||||
|
||||
##### dispose()
|
||||
|
||||
When `dispose` is invoked on an Async Compiler:
|
||||
|
||||
* Any subsequent invocations of `compileAsync` and `compileStringAsync` must
|
||||
throw an error.
|
||||
|
||||
* Any compilations that have not yet been settled must be allowed to settle, and
|
||||
not be cancelled.
|
||||
|
||||
* Resolves a Promise when all compilations have been settled, and disposal is
|
||||
complete.
|
||||
|
||||
```ts
|
||||
dispose(): Promise<void>;
|
||||
}
|
||||
```
|
Loading…
Reference in New Issue
Block a user