Add support for list with encode of string

[lmazuel]

Clear and concise description of the problem

Short version:

model MyModel {
  @encode(string, ",")
  terms: string[];
}

would match this JSON:

{
  "synomyms": "a,b,c"
}

and produce SDK like:

class Data:
   synonyms: List[str]

Which will tell the serializer deserializer to use csv, for instance a,b,c. Delimiter is the second parameter. We may decide to accept it only on list of strings for now (refuse int[])

Kwown separator: \n, | and ,

Checklist

• Follow our Code of Conduct
• Read the docs.
• Check that there isn't already an issue that request the same feature to avoid creating a duplicate.

[bterlson]

My feeling on this:

We have ArrayEncoding.spaceDelimited and ArrayEncoding.commaDelimited which today only work in query strings. It's not clear how these should even work outside of that context because the escaping rules are not specified. This seems like a related problem to solve.

One proposal I like is to add ArrayEncoding.CSV with a configurable delimiter and make the existing encoding formats aliases for CSV encoding with the proper delimiter (e.g. ArrayEncoding.spaceDelimited would mean the same thing as ArrayEncoding.CSV, #{ delimiter: " " }). We can follow the CSV RFC for this. For example:

model Foo {
  @encode(ArrayEncoding.CSV)
  list: string[];
  matrix: string[][];
}

might look like this on the wire:

{
  list: "\"A,B\", C",
  matrix: "r1c1,r1c2\nr2c1,r2c2"
}

One concern with this approach is that it would require a standards compliant CSV parser for HTTP clients/servers, which may not in fact be needed. E.g. we know of a service which takes CSV but does not allow commas in the elements which means you can safely split/join. We might consider something like a noEscape option for this scenario.

[timotheeguerin]

Add commaDelimited, newlineDelimited to ArrayEncoding in core and update pipeDelimited and spaceDelimited to have similar doc around containing the delimiter

enum ArrayEncoding {
  /**
   * Values can only contain , if underlying protocol supports encoding those
   * - json -> error
   * - http -> %2C
   */
  commaDelimited,

  /**
   * Values can only contain \n if underlying protocol supports encoding those
   * - json -> error
   * - http -> %0A
   */
  newlineDelimited,
}

Appendix : Encoding with options

Just for reference, do not implement

A POC of what we could do without new language syntax

namespace Encoding {
  scalar custom;

  scalar `array` extends custom {
    /**
     * Values can only contain the delimiter if underlying protocol supports encoding those
     * Example delimiter: ,
     * - json -> error
     * - http -> %2c
     */
    init join(delimiter: valueof string);
  }
}
 model Test {
   @encode(CustomCSVEncoding("-"))
   @encode(#{encoding: ArrayEncoding2.CSV, sep: "-"})
   foo: string[]
 }