implementation, tests, readme

Author: dested

.gitignore

@@ -0,0 +1,24 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+/.pnp
+.pnp.js
+.idea
+# testing
+/coverage
+
+# production
+/build
+
+# misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+

.prettierrc

@@ -0,0 +1,8 @@
+{
+  "tabWidth":2,
+  "singleQuote":true,
+  "printWidth":120,
+  "bracketSpacing":false,
+  "trailingComma": "es5",
+  "endOfLine": "auto"
+}

LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 Jenny Louthan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1 +1,249 @@
-"# safe-schema" 
+# Safe Schema
+
+A dependencies-less solution to **safely** serialize your TypeScript models to and from `ArrayBuffer`s.
+
+## Features
+
+- Uses your TypeScript object definitions as a starting point
+- Type Safe throughout
+- Broad model support
+- Lightning Fast due to AOT
+- First class support for Type Lookups and Enums
+- Well tested
+- No external dependencies
+
+## Install
+
+With npm:
+
+```
+$ npm install safe-schema --save
+```
+
+With yarn:
+
+```
+$ yarn add safe-schema
+```
+
+## Basic Usage
+
+### Node
+
+```ts
+// Import 
+import {SafeSchema, SchemaDefiner} from 'safe-schema';
+
+
+// Define your model
+type SimpleMessage = {count: number};
+
+// Safely define your schema BASED on your model
+const SimpleMessageSchema: SafeSchema<SimpleMessage> = {count: 'uint8'};
+
+...
+
+// Initialize the AOT code generator (only once)
+const generator = SchemaDefiner.generate<SimpleMessage>(SimpleMessageSchema);
+
+// Turn your object into an ArrayBuffer
+const buffer = SchemaDefiner.toBuffer({count: 12}, generator);
+
+assert(buffer.byteLength === 1)
+...
+
+// Turn your ArrayBuffer back into your object
+const result = SchemaDefiner.fromBuffer(buffer, generator);
+
+
+// Use your 100% type safe object on the other side of the wire
+assert(result.count === 12)
+
+```
+
+## How It Works
+
+You define your network schema just as you normally would using TypeScript types, then use `SafeSchema` to generate a runtime version of that schema. You will get full intellisense support when defining `SafeSchema<SimpleMessage>`, allowing you to easily define the DataTypes of your model (for instance `number` as `uint16`), as well as the ability to easily **change your schema** and have TypeScript throw the appropriate errors for missing values at compile time.
+
+Calling `SchemaDefiner.generate<SimpleMessage>(SimpleMessageSchema)` generates JavaScript **at runtime** that is hand built to read and write your model to and from an `ArrayBuffer`. There is no switch case behind the scenes, every model generates unique JavaScript which executes **lightning fast**! Only exactly as many bytes will be sent over the wire as needed.
+
+Take a look at the [kitchenSink](__tests__/kitchenSink.ts), and the other tests for complex and realworld examples.
+
+## Why It's Needed
+
+Every other solution to this problem (protocol buffers, JSON, etc), did not allow me to define my models the way I wanted to, **using TypeScript**. TypeScript's modeling abilities are incredibly feature rich and I did not want to lose any of that functionality just because I needed to serialize my data. That's why I built in first class support for things like Discriminating Unions and Enums, so I can have a richly defined schema with the minimum amount of bytes used.
+
+
+## API Documentation
+
+- [`numbers`](#numbers)
+- [`string`](#string)
+- [`boolean`](#boolean)
+- [`optional`](#optional)
+- [`array`](#array)
+- [`type-lookup`](#type-lookup)
+- [`enum`](#enum)
+- [`bitmask`](#bitmask)
+
+### numbers
+<a name="numbers" />
+
+When you define your model to be a number in TypeScript you must tell the Schema what type and how big the number is. This is to save on memory over the wire and to not make assumptions.
+
+Example:
+
+```ts
+type SimpleMessage = {count: number};
+
+const SimpleMessageSchema: SafeSchema<SimpleMessage> = {count: 'int32'};
+```
+
+TypeScript intellisense will only allow values that are valid. The valid values are:
+
+- `uint8`
+- `uint16`
+- `uint32`
+- `int8`
+- `int16`
+- `int32`
+- `float32`
+- `float64`
+
+### string
+<a name="string" />
+
+SafeSchema encodes strings into utf16 values, plus one uint16 for its length. It does not currently support strings over 65535 in length.
+
+Example:
+
+```ts
+type SimpleMessage = {count: string};
+
+const SimpleMessageSchema: SafeSchema<SimpleMessage> = {count: 'string'};
+```
+
+### boolean
+<a name="boolean" />
+
+SafeSchema encodes booleans into a single uint8 value
+
+Example:
+
+```ts
+type SimpleMessage = {count: boolean};
+
+const SimpleMessageSchema: SafeSchema<SimpleMessage> = {count: 'boolean'};
+```
+
+
+### optional
+<a name="optional" />
+
+SafeSchema allows any value to be optionally defined. This will send an extra byte over the wire to denote if the value is there or not. The type must be defined as optional in your model
+
+Example:
+
+```ts
+type SimpleMessage = {count?: number};
+
+const SimpleMessageSchema: SafeSchema<SimpleMessage> = {
+  count: {
+    flag: 'optional',
+    element: 'uint8',
+  },
+};
+```
+
+### array
+<a name="array" />
+
+SafeSchema can encode any type as an array. You must specify the max length of the array, either `array-uint8` or `array-uint16`
+
+Example:
+
+```ts
+type SimpleMessage = {count: boolean[]};
+const SimpleMessageSchema: SafeSchema<SimpleMessage> = {
+  count: {
+    flag: 'array-uint8',
+    elements: 'boolean',
+  },
+};
+```
+
+```ts
+type ComplexMessage = {count: {shoes: number}[]};
+const ComplexMessageSchema: SafeSchema<ComplexMessage> = {
+  count: {
+    flag: 'array-uint8',
+    elements: {shoes: 'float64'},
+  },
+};
+
+```
+
+### type-lookup
+<a name="type-lookup" />
+
+SafeSchema has first class support for type lookups. This is useful for Discriminating Unions in TypeScript.
+
+Example:
+
+```ts
+type SimpleMessage = {type: 'run'; duration: number} | {type: 'walk'; speed: number};
+
+const SimpleMessageSchema: SafeSchema<SimpleMessage> = {
+  flag: 'type-lookup',
+  elements: {
+    run: {duration: 'uint8'},
+    walk: {speed: 'float32'},
+  },
+}
+```
+
+### enum
+<a name="enum" />
+
+SafeSchema has first class support TypeScript enums through string unions. It will only send a single byte over the wire.
+
+Example:
+
+```ts
+type SimpleMessage = {weapon:'sword'|'laser'|'shoe'};
+
+const SimpleMessageSchema: SafeSchema<SimpleMessage> = {
+  flag: 'enum',
+  sword: '0',
+  laser: '1',
+  shoe: '2',
+}
+```
+
+### bitmask
+<a name="bitmask" />
+
+In rare cases you may want to send a bitmasked value over the wire. You define this as a single object that **only has boolean values**. It will send a single byte over the wire, and be serialized back into the complex object.
+
+Example:
+
+```ts
+type BitMaskMessage = {
+  switcher: {
+    up: boolean;
+    down: boolean;
+    left: boolean;
+    right: boolean;
+  };
+};
+
+const BitMaskMessageSchema: SafeSchema<BitMaskMessage> = {
+  switcher: {
+    flag: 'bitmask',
+    up: 0,
+    down: 1,
+    left: 2,
+    right: 3,
+  },
+};
+
+```

__tests__/arrayLookup.ts

@@ -0,0 +1,69 @@
+import {SafeSchema, SchemaDefiner} from '../src';
+
+type Uint8ArrayMessage = {count: number[]};
+const Uint8ArrayMessageSchema: SafeSchema<Uint8ArrayMessage> = {
+  count: {
+    flag: 'array-uint8',
+    elements: 'uint32',
+  },
+};
+
+test('array unit8 test', async () => {
+  const generator = SchemaDefiner.generate<Uint8ArrayMessage>(Uint8ArrayMessageSchema);
+
+  const buffer = SchemaDefiner.toBuffer({count: [12, 24]}, generator);
+  expect(buffer.byteLength).toEqual(4 * 2 + 1);
+
+  const result = SchemaDefiner.fromBuffer(buffer, generator);
+  expect(result.count).toEqual([12, 24]);
+});
+
+type Uint16ArrayMessage = {count: number[]};
+const Uint16ArrayMessageSchema: SafeSchema<Uint16ArrayMessage> = {
+  count: {
+    flag: 'array-uint16',
+    elements: 'uint32',
+  },
+};
+
+test('array unit8 test', async () => {
+  const generator = SchemaDefiner.generate<Uint16ArrayMessage>(Uint16ArrayMessageSchema);
+
+  const buffer = SchemaDefiner.toBuffer({count: [12, 24]}, generator);
+  expect(buffer.byteLength).toEqual(4 * 2 + 2);
+
+  const result = SchemaDefiner.fromBuffer(buffer, generator);
+  expect(result.count).toEqual([12, 24]);
+});
+
+type Uint8ArrayObjectMessage = {count: {shoes: boolean; count: number}[]};
+const Uint8ArrayObjectMessageSchema: SafeSchema<Uint8ArrayObjectMessage> = {
+  count: {
+    flag: 'array-uint8',
+    elements: {
+      count: 'uint8',
+      shoes: 'boolean',
+    },
+  },
+};
+
+test('array unit8 object test', async () => {
+  const generator = SchemaDefiner.generate<Uint8ArrayObjectMessage>(Uint8ArrayObjectMessageSchema);
+
+  const buffer = SchemaDefiner.toBuffer(
+    {
+      count: [
+        {shoes: true, count: 12},
+        {shoes: false, count: 34},
+      ],
+    },
+    generator
+  );
+  expect(buffer.byteLength).toEqual((1 + 1) * 2 + 1);
+
+  const result = SchemaDefiner.fromBuffer(buffer, generator);
+  expect(result.count).toEqual([
+    {shoes: true, count: 12},
+    {shoes: false, count: 34},
+  ]);
+});