url-safe-bitpacking 0.2.0 → 0.3.0

package/README.md

@@ -2,7 +2,7 @@
 
 Package for creating definitions of parametric models that can be stored as compactly as possible in a URL by storing it in a web-safe base-64 string. This pacakge is till very much WIP. Feel free to suggest by making an issue or pull-request [GitHub](https://github.com/JonasWard/url-safe-bitpacking).
 
-### goal for version 0.2
+### goal for 1.0
 
 | what                                                 | code     | tests    | docs     |
 | ---------------------------------------------------- | -------- | -------- | -------- |
@@ -19,65 +19,25 @@ Package for creating definitions of parametric models that can be stored as comp
 
 The goal of this library is to offer a flexible, minimal and, variable object definition that can be stored in the browser URL. The main imagined use-case is parametric models that have nested and variable sub-object definitions. The library heavily relies on the bitpacking of custom bitwidth numeric values. Because of that, the biggest trade-off for this library is legibility. Without the related object definition, it would be impossible to reconstruct the state. The big advantage though is the ability to store rather many variables in a very condensed URL, allowing to store all information in rather short urls which then can be used for qr code generation.
 
-## bit-level data types
-
-Currently, there are 4 data types implemented (+1 special case for safety). All data entries have a name that will behave as an attribute name in the object.
-
-### bool
-
-Bool type values are simple yes or no, 1 or 0s, nothing special
-
-```typescript
-DataEntryFactory.createBoolean(false, 'shapePreProcessingWarpabsolute');
-```
-
-### enum
-
-An enum in this context is a continuous array of integers. The Bitwidth of this data type is defined by the maximum entry. eg. in case you you would need 21 states, the larges value would be 20. The value 20 would require at least five bits (log2(20) ~ 4.32). The maximum bitwidth for enums is right now hardcoded to 8-bit (which would be the range [0, 255] ).
-
-```typescript
-DataEntryFactory.createEnum(0, 3, 'footprintType');
-```
-
-### int
-
-An int type is rather similar to the enum, except that it starts at a specific minimum value. The range that then needs to be able to be stored is: max - min. In case you would need values from -30 to 10, you would have to be able to store 10 - 30 + 1 = 51 states. This would require a bitwidth of 6 (log2(51) ~ 5.67). The max bitwidth is now hardcoded to be 12 (which would be the range [minimum, 4095 - minimum])
-
-```typescript
-DataEntryFactory.createInt(5, 3, 20, 'circleDivisions');
-```
-
-### float
-
-Floating points work very much like the integer type, with the main difference that one can also define a precision to define at what order of magnitude (from -3 to +3) the variable should be considered. The significand can be up to 20 bits, which eg. at precision -3 would allow a range of .001 to 1048.576.
-
-```typescript
-DataEntryFactory.createFloat(20, 10, 200, -1, 'shapePreProcessingWarptotal');
-```
-
-### enum array
-
-Enum arrays are a special type of arrays where integer values are intepreted as being values of a **specific base** to then be transformed to base 2. The base is derived from the delta of the max `and` the `min` value of the enums. Besides that, there is also a `minCount` and `maxCount` value (which can be the same value, but `minCount` is at least 1). This only offers a compression rate of upto 22% vis-a-vis an array of `IntDataEntry` (worst case its 0% percent, it never takes up more space), so sometimes questionable whether it makese sense to use ^^.
-
-```typescript
-DataEntryFactory.createEnumArray([0, 1, 2], 0, 10, 3, 5, 'enumArrayA')    
-```
-
-### version
-
-There is also a Version object which is a special case of the enum data type and has a bitwidth of 4, 6, 8 or, 10 and always occupies the first bits of the bitarray.
-
-```typescript
-DataEntryFactory.createVersion(0, 8, 'version');
-```
-
-## nested attribute definitions
-
-More often than not in parametric models, certain data belongs together. It can also happen that the specific state of some values will have an impact on other ones being present (or which ranges are allowed). To be able to deal with this there is the option to nest data. I tried to come with an as concise yet versatile way of defining the object definitions.
-
-### single nes
-
-For the Double Nested arrays there are currently two variations: either an Optional type, which only accepts two values of which is an empty array and will be toggle on/off in relation to a certain boolean data entry.
+# Types defined in `url-safe-bitpacking`
+`url-safe-bitpacking` stores the state of an object according to its definition (`descriptor`) into memory (for now using a `bitstring`, a string consisting of `0` and `1`s, parsed into a `base64` string). Attributes of the object are packed according to their specific `bitwidths`, the amount of bits they take up in memory.
+
+From a memory footprint perspective there are two types of attributes in an object defintion. Those that have a definition that gives them a `fixed` bitwidth and those that have a `variable` bitwidth. For the **variable** ones the state of its value will have an impact on the memory footprint of the object. For the **fixed** types, their definition defines their memory footprint. Some of the objects with a **variable** footprint have some state to them, which informs how the state should be parsed. The size of this state is defined by the **descriptor** of the object.
+
+|                          | VERSION     | BOOLEAN     | ENUM        | INT         | FLOAT       | ENUM_ARRAY     | OPTIONAL     | ENUM_OPTIONS     | ARRAY       | OBJECT      |
+| ------------------------ | ----------- | ----------- | ----------- | ----------- | ----------- | -------------- | ------------ | ---------------- | ----------- | ----------- |
+| Predefined Bitwidth      | **✓** | **✓** | **✓** | **✓** | **✓** | ✗        | ✗      | ✗          | ✗     | ✗     |
+| Has State Bit            | ✗     | ✗     | ✗     | ✗     | ✗     | **✓**    | **✓**  | **✓**      | **✓** | ✗     |
+| Min Bitwidth             | `4`         | `1`         | `1`         | `0`         | `0`         | `1`            | –            | –                | –           | –           |
+| Max Bitwidth             | `10`        | `1`         | `10`        | `21`        | `21`        | `10`           | –            | –                | –           | –           |
+| Min State Bitwidth       | –           | –           | –           | –           | –           | `0`            | `1`          | `1`              | `0`         | –           |
+| Max State Bitwidth       | –           | –           | –           | –           | –           | `10`           | `1`          | `10`             | `10`        | –           |
+| Max Available States     | `1024`      | `2`         | `1024`      | `2097152`   | `2097152`   | `1024 x 1024`  | `2`          | `1024`           | `1024`      | `0`         |
+| Has Mapping              | ✗     | ✗     | **✓** | ✗     | ✗     | **✓**    | ✗      | **✓**      | ✗     | ✗     |
+| Has Nested Objects       | ✗     | ✗     | ✗     | ✗     | ✗     | ✗        | **✓**  | **✓**      | **✓** | **✓** |
+| **UPDATING**             | **VERSION** | **BOOLEAN** | **ENUM**    | **INT**     | **FLOAT**   | **ENUM_ARRAY** | **OPTIONAL** | **ENUM_OPTIONS** | **ARRAY**   | **OBJECT**  |
+| Requires Value on Update | **✓** | **✓** | **✓** | **✓** | **✓** | **✓**    | **✗**  | **✗**      | **✗** | **✗** |
+| Requires State on Update | –           | –           | –           | –           | –           | **✗**    | **✓**  | **✓**      | **✓** | –           |
 
 # Install
 

package/dist/enums/dataTypes.d.ts

@@ -1,4 +1,16 @@
-export declare const DataTypeValues: readonly ["VERSION", "BOOLEAN", "ENUM", "INT", "FLOAT", "ENUM_ARRAY"];
-export declare const ComplexDataValues: readonly ["OPTIONAL", "ENUM_OPTIONS", "ARRAY"];
-export type DataType = (typeof DataTypeValues)[number];
-export type ComplexDataType = (typeof ComplexDataValues)[number];
+import { DataEntry } from '../types';
+export declare const ConstantBitWidthDataTypes: readonly ["VERSION", "BOOLEAN", "ENUM", "INT", "FLOAT"];
+export declare const VariableBitWidthDataTypes: readonly ["ENUM_ARRAY", "OPTIONAL", "ENUM_OPTIONS", "ARRAY", "OBJECT"];
+export declare const HasMappingDataTypes: readonly ["ENUM", "ENUM_ARRAY", "ENUM_OPTIONS"];
+export declare const HasStateBitsDataTypes: readonly ["ENUM_ARRAY", "OPTIONAL", "ENUM_OPTIONS", "ARRAY"];
+export declare const HasChildDataTypes: readonly ["OPTIONAL", "ENUM_OPTIONS"];
+export declare const HasChildrenDataTypes: readonly ["ARRAY", "OBJECT"];
+export declare const HasNestedDataTypes: readonly ["OPTIONAL", "ENUM_OPTIONS", "ARRAY", "OBJECT"];
+export declare const ValueUpdateDataTypes: readonly ["VERSION", "BOOLEAN", "ENUM", "INT", "FLOAT", "ENUM_ARRAY"];
+export declare const StateUpdateDataTypes: readonly ["OPTIONAL", "ENUM_OPTIONS", "ARRAY"];
+export type ValueUpdateType = (typeof ValueUpdateDataTypes)[number];
+export type StateUpdateType = (typeof StateUpdateDataTypes)[number];
+export type DataType = (typeof ConstantBitWidthDataTypes)[number] | (typeof VariableBitWidthDataTypes)[number];
+export type SpecifiedDataEntry<T extends DataType> = DataEntry & {
+    type: T;
+};

package/dist/factory/arrayFactory.d.ts

@@ -1,2 +1,3 @@
-import { ArrayDataEntry, NestedData } from '@/types';
-export declare const create: (descriptor: NestedData, defaultState?: number, minCount?: number, maxCount?: number, name?: string, index?: number) => ArrayDataEntry;
+import { ArrayDataEntry } from '../types';
+export type ArrayFactory = (descriptor: ArrayDataEntry['descriptor'], defaultState?: number, minCount?: number, maxCount?: number, name?: string) => ArrayDataEntry;
+export declare const create: ArrayFactory;

package/dist/factory/booleanFactory.d.ts

@@ -1,2 +1,3 @@
 import { BooleanDataEntry } from '../types';
-export declare const create: (value: boolean, name?: string, index?: number) => BooleanDataEntry;
+export type BooleanFactory = (value: boolean, name?: string) => BooleanDataEntry;
+export declare const create: BooleanFactory;

package/dist/factory/enumArrayFactory.d.ts

@@ -1,2 +1,3 @@
-import { EnumArrayDataEntry } from '@/types';
-export declare const create: (value: number[], options: (string | number | object)[] | string | number, minCount?: number, maxCount?: number, name?: string, index?: number) => EnumArrayDataEntry;
+import { EnumArrayDataEntry, EnumOptionsType } from '../types';
+export type EnumArrayFactory = (value: number[], options: EnumOptionsType, minCount?: number, maxCount?: number, name?: string) => EnumArrayDataEntry;
+export declare const create: EnumArrayFactory;

package/dist/factory/enumFactory.d.ts

@@ -1,2 +1,4 @@
 import { EnumDataEntry } from '../types';
-export declare const create: (value: number, options: (string | number | object)[] | string | number, name?: string, index?: number) => EnumDataEntry;
+import { EnumOptionsType } from '../types/enumData';
+export type EnumFactory = (value: number, options: EnumOptionsType, name?: string) => EnumDataEntry;
+export declare const create: EnumFactory;

package/dist/factory/enumOptionsFactory.d.ts

@@ -1,2 +1,3 @@
-import { EnumOptionsDataEntry, NestedData } from '@/types';
-export declare const create: (descriptor: NestedData[], defaultState?: number, name?: string, index?: number) => EnumOptionsDataEntry;
+import { DataEntry, EnumOptionsDataEntry, EnumOptionsType } from '../types';
+export type EnumOptionsFactory = (descriptor: (DataEntry | null)[], defaultState?: number, name?: string, options?: EnumOptionsType) => EnumOptionsDataEntry;
+export declare const create: EnumOptionsFactory;

package/dist/factory/factory.d.ts

@@ -7,19 +7,21 @@ import { create as createEnumArray } from './enumArrayFactory';
 import { create as createOptional } from './optionalFactory';
 import { create as createEnumOptions } from './enumOptionsFactory';
 import { create as createArray } from './arrayFactory';
+import { create as createObject } from './objectFactory';
+import { DataEntry, ObjectDataEntry, VersionDataEntry } from '../types';
 /**
  * Record containing all the factory methods for the different data entry objects
  */
-export declare const DataEntryFactory: {
-    createFloat: typeof createFloat;
-    createInt: typeof createInt;
-    createEnum: typeof createEnum;
-    createBoolean: typeof createBoolean;
-    createVersion: typeof createVersion;
-    createEnumArray: typeof createEnumArray;
-};
-export declare const ComplexDataEntryFactory: {
-    createOptional: typeof createOptional;
-    createEnumOptions: typeof createEnumOptions;
-    createArray: typeof createArray;
+export declare const DescriptorFactory: {
+    FLOAT: typeof createFloat;
+    INT: typeof createInt;
+    ENUM: typeof createEnum;
+    BOOLEAN: typeof createBoolean;
+    VERSION: typeof createVersion;
+    ENUM_ARRAY: typeof createEnumArray;
+    OPTIONAL: typeof createOptional;
+    ENUM_OPTIONS: typeof createEnumOptions;
+    ARRAY: typeof createArray;
+    OBJECT: typeof createObject;
 };
+export declare const StateDescriptorFactoryMethod: (descriptor: [VersionDataEntry, ...DataEntry[]], name?: string) => ObjectDataEntry;

package/dist/factory/floatFactory.d.ts

@@ -1,5 +1,6 @@
 import { FloatDataEntry } from '../types';
 import { PrecisionRangeType } from '../types/floatData';
+export type FloatFactory = (value: number, min?: number, max?: number, precision?: PrecisionRangeType, name?: string) => FloatDataEntry;
 /**
  * Method to create a float data entry
  * @param value - `number` default value, should be between `min` and `max`
@@ -7,6 +8,5 @@ import { PrecisionRangeType } from '../types/floatData';
  * @param max - `number` (default: 1), should be larger than `min`
  * @param precision - `PrecisionRangeType` (default: 2 -> .01),
  * @param name - `string`
- * @param index - `number`
  */
-export declare const create: (value: number, min?: number, max?: number, precision?: PrecisionRangeType, name?: string, index?: number) => FloatDataEntry;
+export declare const create: FloatFactory;

package/dist/factory/intFactory.d.ts

@@ -1,2 +1,3 @@
 import { IntDataEntry } from '../types';
-export declare const create: (value: number, min?: number, max?: number, name?: string, index?: number) => IntDataEntry;
+export type IntFactory = (value: number, min?: number, max?: number, name?: string) => IntDataEntry;
+export declare const create: IntFactory;

package/dist/factory/objectFactory.d.ts

@@ -0,0 +1,3 @@
+import { DataEntry, ObjectDataEntry } from '../types';
+export type ObjectFactory = (descriptor: DataEntry[], name?: string) => ObjectDataEntry;
+export declare const create: ObjectFactory;

package/dist/factory/optionalFactory.d.ts

@@ -1,2 +1,3 @@
-import { NestedData, OptionalDataEntry } from '@/types';
-export declare const create: (descriptor: [null, NestedData] | [NestedData, null], defaultState?: boolean, name?: string, index?: number) => OptionalDataEntry;
+import { DataEntry, OptionalDataEntry } from '../types';
+export type OptionalFactory = (descriptor: [DataEntry, null] | [null, DataEntry], defaultState?: boolean, name?: string) => OptionalDataEntry;
+export declare const create: OptionalFactory;

package/dist/factory/utils.d.ts

@@ -1,9 +1,19 @@
+import { EnumMappingType, EnumOptionsType } from '../types';
 /**
  * Method to get the max and mapping from the options
  * @param options - `any[] | string | number` the options to get the max and mapping from
  * @returns `{ max: number; mapping: any[] }` the max and mapping
  */
-export declare const getOptionsFromEnumOptions: (options: (string | number | object)[] | string | number) => {
+export declare const getEnumMaxAndMappingFromOptions: (options: EnumOptionsType) => {
     max: number;
-    mapping: (string | number | object)[];
+    mapping: EnumMappingType;
 };
+/**
+ * Method to get the options from the max and mapping of an ENUM & ENUM_ARRAY type
+ * @param v - `{ max: number; mapping: EnumMappingType }` the max and mapping to get the options from
+ * @returns `EnumOptionsType` the options
+ */
+export declare const getOptionsFromMaxAndMapping: (v: {
+    max: number;
+    mapping: EnumMappingType;
+}) => EnumOptionsType;

package/dist/factory/versionFactory.d.ts

@@ -1,3 +1,4 @@
 import { VersionDataEntry } from '../types';
 import { VersionRangeType } from '../types/versionData';
-export declare const create: (value: number, bits?: VersionRangeType, name?: string, index?: number) => VersionDataEntry;
+export type VersionFactory = (value: number, bits?: VersionRangeType, name?: string) => VersionDataEntry;
+export declare const create: VersionFactory;

package/dist/index.d.ts

@@ -1,6 +1,6 @@
-export { DataType, DataTypeValues, ComplexDataType, ComplexDataValues } from './enums';
-export { DataEntryFactory, ComplexDataEntryFactory } from './factory';
-export { PrecisionRangeType, SignificandMaxBits, FloatDataEntry, IntegerMaxBits, IntDataEntry, EnumDataEntry, EnumArrayDataEntry, VersionRangeType, VersionDataEntry, BooleanDataEntry, DataEntry, ComplexDataEntry, NestedData, ProtectedAttributeNames, StateDescriptor, StateObject, StateDataObject, StateDataEntry, State, PROTECTED_ATTRIBUTE_NAMES } from './types';
-export { parseBase64ToBits, getBitsCount, valueBitsParser, dataBitsParser, dataEntryBitstringParser, dataBitsStringifier, dataEntryCorrecting } from './parsers';
-export { createStateDataObject, getInitialStateFromBase64 } from './stateHandling';
+export { DataType, ConstantBitWidthDataTypes, VariableBitWidthDataTypes } from './enums';
+export { PrecisionRangeType, SignificandMaxBits, FloatDataEntry, IntegerMaxBits, IntDataEntry, EnumDataEntry, EnumArrayDataEntry, VersionRangeType, VersionDataEntry, BooleanDataEntry, DataEntry, ProtectedAttributeNames, EnumOptionsType, EnumMappingType, PROTECTED_ATTRIBUTE_NAMES } from './types';
+export { getBitsCount, dataEntryBitstringParser, dataEntryCorrecting, dataEntryBitsStringifier, parseBase64ToBits } from './parsers';
+export { SpecificTypeNode, NodeFactory, GetStateNodeTree, FromState, ArrayNode, BooleanNode, EnumNode, IntNode, FloatNode, EnumArrayNode, OptionalNode, EnumOptionsNode, ObjectNode, StateNode } from './stateHandling';
 export { interpolateEntryAt, getRelativeValue } from './utils';
+export { getEnumMaxAndMappingFromOptions, getOptionsFromMaxAndMapping } from './factory/utils';