Auto-imports / import shortcuts / namespaces

[gustavopch]

What?

Civet:

^date-fns#addDays(a, b) // Named import from node_modules

^lodash/add(c, d) // Default import (a function) from node_modules

^../utils.add(e, f) // Default import (an object containing a function) from relative module

<^ui/Button> // JSX element (where `ui` could be an ESBuild alias to `src/ui` for example)

Output:

import { addDays } from 'date-fns'
import add from 'lodash/add'
import utils from '../utils'
import Button from 'ui/Button'

addDays(a, b)

add(c, d)

utils.add(e, f)

<Button>

It's necessary to disambiguate between accessing a named export Vs. accessing a property of the default export, so # is used for the named export to resemble how # is used to point to a specific anchor inside a page on the internet (e.g.: example.com/foo#bar where #bar is something inside that page).

Why?

• When you want to add one line, sometimes you need to add two (the line that imports the thing and the line that uses the thing). Why write more if we can write less?
• Imports are a source of name conflicts: you'll usually need to alias some imports like import { format as formatDate } from 'date-fns' to avoid conflicts with other things in the code. With namespaces, that's not a concern. While namespaces may not be possible, inline imports as showed in the code above are. Why waste any time thinking about name conflicts if we can just not have name conflicts in the first place?
• Imports are a source of Git conflicts: when two changes happen in the same part of the file, they conflict; as static imports are all in the same place, two commits that would otherwise not conflict may conflict simply because they both touch the imports. Why have more Git conflicts when we can have fewer?
• Functions with generic names like format may not clear on what they do. Is it formatting a date? A phone number? A currency? Knowing where it comes from eliminate that doubt: you look ^date-fns.format(value) and you immediately know what it's about, not even 1 second wondering. Why implicit/ambiguous if we can make it explicit/obvious?

Relevant links

• https://rescript-lang.org/docs/manual/latest/import-export: ReScript doesn't have imports/exports. Each file is a module that can be accessed by its name. If a file is called DateUtil.res, it's immediately available in all other modules as the DateUtil module (file names must be unique), e.g.: DateUtil.format(date). No import needed.

Edits

• 2023-01-06: Adjust to disambiguate between default exports and named exports.

[edemaine]

Looks cool! I think this would be fun to play with.

An alternate compilation (which I think you've written in Discord at some point) is this:

import {addDays} from 'date-fns'
import add from 'lodash/add'
import foo from '../utils/foo'

addDays(a, b)

add(c, d)

foo(e, f)

I guess this would be more efficient (less . dereferencing), but it's a little more complicated to implement. (It's still easy to avoid name conflicts via the existing ref mechanism.) Also for something like ^date-fns['add'+'Days'] you wouldn't be able to simplify. So maybe your compilation is what should happen first, and then we could optimize to the above when possible.

The other concern I have is import foo vs. import * as foo. These have different meanings if the module has an export default. Probably you always want to use import * as given how you're using it.

[gustavopch]

Hum, maybe:

• ^date-fns:addDays(): call the named export addDays.
• ^date-fns.addDays(): call the function addDays of the default export.

[gustavopch]

Or maybe ^date-fns#addDays() for the named export. It might make more sense because # is what we use to express the URL of a specific section inside a page on the internet. In a way, those are similar concepts.

Anyway, it seems it will be necessary to disambiguate "accessing a named export" Vs. "accessing a property of the default export".

[gustavopch]

<^ui.Button> is a bit ugly. I'd still use it as I value convenience more than beauty in my code, but it might be good to consider alternatives to ^.

[STRd6]

One possibility might be a "civet autoImport" which will add imports for non-declared variables that start with a capital letter.

"civet autoImport"
<UI.Button>
---
import UI from "./UI.civet"
<UI.Button />

[gustavopch]

So only auto import files in the same folder starting with a capital letter? It wouldn’t be very useful for me honestly as it would leave out most of the desired use cases.

That approach works in ReScript because their module system is completely different and everything can be “imported” that way, so nothing is left out. In Civet, I believe it must be 100% compatible with ESM to be useful.

[STRd6]

That's a good point. It looks like my suggestion wouldn't cover those cases.

[tomByrer]

I'd prefer the auto-import also, but maybe the imported function names & sources all are declaimed in a master file instead of declaimed on top of each file as-needed basis (also would be easy concoctinate).

Not liking to need capitals; clashes with JSX et al. & TBH not liking to learn new tokens also.

[gustavopch]

I believe it could be a new proposal.

// globals.ts
export global PI = 3.14
export global { format as formatDate } from 'date-fns'

// foo.ts
console.log(PI)
formatDate(new Date())

It's not a replacement for this proposal, but a whole different thing.

Could even use both together:

export global formatDate = ^date-fns#format

[edemaine]

^date-fns#addDays seems natural for the named export.

I have a problem now with ^date-fns.addDays. This could naturally be interpreted as a filename; it's common for periods to be in filenames, especially for extensions. I don't think we want .ts or .civet to behave differently than .addDays.

One natural solution is ^date-fns#.addDays where ^date-fns# is short for date-fns#default i.e. the default export. This seems clear enough, but possibly a little ugly.

Alternatively we find some other notation, e.g. one that has a clear open and close delimiter. For example, I was thinking <date-fns> would be cool (like C #include) but it conflicts with JSX. 🫤

For symmetry, another option would be #date-fns# (default export) or #date-fns#addDays (named export). The only problem is that this looks somewhat like a private property, but I don't think it's ambiguous. Oops, no: #UI.civet#Button has an existing meaning (this.#UI.civet.#Button).

Another approach is to use a trailing character instead of a leading character. For example, date-fns^addDays for named export, date-fns^ for default export (e.g. date-fns^.addDays would use a property of the default export). We lose the commonality of # but maybe it's too close to private members anyway (x#y already means x.#y). And the nice thing is we only need to add one character, and it serves the dual role of indicating an auto-import and separating the filename from the export. We could also support spaces in filenames via "foo bar"^. What do you think?

date-fns^addDays(a, b) // Named import from node_modules

node:fs/promises^readFile(filename) // Named import from namespaced submodule

lodash^.add(c, d) // Default import (a function) from node_modules

../utils^.add(e, f) // Default import (an object containing a function) from relative module

<ui/Button^> // JSX element (where `ui` could be an ESBuild alias to `src/ui` for example)

By the way, ^ is now used in left-hand sides (especially patterns) in Civet to denote "pins". But I think it's still fair game to use it in right-hand sides for auto-imports.

[gustavopch]

The "Default import (a function) from node_modules" should be like importing from lodash/add. What you wrote lodash^.add(c, d) looks like importing the default export of lodash and acessing the add property. 🤔

[gustavopch]

Other idea (this works nicely with the syntax highlight):

^'date-fns'#addDays(a, b) //=> import { addDays } from 'date-fns'; addDays(a, b)

^'lodash/add'(c, d) //=> import add from 'lodash/add'; add(c, d)

^'../utils.js'.add(e, f) //=> import utils from '../utils.js'; utils.add(e, f)

<^'ui/Button'> //=> import Button from 'ui/Button'; <Button>

Another one:

date-fns:addDays(a, b) //=> import { addDays } from 'date-fns'; addDays(a, b)

lodash/add:(c, d) //=> import add from 'lodash/add'; add(c, d)

../utils.js:.add(e, f) //=> import utils from '../utils.js'; utils.add(e, f)

<ui/Button:> //=> import Button from 'ui/Button'; <Button>

[edemaine]

lodash^.add(c, d) looks like importing the default export of lodash and acessing the add property. 🤔

That's what I meant. Sorry, I haven't used lodash in ages, so don't know its conventions. I was thinking of something like fs^.readFile for example, where fs's default export is the whole module, so we want import fs from fs; fs.readFile.

@bbrk24 points out that my proposed syntax is ambiguous with XOR though. x^y could be the named export y from module x, or x ^ y. 😭 So if a postfix symbol is going to work, it would need to be a different symbol than ^.

x:y is similarly taken, so we can't do your second idea: date-fns:addDays already means {"datefns": addDays}. I think it would also be confusing with modules like node:fs.

Your first idea, ^"module" and ^"module"#exportName is interesting. I think the quotes could still be optional when you have a #, and ^module# could still be equivalent to ^"module" and ^module#default. I'm not sure whether to prefer ^"module" or ^module#. The quotes have the advantage of making it look like a path (which it is), at the cost of more verbosity. Arguably though the quotes could be an annoyance (e.g. we already made them optional in import statements). Anyway, we could do both:

^'date-fns'#addDays(a, b) //=> import { addDays } from 'date-fns'; addDays(a, b)
^date-fns#addDays(a, b) //=> import { addDays } from 'date-fns'; addDays(a, b)

^'lodash/add'(c, d) //=> import add from 'lodash/add'; add(c, d)
^lodash/add#(c, d) //=> import add from 'lodash/add'; add(c, d)

^'../utils.js'.add(e, f) //=> import utils from '../utils.js'; utils.add(e, f)
^../utils.js#.add(e, f) //=> import utils from '../utils.js'; utils.add(e, f)

<^'ui/Button'> //=> import Button from 'ui/Button'; <Button>
<^ui/Button#> //=> import Button from 'ui/Button'; <Button>

Alternatively, import { Button } from 'ui/Button' is also common, and we could reserve <^ui/Button#> for that. I.e. a blank # could mean "same name as the module filename" by default, instead of the default export, which could be written <^ui/Button#default> if you wanted to avoid quotes. Not sure I prefer this, but throwing it out there. It's maybe hard to define, because you also need to remove the file extension, and it's not clear where to stop (delete after first or last .?).

I think the only downsides are potential ugliness and that # looks like a private property. But as you previously argued, it is how JS exports are often named in documentation.

[edemaine]

One other possibility I wanted to raise is that "string"#foo could be our syntax, in the postfix syntax. And "string"# could be the default export. The idea is that private properties never make sense on a string. There would be no quoteless syntax for this (so far anyway). But it's intriguingly minimal.

'date-fns'#addDays(a, b) //=> import { addDays } from 'date-fns'; addDays(a, b)

'lodash/add'#(c, d) //=> import add from 'lodash/add'; add(c, d)

'../utils.js'#.add(e, f) //=> import utils from '../utils.js'; utils.add(e, f)

<'ui/Button'#> //=> import Button from 'ui/Button'; <Button>

This is essentially my proposal at the top of the thread, but with # instead of ^, combined with your idea of required quotes.

[edemaine]

Oops, I forgot about # → length shorthand. This means we can't use "string"# as shorthand for default input — this is already useful for counting the length of a string. But we could still use "module"#export.

I went ahead and implemented auto imports (which I'm now calling "import literals") in #1652. It should be easy to tweak the notation; the hard part was doing the import deduplication and hoisting. Once we settle the notation, the PR will be ready to review. Getting close!