ya-struct 0.0.5 → 0.0.7

package/lib/layout.ts

@@ -0,0 +1,278 @@
+import { align, type TAbi } from "./common.ts";
+import { createCTypeNormalizer } from "./types/c-types.ts";
+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 "array": {
+
+          // TODO: this is probably not sufficient for all cases
+
+          // eslint-disable-next-line no-use-before-define
+          const { sizeInBits } = layout({ definition: normalizedField.elementType, abi, currentOffsetInBits: 0 });
+
+          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/lib/parser.ts

@@ -0,0 +1,87 @@
+import type { TAbi } from "./common.ts";
+import { layout, type TLayoutedField } from "./layout.ts";
+import type { TFieldType } from "./types/index.ts";
+import { createStructParser } from "./types/struct.ts";
+import type { TValueParser } from "./types/value.ts";
+
+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;
+};
+
+const define = <const T extends TFieldType>({ definition }: { definition: T }) => {
+
+  const parser = ({ abi }: { abi: TAbi }): TParser<T> => {
+
+    type P = TParser<T>;
+
+    const l = layout({ definition, abi, currentOffsetInBits: 0 });
+
+    const size = Math.ceil(l.sizeInBits / 8);
+
+    // console.log(l);
+
+    let valueParser: TValueParser<TParsedValueOfDefinition<T>>;
+
+    if (l.type === "struct") {
+      valueParser = createStructParser({
+        layoutedFields: l.fields,
+        endianness: abi.endianness
+      }) as unknown as TValueParser<TParsedValueOfDefinition<T>>;
+    } else {
+      throw Error("only struct root definitions are supported currently");
+    }
+
+    const parse: P["parse"] = ({ data }) => {
+      return valueParser.parse({ data, offsetInBits: 0 });
+    };
+
+    const format: P["format"] = ({ value }) => {
+      const data = new Uint8Array(l.sizeInBits / 8);
+      valueParser.format({ value, target: data, offsetInBits: 0 });
+
+      return data;
+    };
+
+    return {
+      size,
+      parse,
+      format,
+      layout: l
+    };
+  };
+
+  return {
+    definition,
+    parser
+  };
+};
+
+export {
+  define
+};

package/lib/types/array.ts

@@ -0,0 +1,90 @@
+import type { TEndianness } from "../common.ts";
+import type { TFieldType } from "./index.ts";
+import { createIntegerParser } from "./integer.ts";
+import type { TValueParser } from "./value.ts";
+
+type TArrayParser = TValueParser<unknown[]>;
+
+const createArrayParser = ({
+  elementType,
+  length,
+  endianness
+}: {
+  elementType: TFieldType,
+  length: number,
+  endianness: TEndianness
+}): TArrayParser => {
+
+  let fieldParser: TValueParser<unknown>;
+
+  if (elementType.type === "integer") {
+    fieldParser = createIntegerParser({
+      sizeInBits: elementType.sizeInBits,
+      signed: elementType.signed,
+      endianness
+    }) as TValueParser<unknown>;
+  } else {
+    throw Error("only integer array elements are supported currently");
+  }
+
+  const elementSizeInBytes = elementType.sizeInBits / 8;
+  if (!Number.isInteger(elementSizeInBytes)) {
+    throw Error("BUG: non byte-aligned array element size");
+  }
+
+  const parse: TArrayParser["parse"] = ({ data, offsetInBits }) => {
+    if (offsetInBits !== 0) {
+      throw Error("unaligned array parsing not supported yet");
+    }
+
+    // eslint-disable-next-line prefer-const
+    let result: unknown[] = [];
+
+    for (let i = 0; i < length; i += 1) {
+      const fieldData = data.subarray(i * elementSizeInBytes, (i + 1) * elementSizeInBytes);
+      const fieldValue = fieldParser.parse({ data: fieldData, offsetInBits: 0 });
+      result.push(fieldValue);
+    }
+
+    return result;
+  };
+
+  // eslint-disable-next-line complexity
+  const format: TArrayParser["format"] = ({ value, target, offsetInBits }) => {
+    if (offsetInBits !== 0) {
+      throw Error("unaligned array formatting not supported yet");
+    }
+
+    if (value.length !== length) {
+      throw Error(`array length mismatch: field length is ${length}, value length is ${value.length}`);
+    }
+
+    if (target.length < length * elementSizeInBytes) {
+      throw Error("not enough space in target for array formatting");
+    }
+
+    for (let i = 0; i < length; i += 1) {
+      const fieldTarget = target.subarray(i * elementSizeInBytes, (i + 1) * elementSizeInBytes);
+
+      try {
+        fieldParser.format({
+          value: value[i],
+          target: fieldTarget,
+          offsetInBits: 0
+        });
+      } catch (ex) {
+        throw Error(`failed to format array element at index ${i}`, { cause: ex });
+      }
+
+    }
+  };
+
+  return {
+    parse,
+    format
+  };
+};
+
+export {
+  createArrayParser
+};

package/lib/types/c-types.ts

@@ -0,0 +1,222 @@
+import { type TCompiler, type TDataModel, type TAbi } from "../common.ts";
+import { type TFieldType, type TCFieldType, type TPrimitiveBasicFieldType } from "./index.ts";
+
+type TCField = TFieldType & { type: "c-type" };
+
+type TPartialCTypeMappings = {
+  [dataModel in TDataModel]?: {
+    [compiler in TCompiler]?: {
+      [field in TCFieldType]?: TPrimitiveBasicFieldType
+    }
+  }
+};
+
+const cTypeMappings: TPartialCTypeMappings = {
+  LP64: {
+    gcc: {
+      "char": {
+        type: "integer",
+        sizeInBits: 8,
+        fixedAbi: {},
+        signed: true
+      },
+      "unsigned char": {
+        type: "integer",
+        sizeInBits: 8,
+        fixedAbi: {},
+        signed: false
+      },
+      "short": {
+        type: "integer",
+        sizeInBits: 16,
+        fixedAbi: {},
+        signed: true
+      },
+      "unsigned short": {
+        type: "integer",
+        sizeInBits: 16,
+        fixedAbi: {},
+        signed: false
+      },
+      "int": {
+        type: "integer",
+        sizeInBits: 32,
+        fixedAbi: {},
+        signed: true
+      },
+      "unsigned int": {
+        type: "integer",
+        sizeInBits: 32,
+        fixedAbi: {},
+        signed: false
+      },
+      "long": {
+        type: "integer",
+        sizeInBits: 64,
+        fixedAbi: {},
+        signed: true
+      },
+      "unsigned long": {
+        type: "integer",
+        sizeInBits: 64,
+        fixedAbi: {},
+        signed: false
+      },
+      "long long": {
+        type: "integer",
+        sizeInBits: 64,
+        fixedAbi: {},
+        signed: true
+      },
+      "unsigned long long": {
+        type: "integer",
+        sizeInBits: 64,
+        fixedAbi: {},
+        signed: false
+      },
+      "float": {
+        type: "float",
+        sizeInBits: 32,
+        fixedAbi: {}
+      },
+      "double": {
+        type: "float",
+        sizeInBits: 64,
+        fixedAbi: {}
+      },
+      "long double": {
+        type: "float",
+        sizeInBits: 128,
+        fixedAbi: {}
+      },
+    }
+  },
+
+  ILP32: {
+    gcc: {
+      "char": {
+        type: "integer",
+        sizeInBits: 8,
+        fixedAbi: {},
+        signed: true
+      },
+      "unsigned char": {
+        type: "integer",
+        sizeInBits: 8,
+        fixedAbi: {},
+        signed: false
+      },
+      "short": {
+        type: "integer",
+        sizeInBits: 16,
+        fixedAbi: {},
+        signed: true
+      },
+      "unsigned short": {
+        type: "integer",
+        sizeInBits: 16,
+        fixedAbi: {},
+        signed: false
+      },
+      "int": {
+        type: "integer",
+        sizeInBits: 32,
+        fixedAbi: {},
+        signed: true
+      },
+      "unsigned int": {
+        type: "integer",
+        sizeInBits: 32,
+        fixedAbi: {},
+        signed: false
+      },
+      "long": {
+        type: "integer",
+        sizeInBits: 32,
+        fixedAbi: {},
+        signed: true
+      },
+      "unsigned long": {
+        type: "integer",
+        sizeInBits: 32,
+        fixedAbi: {},
+        signed: false
+      },
+      "long long": {
+        type: "integer",
+        sizeInBits: 64,
+        fixedAbi: {},
+        signed: true
+      },
+      "unsigned long long": {
+        type: "integer",
+        sizeInBits: 64,
+        fixedAbi: {},
+        signed: false
+      },
+      "float": {
+        type: "float",
+        sizeInBits: 32,
+        fixedAbi: {}
+      },
+      "double": {
+        type: "float",
+        sizeInBits: 64,
+        fixedAbi: {}
+      },
+      "long double": {
+        type: "float",
+        sizeInBits: 128,
+        fixedAbi: {}
+      },
+    }
+  }
+};
+
+const createCTypeNormalizer = ({
+  abi
+}: {
+  abi: TAbi
+}) => {
+
+  const fieldMappings = cTypeMappings[abi.dataModel]?.[abi.compiler];
+  if (!fieldMappings) {
+    throw Error(`no c-type mappings for data model ${abi.dataModel} and compiler ${abi.compiler}`);
+  }
+
+  const normalize = ({ cField }: { cField: TCField }): TPrimitiveBasicFieldType => {
+
+    const mapping = fieldMappings[cField.cType];
+    if (mapping === undefined) {
+      throw Error(`no c-type mapping for c-type "${cField.cType}" for data model ${abi.dataModel} and compiler ${abi.compiler}`);
+    }
+
+    const mappingFixedAbi = mapping.fixedAbi;
+    const fieldFixedAbi = cField.fixedAbi;
+
+    const fixedAbi = {
+      ...mappingFixedAbi,
+      ...fieldFixedAbi
+    };
+
+    Object.keys(fixedAbi).forEach((keyAsString) => {
+      const key = keyAsString as keyof TAbi;
+      if (mappingFixedAbi[key] !== undefined && fieldFixedAbi[key] !== undefined) {
+        throw Error(`conflicting fixed ABI property for key ${key} between c-type mapping and c-field`);
+      }
+    });
+
+    return {
+      ...mapping,
+      fixedAbi
+    };
+  };
+
+  return {
+    normalize
+  };
+};
+
+export {
+  createCTypeNormalizer
+};