Add ES Module import/export conventions to improve the ergonomics around including other script files or code blocks. #84
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
- Add explicit dev dependency on `ts-node`, which fixes an configuration
issue with TypeScript/`ts-jest` that would prevent tests from running.
- Update the DateTime JSON conversion tests:
- Update the deserializer logic so that it applies the zone offset to the
resulting DateTime object if there is one in the ISO String
- Use the ISO strings for equality comparisons, since the `.equals()` method
on the DateTime object does a field-wise deep comparison, and zones don't
serialize/deserialize symmetrically.
Provides an overloaded implementation of `Plugin.saveData()` that serializes a `Set<T>` in to an array `T[]`. `loadData()` is not overloaded for conversion back to a `Set<T>`, since there's ambiguity around whether something is intended to be an array or not.
Allows users to provide any amount of folders in the vault that can be used for shortening the paths that need to be provided when `require`'ing other script files or code block links.
dljsjr
force-pushed
the
feat/improved-import-ergonomics
branch
from
2d8eb1d to
25ddd66
Compare
|
Here's a little demo as well: CleanShot.2025-02-05.at.00.48.07.mp4 |
This commit improves the ergonomics aroud importing/requiring scripts from
other files or blocks, while remaining backwards compatible with the existing
functionality in Datacore. The specifics of the changes are:
- Paths and wikilink-like strings passed to `dc.require()` will be checked
against all elements in the `scriptRoots` Setting if the path fails to resolve
against the vault root
- The `imports` transform is now enabled on the Sucrase `transform` operations. This
causes `import { foo } from "bar"` syntax to be transformed in to `const _foo = require("bar")` during
transpiling.
- The script transpilation pass will convert any `foo = require("bar")` statements in to the form
`foo = await dc.require("bar")` before evaluation. This covers both explicitly authored CommonJS require
syntax, as well as the output of the Sucrase transformation for ES Module imports.
- The script transpilation pass will resolve relative paths (e.g. `./foo`) against the script that called
`dc.require()`, allowing for relative imports to now be utilized. This happens as part of the same new
transform sa the one above that converts all `require` statements in to `dc.require` statements.
- The `imports` transform also allows for the use of the `export` keyword in scripts, which gets
transformed in to keys on an `exports` object.
- The `exports` object is injected via the context used to construct the `Function` evaluator.
- Scripts can now choose to either `return { ... }`, as is the current pattern, *or* they can use
`export`.
- Returned values take precedence over the exports object.
- Datacore code blocks that return a View to be rendered can now use `export default` by leveraging
the same effects introduced by the `imports` transform.
- Similarly to scripts loaded with `dc.require()`, the `return function ...` form is still supported.
- Also similarly to the above, the `return function ...` form is given precedence over the `export default` form.
dljsjr
force-pushed
the
feat/improved-import-ergonomics
branch
from
25ddd66 to
23be4b0
Compare
|
Very interesting - I didn't even know this was possible. I will review this soon. |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Note
This change includes the commit from #83
Overview
This PR adds improvements to the ergonomics around importing/requiring scripts.
To provide a rough summary: it adds a series of script transforms that enables emulating ES Module import/export semantics. And it retains backwards compatibility with the existing way of doing things where all scripts get treated as a function body.
Motivation
I wanted to be able to work on Datacore scripts in VS Code, with full IDE support. It was easy enough to emit type declaration files and set up a tsconfig file, but the custom
dc.requiresemantics were obviously not supported.Description of Changes
New Setting:
scriptRootsThe first two commits (after the Jest fix commit) introduces a new Setting for the plug-in,
scriptRoots. It's aSet<string>that is serialized as an arraystring[]. It lets the user configure as many additional roots as they'd like; each root added to this set will be used to attempt to resolvedc.requirepaths until one succeeds.The first commit adds support for serializing Sets to Arrays. The second commit builds the new setting on top of this.
There is custom UI for the setting:
The setting is backed by a
FuzzyFolderSearchSugggestclass for ease-of-use.ES Module
import/exportsemanticsThe final commit is the implementation of the import/export mode. An outline of the major stuff:
Script Definitions refactored in to an interface
The code + language payload loaded from the script cache has been refactored in to an interface. It also now includes a reference to the TFile that the source code came from.
Script Evaluation Context Helpers
The creation of the script context object for the
Functionevaluator is now handled by a utility function.I added this as an exported free function that takes the Local API instance as an argument to avoid having to add this function to the Public API available on the
dcobject.Script Cache
load()'ing from the cache, utilize the new scriptRoots to compute the cache key/file pathsourcePathargument is now available onresolveSource()for passing toresolveLink()on the datastore. This is used assist in converting a module name to a file name, since ES Module names don't have file extensions.Datastore
Script Transpiling/Sucrase Behavior
importstransform for all script types has been enabled. This transform converts ES Moduleimportstatements torequirestatements. It also transforms items modified by theexportkeyword to properties on anexportsobject that is injected via theFunctioncontext/environment.require's to anawait dc.requireform.Loading Views from Datacore Blocks
Views can now
export defaulttheir render target instead ofreturn'ing it.Backwards Compatibility
dc.requireis still the only way to include another script; these changes introduce transforms for ES Moduleimports/CommonJSrequires that make them converge ondc.require.returnform is given precedent over theexportform for generically required scripts.returnform is given precedent over theexport defaultform for render targets.To Do