omar-azmi / byte_codec_ts Goto Github PK

here a bunch of to-dos for a more robust codebase:

• add fixed value deterministic tests
• add primitive type randomized value generator
• integrate random value generator to tests for randomized tests
• use of class-based schema-generator,
  or anonymous function schema-generator
  instead of using object variables, since embedding any value into the schema variable during codec runtime will affect all objects embedding that schema variable as a child. the only way to avoid it is by:
  • never embedding any value into schema variables. which makes writing functions for schema a lot more difficult
  • cloning a template of the schema, which can either be done via a function, or a class. but schema generating functions could possibly reference embed a child schema variable instead of a generator, which will again break all instances of that schema during runtime. so, exclusive class-based instancing of schema is far more preferable
• non-exported codecs do not appear in the TypeDoc docs that get generated. I'm using a typedoc-plugin-not-exported plugin to allow the documentation of non-exported stuff, but the plugin either does not work with the latest version of TypeDoc, or maybe only intended for using on typescript types and interfaces. find a fix for this, or ultimately downgrade your TypeDoc version
• engineer CallbackType schemas better, or maybe turn them into conditionals
• reconsider the way schema args are currently used when you switch on to a class-based schema instancing
• consider using a global_codecs key-value global variable that holds all schema type codecs, based on the schema's { type: string } as key, and the corresponding schema-class as the value
• find ways to minify class-based code using esbuild's mangle option. but if it's not good enough, consider ditching esbuild and using Teser instead for minification and bundling. or maybe consider es6-class-minify + esbuild
• base design choices on what will benefit a general multi-stage and context-aware object codec
• convert all scripts from non-module javascript extensions ".js" to modular ".mjs'
• consider the possibility of using deno+esbuild instead of node+esbuild to avoid the extensive use of node scripts and the complexities of ".mjs" and inability to run typescript directly. however, using TypeDoc in that scenario will require a bit of configuration, which takes away the benefits of smaller codebase. plus, extending the library will probably require the use of deno, or a node adapter will be need.

utility.ts

• 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)) + "]"
}

• 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]

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

schema_codec.ts

• 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

• 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