Export redesign - Githubissues

Currently exports are used in two ways:

export default is how mappings get exported (sometimes implicitly). This is OK but is ambiguous with Maketiles which feels a little ugly.
export rule is how Maketiles export rules, with the default rule via export default (which is ambiguous with mappings). A bigger uglyness is when we want to rules to be computed names, as ESM export doesn't support exporting computed names. Current workaround is to use CommonJS exports[name] = ... but this means we could never go to true ESM which seems like a bad design decision.

I'd like to propose instead that export has a finite set of intended names. export default will remain ambiguous between Maketiles and mappings, for convenience, but you can choose to be unambiguous via export map or export make.

Maketiles (Maketile.{js,coffee})

[x] export make or export default can be specified recursively, similar to maps:
- [x] A default rule (if it's a function with no argument)
- [x] An object (or Map) mapping rule names to rules. Should default rule name be '' or 'default' or undefined or null? I think '' probably makes the most sense.
- [x] A function mapping rule names to rules
- [x] Array maybe means to run the rules in sequence (or in parallel?)
[x] If export make is present, export default is ignored (in case used as mapping file)

The result is that a Maketile.coffee could be written much closer to an actual Makefile, via implicit export default:

drawing1: -> svgtiler 'mapping.coffee drawing1.asc'
drawing2: -> svgtiler 'mapping.coffee drawing2.asc'

And programmatically generated rules could be written reasonably nicely and in ESM:

export make = {}
for lang in ['coffee', 'js']
  make[lang] = do (lang) -> -> svgtiler "mapping.#{lang}"

Or totally generic rule names, something we couldn't do at all with the export approach:

export make = (lang) ->
  svgtiler "mapping.#{lang}"

# Example with default too:
export make = (lang) ->
  if lang
    svgtiler "mapping.#{lang}"
  else # default
    svgtiler 'coffee js'  # recursively call rules
    #or
    for lang in ['coffee', 'js']
      make lang

One limitation here is there's no way to tell, given an argument, whether it's a Maketile rule or a filename. That's fine with the current design: currently, filenames take priority over Maketile rules, so if you do svgtiler foo and foo is a filename, then it gets treated as a filename; indeed, the Maketile only gets loaded if the argument doesn't match as a filename. I think this is fine, as filenames should have .s in them, while rules should not, so there's no real conflict.

[x] Document encouragement to not include ., *, ? in rule names, to avoid conflicts with filenames/globs.
[x] Perhaps don't treat foo as a filename if it doesn't have a . in it, or any glob operators, as it can't possibly be treated as an input; instead directly try to apply as a rule.
[x] Should possibly treat glob as a filename even if it doesn't match any files. Currently *foo gets treated as a rule if there aren't any files ending in foo.

Mappings

This is the second half of #95. In the end, I think the svgtiler.{onInit,preprocess,postprocess} side effects are dangerous and hard to use:

Dangerous when requiring a module for the first time not as a mapping. require('mapping.js') breaks later use as svgtiler.require('mapping.js') or svgtiler('mapping.js'); the side effects are lost forever.
Similarly dangerous when a mapping file is required from another mapping file. If this is the first require, the side effects get attached to the wrong mapping.
Hard to make your own mapping without a file. We could introduce an InlineMapping class that simulates the behavior, but {init, preprocess, postprocess, map} (passed into new Mapping probably) is simpler.
Hard to control order of preprocess/postprocess effects triggered by subroutines.

So instead the proposal is:

[x] export init = -> ... replaces svgtiler.init -> ...
[x] export preprocess = (render) -> ... replaces svgtiler.preprocess (render) -> ...
[x] export postprocess = (render) -> ... replaces svgtiler.postprocess (render) -> ...
[x] Potentially we could allow arrays of functions in the above exports to make it easy to combine multiple steps.
[x] export map or export default specifies a mapping as we currently do.
[x] If export map is present, export default is ignored.

Cool features of this approach:

svgtiler.require('map.js') and require('map.js') are equivalent; there's no special processing for JS/CS mapping files.
Similarly, svgtiler('map.js') is equivalent to svgtiler(require('./map.js')).
You can copy some features from another mapping via export {preprocess, postprocess} from '...js'

If you want to combine effects from two mapping files, you can manually control the order in which they execute. This was very difficult with callbacks. For example:

import {preprocess as preprocess1, postprocess as postprocess1} from 'mapping1.js'
import {preprocess as preprocess2, postprocess as postprocess2} from 'mapping2.js'
export preprocess = (r) -> preprocess1(r); preprocess2(r)
export postprocess = (r) -> postprocess2(r); postprocess1(r)
#or maybe
export preprocess = [preprocess1, preprocess2]
export postprocess = [postprocess2, postprocess1]

[x] Speaking of which, currently postprocess is called in mapping file order, but perhaps it should be in reverse order.

An {init, preprocess, postprocess, map} mapping object can be created via import * as mapping from './mapping.js'

We will have to change the situations in which svgtiler.background is allowed; it can no longer be at the top level of a mapping file.

[ ] We could redefine svgtiler.background to only be callable within postprocess callbacks, with the meaning "add background rect now"; or
[x] Keep its scheduling behavior, but restrict to running within a render (either preprocess or postprocess).

edemaine / svgtiler

Export redesign #100

Maketiles (Maketile.{js,coffee})

Mappings