normalize-function-arguments

Table of Contents generated with DocToc

• normalize-function-arguments
  • Properties
  • Terminology
  • To Do
    • Template Class
    • Order of Arguments
    • Other
  • Is Done
  • Don't

normalize-function-arguments

Normalize JavaScript function arguments to simplify variadic function signatures, default values, type validation

Properties

• method nfa() accepts (among other things) a function fn as argument
• nfa() returns a function (call it nfn), which is a wrapped version of fn that
  • accepts the same number of arguments;
  • fn will be called with a normalized arguments
  • and its return value will be returned by the wrapper.
• The declaration of fn:
  • must not use spread syntax or default values on any on the parameters
  • must have a parameter named cfg as its only, or as its last or as its next-to-last parameter

• (TBD) normalization of call-time arguments
• (TBD) templating
• (TBD) validation
• (TBD) ClearType integration

Terminology

• qualified parameters (Q)
• qualified argument(s)
• positional parameters (P)
• positional arguments

To Do

Template Class

• class Template accepts cfg, an optional, single POD for instantiation
• will copy all own properties of cfg, but
• properties that are functions will be turned into managed properties
• in order to have templates with mutable objects as properties that are not shared after copying with t = new Template cfg; { t..., }, do not use t = { n: [ 1, 2, 3, ], }, instead wrap value in function, as in t = { n: ( -> [ 1, 2, 3, ] ), }; now every time t is copied, t.n will be a new list
• nested PODs will be recursively turned into instances of Template

Order of Arguments

• when CFG is in the penultimate, an optional function is assumed to be the last parameter
  • in such cases, when the wrapped function is called with a function as last argument, that function will be 'shifted' to the position of the terminal parameter, meaning that it will not be understood as the value of another positional argument

Other

• [—] integrate ClearType as nfa type, fn and nfa { type, }, fn
• [—] allow shifting of arguments depending on their type
• [—] configuration settings:
  • [—] demand vs allow final CFG
  • [—] demand n positional arguments
  • [+] fallback value for unset qualified arguments (template)
  • [+] function or type to check whether last argument is 'Q-worthy' (one expected for named arguments)
  • [—] name of named parameters object (defaults to cfg)
  • [—] allow both standalone type (as in nfa type ( cfg ) ->) and type as named setting (as in nfa { type, } ( cfg ) ->)
• resolution strategy for repeated setting:
  • [—] cfg.template should prevail in cfg = { template, type: { template, }, }
  • [—] cfg.isa should prevail in cfg = { isa, type: { isa, }, }
  • [—] cfg.validate should prevail in cfg = { validate, type: { validate, }, }
  • [—] cfg.validate should prevail in cfg = { validate, isa, type: { validate, isa, }, }
  • in general, the 'lower'/outer, ('more visible') setting should prevail; explicit validate() should prevail over implicit validation constructed from isa()
• [—] allow the CFG parameter to be in penultimate position to cover cases (like in Normalize_function_arguments::nfa()) where a final parameter should be occupied by e.g. a function (but do not place type restrictions on that last parameter)
• [—] allow asynchronous functions, generator functions, async generator functions for Normalize_function_arguments::nfa#fn
• [—] errors:
  • [—] refactor error classes to proper module
  • [—] use standard setup
  • [—] apply to errors thrown in submodule helpers
• [—] implement a 'nano' or 'kernel' version of ClearType (sans create() prob.) but, crucially, with constructor for validate() methods, proper type_of()

Is Done

• [+] handle empty signatures
  • [+] in Normalize_function_arguments::get_signature()
  • [+] in Normalize_function_arguments::nfa()
• [+] consider to dump dispositions, disallow soaks, default values in signatures to make analysis simpler, faster; will be handled by cfg.template / cfg.type
• [+] implement class Template
• [+] implement recursive templating in class Template
• [+] if last parameter is named cfg, assume it is for the named parameters object and assign it a fallback value {} mandate at least one and final parameter that must have the configured q_name
• [+] CFG setting template as nfa { template, }, fn
• [+] preserve name of wrapped function
• [+] implement validation as nfa { isa, }, fn

Don't

• [—] name clash resolution strategies positional arguments other than undefined always override values in cfg
• [—] fallback value for unset positional arguments (or use template) positional arguments other than undefined always override values in cfg