minor improvements to do

[omar-azmi]

utility.ts

• [x] to_hex_string should also accept typed arrays.

  export const to_hex_string = (arr: number[] | TypedArray, sep: string = ", ", prefix: string = "0x", trailing_sep: boolean = false) => {
  const num_arr: number[] = (arr as TypedArray).buffer ? Array.from(arr as TypedArray) : arr as number[]
  const str = num_arr.map(v => v.toString(16).toUpperCase()).reduce((s, v) => {
      v = v.length === 2 ? v : "0" + v
      return s + prefix + v + sep
  }, "")
  return "[" + str.substring(0, str.length - (trailing_sep ? 0 : sep.length)) + "]"
  }

• [x] introduce a type alias for the commonly used 2-tuple [value: any, bytesize: number] return type of all decode functions.

  export type Decoded<V extends any, ByteSize: number> = [value: V, bytesize: ByteSize]
  // sample usage:
  const decode_u4l = (buf: Uint8Array, offset: number): Decoded<number> => [new Uint32Array(buf.slice(offset, offset+4).buffer)[0], 4]

• [x] add a schema based FileWriter class or add a writeFile schema encoding function to FileParser

schema_codec.ts

• [x] introduce the convenience schema class SHeadLengthArray<S, HeadType extends NumericType> extends SArray<S>, which behaves just like SArray, but has its array length defined in the head (beginning) bytes in the provided byte format NumericType

• [x] also introduce a similar SHeadBytes<HeadType extends NumericType> schema class for convenient decoding of Uint8Arrays

tasks above were completed at commit d7f7bb641d1831ffe9fb962ea53c67c2f03b2df4

• [ ] add javascript primitive types with binary_format branding

[omar-azmi]

primitive_codec.ts

• [ ] add javascript primitive types with binary_format branding

  example:

  export type U4L = number | number & { format: "unsigned", bytesize: 4, endian: "little" }
  export type I4L = number | number & { format: "signed", bytesize: 4, endian: "little" }
  export type U1 = number | number & { format: "unsigned", bytesize: 1, endian: undefined }
  /** a `cstring` is a string terminated by the `"\u0000"` (or `0x00`) byte character */
  export type CSTR = string | `${string}\u0000` | `${string}\\u0000`
  /** a string of length `N` */
  export type STR<N extends number = 0> = string | string & { length: N }

  doing so will allow you to specify the byte_format directly in the type declarations, and it will also get picked up by document generators, such as TypeDoc. moreover, it will be fully compatible with regular javascript types

  sample usage:

  
  type CanvasRectHeader_type = {
  /** x-coord pixel position with respect to the top-left corner */
  x: U4L
  /** y-coord pixel position with respect to the top-left corner */
  y: U4L
  /** pixel width (rightward) of this canvas */
  width: U4L
  /** pixel height (downward) of this canvas */
  height: U4L
  /** specify the length of `palette`. it must be at least `2` because the first entry is reserved for erasing/background. `min(palette_len) = 2` and `max(palette_len) = 255` */
  palette_len?: never & U1 // this is an opaque type, which is present in the binary format, but not in the decoded object
  /** ordered array of palette ids. `palette.length == palette_len` or `bytesizeOf(palette) / 4 == palette_len`. <br>
   * the first entry (`palette[0]`) is always set to `0x00` because it is reserved for eraser mode
  */
  palette: [eraser: 0, ...indexes: I4L[]]
  }

class CanvasRectHeader extends SRecord { constructor() { super( new SPrimitive("u4l").setName("x"), new SPrimitive("u4l").setName("y"), new SPrimitive("u4l").setName("width"), new SPrimitive("u4l").setName("height"), new SHeadPrimitive("u1", "i4l[]", [0,] as [0, ...number[]]).setName("palette"), ) } }