microsoft/qdk
Publicmirrored from https://github.com/microsoft/qdkAvailable
source/npm/qsharp/README.md
51lines · modecode
| 1 | # qsharp npm module |
| 2 | |
| 3 | This package contains the qsharp compiler and language service functionality shipped for consumption via npm. |
| 4 | |
| 5 | The source is written in TypeScript, which is compiled to ECMAScript modules in the ./dist directory. |
| 6 | The wasm binaries from the Rust builds are copied to the ./lib directory. |
| 7 | |
| 8 | Consuming browser projects should import from this module and use a bundler to create their |
| 9 | own JavaScript bundle, and also copy the wasm file to their project and provide the URL |
| 10 | to it when calling the `loadWasmModule` method so it may be located and loaded. |
| 11 | |
| 12 | ## Node and browser support |
| 13 | |
| 14 | This package provides separate entry points for browser (`browser.ts`) and Node.js (`node.ts`) |
| 15 | environments. Each entry point handles platform-specific setup before re-exporting the |
| 16 | shared API from `main.ts`. The public API is the same regardless of the runtime. |
| 17 | |
| 18 | ## Design |
| 19 | |
| 20 | This package provides two services, the compiler and the language service. |
| 21 | |
| 22 | The API for using these services is similar whether using a browser or Node.js, |
| 23 | and whether running in the main thread or a worker thread. You instantiate the service |
| 24 | and call operations on it which complete in the order called. |
| 25 | |
| 26 | All operations return a Promise which resolves then the operation is complete. Some operations |
| 27 | may also emit events, such as debug messages or state dumps as they are processed. The service |
| 28 | itself can also emit events which can be subscribed to using `addEventListener`. |
| 29 | |
| 30 | See the Q# playground code at <https://github.com/microsoft/qdk/tree/main/source/playground> for |
| 31 | an example of code that uses this package. The unit tests at |
| 32 | <https://github.com/microsoft/qdk/tree/main/source/npm/test> are also a good reference. |
| 33 | |
| 34 | Promises, Events, and Cancellation are based on JavaScript or Web standards, or the VS Code API: |
| 35 | |
| 36 | - Promises <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Using_promises> |
| 37 | - EventTarget <https://developer.mozilla.org/en-US/docs/Web/API/EventTarget> |
| 38 | - Event <https://developer.mozilla.org/en-US/docs/Web/API/Event/Event> |
| 39 | - VS Code API for CancellationToken <https://code.visualstudio.com/api/references/vscode-api#CancellationToken> |
| 40 | |
| 41 | The standard Web APIs for custom events were added to Node.js in v16.17. <https://nodejs.org/dist/v16.17.0/docs/api/events.html>, but behind an experimental flag. As CustomEvent is not on |
| 42 | the global by default until v19 or later, the code will use Event with a 'detail' |
| 43 | property manually set until v20 is in common use. |
| 44 | |
| 45 | The VS Code implementation for cancellation tokens is viewable in their source code |
| 46 | at <src/vs/base/common/cancellation.ts>. This code uses a simplified version of that API. |
| 47 | |
| 48 | ## Testing |
| 49 | |
| 50 | Node.js tests can be run via `node --test` (see |
| 51 | <https://nodejs.org/dist/latest-v18.x/docs/api/test.html#test-runner-execution-model>). |
| 52 | |