ya-struct 0.0.5 → 0.0.6

package/.editorconfig

@@ -0,0 +1,8 @@
+root = true
+
+[*]
+end_of_line = lf
+insert_final_newline = true
+indent_style = space
+indent_size = 2
+trim_trailing_whitespace = true

package/.github/workflows/ci.yml

@@ -0,0 +1,23 @@
+name: CI
+
+on: [push, pull_request]
+
+jobs:
+  ci:
+    runs-on: ubuntu-latest
+    name: Continous integration tests
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '24'
+      - name: Install libc6-dev-i386
+        run: sudo apt-get update && sudo apt-get install -y libc6-dev-i386
+      - name: Install dependencies
+        run: npm ci
+      - name: Build
+        run: npm run build
+      - name: Run tests
+        run: npm run test
+      - name: Verify code with linter
+        run: npm run lint

package/.github/workflows/npm-publish.yml

@@ -0,0 +1,28 @@
+name: Publish Package to npmjs
+on:
+  push:
+    tags:
+      - '*'
+
+permissions:
+  id-token: write  # Required for OIDC
+  contents: read
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      # Setup .npmrc file to publish to npm
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '24'
+          registry-url: 'https://registry.npmjs.org'
+      - run: npm ci
+      - run: npm run build
+      - run: node node_modules/.bin/releasetool merge --local-package-json package.json --npm-package-json package.npm.json --output package.json
+      - run: node node_modules/.bin/releasetool patch-version --package-json package.json --package-version ${{ github.ref_name }}
+      - run: npm publish

package/README.md

@@ -1,24 +1,156 @@
 # node-ya-struct
-Yet Another Node.js Structure API
 
+Yet Another Node.js Structure API - A TypeScript library for defining, parsing, and formatting binary data structures with precise control over memory layout, alignment, and ABI compatibility.
 
-## About
-This module allows you to parse and format fixed C-like data structures. Mainly this can be used for native code interoperability, network communication or file formats. The goal is to support types and alignments similar to C structures with support for endianness.
+## Overview
 
-## API
-TBD
+`node-ya-struct` provides a type-safe way to work with binary data structures in Node.js. It handles complex memory layout calculations including padding, alignment, and platform-specific differences (data models, endianness, compilers). The library is particularly useful for:
+
+- Interfacing with native C libraries and system APIs
+- Parsing binary file formats
+- Working with hardware interfaces and low-level protocols
+- Cross-platform binary data serialization
 
 ## Features
-- Basic Integer type support
-- Buffer referencing - buffers can be used as pointers, including garbage collection protection
-- Endianness support
-
-## Planned Features
-- Nested structures
-- Nested arrays
-- C strings as arrays
-- C strings as pointers
-- Basic C types
-- Bitfields
-- Unions
-- Field alignments
+
+- **Type-safe definitions** - Full TypeScript support with inferred types for parsed values
+- **Multiple data models** - Support for LP64 (64-bit Unix) and ILP32 (32-bit) data models
+- **Packed structs** - Support for packed structures without padding
+- **Endianness control** - Little and big endian support
+- **Zero dependencies** - Pure TypeScript implementation
+
+## Installation
+
+```bash
+npm install ya-struct
+```
+
+## Quick Start
+
+```typescript
+import { define, types } from "ya-struct";
+
+// Define a struct
+const def = define({
+  definition: {
+    type: "struct",
+    packed: false,
+    fixedAbi: {},
+    fields: [
+      { name: "a", definition: types.Int16 },
+      { name: "b", definition: types.UInt16 },
+      { name: "c", definition: types.UInt32 },
+    ]
+  }
+});
+
+// Create a parser with specific ABI settings
+const parser = def.parser({
+  abi: {
+    endianness: "little",
+    dataModel: "LP64",
+    compiler: "gcc",
+  }
+});
+
+// Parse binary data
+const value = {
+  a: 0n,
+  b: 1n,
+  c: 2n,
+};
+
+// Format to binary
+const buffer = parser.format({ value });
+
+// Parse back
+const parsed = parser.parse({ data: buffer });
+```
+
+## API
+
+### `define({ definition })`
+
+Creates a struct definition that can be used to create parsers with specific ABI settings.
+
+**Parameters:**
+- `definition` - A struct definition object
+
+**Returns:** An object with a `parser()` method
+
+### `parser({ abi })`
+
+Creates a parser for the defined structure with specific ABI settings.
+
+**Parameters:**
+- `abi.endianness` - `"little"` or `"big"`
+- `abi.dataModel` - `"LP64"` (64-bit Unix/Linux) or `"ILP32"` (32-bit)
+- `abi.compiler` - `"gcc"` (currently supported)
+
+**Returns:** Parser object with:
+- `size` - Size of the structure in bytes
+- `parse({ data })` - Parse binary data to JavaScript values
+- `format({ value })` - Format JavaScript values to binary data
+- `layout` - Detailed memory layout information
+
+### Built-in Types
+
+Available via `types` export:
+
+- **Integers:** `Int16`, `UInt16`, `Int32`, `UInt32`, `Int64`, `UInt64`
+- **Strings:** `ascii({ length })` - Fixed-length null-terminated ASCII strings
+- **Pointers:** `pointer` - Platform-specific pointer size
+
+### Custom Types
+
+You can define custom field types:
+
+```typescript
+const definition = {
+  type: "struct",
+  packed: false,
+  fixedAbi: {},
+  fields: [
+    {
+      name: "myField",
+      definition: {
+        type: "integer",
+        sizeInBits: 32,
+        signed: true,
+        fixedAbi: {}
+      }
+    }
+  ]
+} as const;
+```
+
+Supported type kinds:
+- `integer` - Custom integer with specified bit width
+- `float` - Floating point numbers
+- `pointer` - Pointer types
+- `array` - Fixed-length arrays
+- `struct` - Nested structures
+- `string` - Fixed-length strings
+- `c-type` - Native C types (char, int, long, etc.)
+
+## Data Models
+
+The library supports different C data models:
+
+- **LP64** - Used on 64-bit Unix/Linux systems (long and pointer are 64-bit)
+- **ILP32** - Used on 32-bit systems (int, long, and pointer are 32-bit)
+
+## Packed Structures
+
+Set `packed: true` in your struct definition to disable padding and alignment:
+
+```typescript
+const def = define({
+  definition: {
+    type: "struct",
+    packed: true,  // No padding between fields
+    fixedAbi: {},
+    fields: [...]
+  }
+});
+```

package/dist/lib/common.d.ts

@@ -0,0 +1,14 @@
+type TDataModel = "LP64" | "ILP32";
+type TCompiler = "gcc";
+type TEndianness = "little" | "big";
+type TAbi = {
+    endianness: TEndianness;
+    compiler: TCompiler;
+    dataModel: TDataModel;
+};
+declare const align: ({ offset, alignment }: {
+    offset: number;
+    alignment: number;
+}) => number;
+export type { TDataModel, TCompiler, TEndianness, TAbi };
+export { align };

package/dist/lib/common.js

@@ -0,0 +1,30 @@
+/*type TDataModel = "LP64" | "ILP32";*/
+/*type TCompiler = "gcc";*/
+/*type TEndianness = "little" | "big";*/
+
+/*type TAbi = {
+  endianness: TEndianness;
+  compiler: TCompiler;
+  dataModel: TDataModel;
+};*/
+
+const align = ({ offset, alignment }/*: { offset: number; alignment: number }*/)/*: number*/ => {
+  const remainder = offset % alignment;
+  if (remainder === 0) {
+    return offset;
+  }
+
+  return offset + (alignment - remainder);
+};
+
+/*export type {
+  TDataModel,
+  TCompiler,
+  TEndianness,
+
+  TAbi
+};*/
+
+export {
+  align
+};

package/dist/lib/index.d.ts

@@ -0,0 +1,5 @@
+import { define } from "./parser.js";
+import { types } from "./types/index.js";
+import type { TAbi, TCompiler, TDataModel, TEndianness } from "./common.js";
+export { define, types };
+export type { TAbi, TEndianness, TCompiler, TDataModel };

package/dist/lib/index.js

@@ -0,0 +1,21 @@
+import { define } from "./parser.js";
+import { types } from "./types/index.js";
+
+/*import type {
+  TAbi,
+  TCompiler,
+  TDataModel,
+  TEndianness,
+} from "./common.ts";*/
+
+export {
+  define,
+  types
+};
+
+/*export type {
+  TAbi,
+  TEndianness,
+  TCompiler,
+  TDataModel
+};*/

package/dist/lib/layout.d.ts

@@ -0,0 +1,48 @@
+import { type TAbi } from "./common.js";
+import type { TFieldType } from "./types/index.js";
+type TLayoutedField = {
+    readonly type: "integer";
+    readonly offsetInBits: number;
+    readonly sizeInBits: number;
+    readonly signed: boolean;
+    readonly fixedAbi: Partial<TAbi>;
+} | {
+    readonly type: "float";
+    readonly offsetInBits: number;
+    readonly sizeInBits: number;
+    readonly fixedAbi: Partial<TAbi>;
+} | {
+    readonly type: "pointer";
+    readonly offsetInBits: number;
+    readonly sizeInBits: number;
+    readonly fixedAbi: Partial<TAbi>;
+} | {
+    readonly type: "array";
+    readonly elementType: TLayoutedField;
+    readonly length: number;
+    readonly offsetInBits: number;
+    readonly sizeInBits: number;
+} | {
+    readonly type: "struct";
+    readonly offsetInBits: number;
+    readonly sizeInBits: number;
+    readonly fields: readonly {
+        readonly name: string;
+        readonly definition: TLayoutedField;
+    }[];
+    readonly packed: boolean;
+    readonly fixedAbi: Partial<TAbi>;
+} | {
+    readonly type: "string";
+    readonly charSizeInBits: number;
+    readonly length: number;
+    readonly offsetInBits: number;
+    readonly sizeInBits: number;
+};
+declare const layout: ({ definition, abi, currentOffsetInBits }: {
+    definition: TFieldType;
+    abi: TAbi;
+    currentOffsetInBits: number;
+}) => TLayoutedField;
+export { layout };
+export type { TLayoutedField };

package/dist/lib/layout.js

@@ -0,0 +1,262 @@
+import { align, /*type TAbi */} from "./common.js";
+import { createCTypeNormalizer } from "./types/c-types.js";
+/*import type { TFieldType } from "./types/index.ts";*/
+import nodeUtil from "node:util";
+
+/*type TLayoutedField = {
+  readonly type: "integer";
+  readonly offsetInBits: number;
+  readonly sizeInBits: number;
+  readonly signed: boolean;
+  readonly fixedAbi: Partial<TAbi>;
+} | {
+  readonly type: "float";
+  readonly offsetInBits: number;
+  readonly sizeInBits: number;
+  readonly fixedAbi: Partial<TAbi>;
+} | {
+  readonly type: "pointer";
+  readonly offsetInBits: number;
+  readonly sizeInBits: number;
+  readonly fixedAbi: Partial<TAbi>;
+} | {
+  readonly type: "array";
+  readonly elementType: TLayoutedField;
+  readonly length: number;
+  readonly offsetInBits: number;
+  readonly sizeInBits: number;
+} | {
+  readonly type: "struct";
+  readonly offsetInBits: number;
+  readonly sizeInBits: number;
+  readonly fields: readonly { readonly name: string; readonly definition: TLayoutedField }[];
+  readonly packed: boolean;
+  readonly fixedAbi: Partial<TAbi>;
+} | {
+  readonly type: "string";
+  readonly charSizeInBits: number;
+  readonly length: number;
+  readonly offsetInBits: number;
+  readonly sizeInBits: number;
+};*/
+
+const pointerSizeInBitsByDataModel = ({ dataModel }/*: { dataModel: TAbi["dataModel"] }*/)/*: number*/ => {
+  switch (dataModel) {
+    case "LP64":
+      return 64;
+    case "ILP32":
+      return 32;
+    default:
+      throw Error(`unsupported data model "${dataModel}" for pointer size determination`);
+  }
+};
+
+const layoutStruct = ({
+  definition,
+  abi,
+  currentOffsetInBits: initialOffsetInBits
+}/*: {
+  definition: TFieldType & { type: "struct" },
+  abi: TAbi,
+  currentOffsetInBits: number
+}*/)/*: TLayoutedField*/ => {
+
+  // TODO: implement alignment handling
+  const structAlignmentInBits = 64;
+  // const fieldAlignmentInBits = 64;
+  const fieldAlignmentInBits = 1;
+  const pointerSizeInBits = pointerSizeInBitsByDataModel({ dataModel: abi.dataModel });
+
+  let currentOffsetInBits = align({ offset: initialOffsetInBits, alignment: structAlignmentInBits });
+  let layoutedFields/*: (TLayoutedField & { type: "struct" })["fields"]*/ = [];
+
+  // eslint-disable-next-line max-statements,complexity
+  definition.fields.forEach((field) => {
+
+    let normalizedField/*: TFieldType*/ = field.definition;
+
+    if (field.definition.type === "c-type") {
+      const cTypeNormalizer = createCTypeNormalizer({ abi });
+      normalizedField = cTypeNormalizer.normalize({ cField: field.definition });
+    }
+
+    if (!definition.packed) {
+      switch (normalizedField.type) {
+        case "integer":
+        case "float": {
+          const sizeInBits = normalizedField.sizeInBits;
+
+          if (abi.compiler === "gcc" && abi.dataModel === "ILP32" && sizeInBits === 64) {
+            // special handling for gcc 64-bit integers on ILP32 data model (alignment to 32 bits)
+            currentOffsetInBits = align({ offset: currentOffsetInBits, alignment: 32 });
+          } else {
+            currentOffsetInBits = align({ offset: currentOffsetInBits, alignment: sizeInBits });
+          }
+
+          break;
+        }
+        case "string": {
+          // no special alignment needed
+          break;
+        }
+        case "pointer": {
+          currentOffsetInBits = align({ offset: currentOffsetInBits, alignment: pointerSizeInBits });
+          break;
+        }
+        default:
+          throw Error(`unsupported field type for struct layout: ${nodeUtil.inspect(field.definition)}`);
+      }
+    }
+
+    // eslint-disable-next-line no-use-before-define
+    const fieldLayout = layout({ definition: normalizedField, abi, currentOffsetInBits });
+
+    layoutedFields = [
+      ...layoutedFields,
+      {
+        name: field.name,
+        definition: fieldLayout
+      }
+    ];
+
+    currentOffsetInBits = align({ offset: fieldLayout.offsetInBits + fieldLayout.sizeInBits, alignment: fieldAlignmentInBits });
+  });
+
+  return {
+    type: "struct",
+    offsetInBits: initialOffsetInBits,
+    sizeInBits: currentOffsetInBits - initialOffsetInBits,
+    fields: layoutedFields,
+    packed: definition.packed,
+    fixedAbi: definition.fixedAbi
+  };
+};
+
+const layoutPrimitive = ({
+  definition,
+  abi,
+  currentOffsetInBits
+}/*: {
+  definition: TFieldType & ({ type: "integer" } | { type: "float" } | { type: "pointer" }),
+  abi: TAbi,
+  currentOffsetInBits: number
+}*/)/*: TLayoutedField*/ => {
+
+  if (definition.type === "integer") {
+    return {
+      type: "integer",
+      offsetInBits: currentOffsetInBits,
+      sizeInBits: definition.sizeInBits,
+      signed: definition.signed,
+      fixedAbi: definition.fixedAbi
+    };
+  }
+
+  if (definition.type === "float") {
+    return {
+      type: "float",
+      offsetInBits: currentOffsetInBits,
+      sizeInBits: definition.sizeInBits,
+      fixedAbi: definition.fixedAbi
+    };
+  }
+
+  const pointerSizeInBits = pointerSizeInBitsByDataModel({ dataModel: abi.dataModel });
+
+  return {
+    type: definition.type,
+    offsetInBits: currentOffsetInBits,
+    sizeInBits: pointerSizeInBits,
+    fixedAbi: definition.fixedAbi
+  };
+};
+
+const layoutString = ({
+  definition,
+  currentOffsetInBits
+}/*: {
+  definition: TFieldType & { type: "string" },
+  abi: TAbi,
+  currentOffsetInBits: number
+}*/)/*: TLayoutedField*/ => {
+
+  const sizeInBits = definition.charSizeInBits * definition.length;
+
+  return {
+    type: "string",
+    offsetInBits: currentOffsetInBits,
+    sizeInBits,
+    charSizeInBits: definition.charSizeInBits,
+    length: definition.length
+  };
+};
+
+const layoutArray = ({
+  definition,
+  abi,
+  currentOffsetInBits
+}/*: {
+  definition: TFieldType & { type: "array" },
+  abi: TAbi,
+  currentOffsetInBits: number
+}*/)/*: TLayoutedField*/ => {
+
+  // eslint-disable-next-line no-use-before-define
+  const elementLayout = layout({ definition: definition.elementType, abi, currentOffsetInBits: 0 });
+
+  // TODO: handle alignment
+  const sizeInBits = elementLayout.sizeInBits * definition.length;
+
+  return {
+    type: "array",
+    offsetInBits: currentOffsetInBits,
+    sizeInBits,
+    elementType: elementLayout,
+    length: definition.length
+  };
+};
+
+const layout = ({
+  definition,
+  abi,
+  currentOffsetInBits
+}/*: {
+  definition: TFieldType,
+  abi: TAbi,
+  currentOffsetInBits: number
+// eslint-disable-next-line complexity
+}*/)/*: TLayoutedField*/ => {
+
+  if (definition.type === "struct") {
+    return layoutStruct({ definition, abi, currentOffsetInBits });
+  }
+
+  if (definition.type === "integer" || definition.type === "float" || definition.type === "pointer") {
+    return layoutPrimitive({ definition, abi, currentOffsetInBits });
+  }
+
+  if (definition.type === "string") {
+    return layoutString({ definition, abi, currentOffsetInBits });
+  }
+
+  if (definition.type === "array") {
+    return layoutArray({ definition, abi, currentOffsetInBits });
+  }
+
+  if (definition.type === "c-type") {
+    const cTypeNormalizer = createCTypeNormalizer({ abi });
+    const basicField = cTypeNormalizer.normalize({ cField: definition });
+
+    return layout({ definition: basicField, abi, currentOffsetInBits });
+  }
+
+  throw Error("not implemented yet");
+};
+
+export {
+  layout
+};
+
+/*export type {
+  TLayoutedField
+};*/

package/dist/lib/parser.d.ts

@@ -0,0 +1,51 @@
+import type { TAbi } from "./common.js";
+import { type TLayoutedField } from "./layout.js";
+import type { TFieldType } from "./types/index.js";
+type FieldValue<T extends TFieldType> = T extends {
+    type: "integer";
+} ? bigint : T extends {
+    type: "float";
+} ? number : T extends {
+    type: "pointer";
+} ? bigint : T extends {
+    type: "string";
+} ? string : T extends {
+    type: "array";
+    elementType: infer E;
+    length: number;
+} ? FieldValue<E & TFieldType>[] : T extends {
+    type: "struct";
+    fields: infer F;
+} ? StructValue<F & readonly {
+    name: string;
+    definition: TFieldType;
+}[]> : never;
+type StructValue<F extends readonly {
+    name: string;
+    definition: TFieldType;
+}[]> = {
+    [K in F[number] as K["name"]]: FieldValue<K["definition"]>;
+};
+type Simplify<T> = {
+    [K in keyof T]: T[K];
+} & {};
+type TParsedValueOfDefinition<T extends TFieldType> = Simplify<FieldValue<T>>;
+type TParser<T extends TFieldType> = {
+    size: number;
+    parse: ({ data }: {
+        data: Uint8Array;
+    }) => TParsedValueOfDefinition<T>;
+    format: ({ value }: {
+        value: TParsedValueOfDefinition<T>;
+    }) => Uint8Array;
+    layout: TLayoutedField;
+};
+declare const define: <const T extends TFieldType>({ definition }: {
+    definition: T;
+}) => {
+    definition: T;
+    parser: ({ abi }: {
+        abi: TAbi;
+    }) => TParser<T>;
+};
+export { define };