@defold-typescript/types 0.1.0

package/src/api-doc.ts

@@ -0,0 +1,168 @@
+export interface ApiModule {
+  namespace: string;
+  brief: string;
+  description: string;
+  functions: ApiFunction[];
+  variables: ApiVariable[];
+  constants: ApiConstant[];
+  properties: ApiProperty[];
+  typedefs: ApiTypedef[];
+}
+
+export interface ApiProperty {
+  name: string;
+  types: string[];
+}
+
+export interface ApiTypedef {
+  name: string;
+}
+
+export interface ApiConstant {
+  name: string;
+  brief: string;
+  description: string;
+}
+
+export interface ApiFunction {
+  name: string;
+  brief: string;
+  description: string;
+  parameters: ApiParameter[];
+  returnValues: ApiParameter[];
+}
+
+export interface ApiParameter {
+  name: string;
+  doc: string;
+  types: string[];
+  isOptional: boolean;
+}
+
+export interface ApiVariable {
+  name: string;
+  brief: string;
+  description: string;
+  types: string[];
+}
+
+export function parseDefoldApiDoc(input: unknown): ApiModule {
+  if (!isRecord(input)) {
+    throw new Error(`parseDefoldApiDoc: expected object, got ${describeKind(input)}`);
+  }
+  const info = input.info;
+  if (!isRecord(info)) {
+    throw new Error(`parseDefoldApiDoc: missing or invalid "info" field`);
+  }
+  const namespace = info.namespace;
+  if (typeof namespace !== "string" || namespace.length === 0) {
+    throw new Error(`parseDefoldApiDoc: missing or invalid "info.namespace"`);
+  }
+  const brief = stringOr(info.brief, "");
+  const description = stringOr(info.description, "");
+
+  const rawElements = input.elements;
+  const elements = Array.isArray(rawElements) ? rawElements : [];
+
+  const functions: ApiFunction[] = [];
+  const variables: ApiVariable[] = [];
+  const constants: ApiConstant[] = [];
+  const properties: ApiProperty[] = [];
+  const typedefs: ApiTypedef[] = [];
+
+  for (const element of elements) {
+    if (!isRecord(element)) continue;
+    const type = element.type;
+    if (type === "FUNCTION") {
+      functions.push(parseFunction(element));
+    } else if (type === "VARIABLE") {
+      variables.push(parseVariable(element));
+    } else if (type === "CONSTANT") {
+      constants.push(parseConstant(element));
+    } else if (type === "PROPERTY") {
+      properties.push(parseProperty(element));
+    } else if (type === "TYPEDEF") {
+      typedefs.push({ name: stringOr(element.name, "") });
+    }
+  }
+
+  return { namespace, brief, description, functions, variables, constants, properties, typedefs };
+}
+
+function parseProperty(element: Record<string, unknown>): ApiProperty {
+  const brief = stringOr(element.brief, "");
+  const span = /<span class="type">([^<]+)<\/span>/.exec(brief);
+  const types =
+    span && span[1] !== undefined
+      ? span[1]
+          .split("|")
+          .map((t) => t.trim())
+          .filter((t) => t.length > 0)
+      : [];
+  return { name: stringOr(element.name, ""), types };
+}
+
+function parseConstant(element: Record<string, unknown>): ApiConstant {
+  return {
+    name: stringOr(element.name, ""),
+    brief: stringOr(element.brief, ""),
+    description: stringOr(element.description, ""),
+  };
+}
+
+function parseFunction(element: Record<string, unknown>): ApiFunction {
+  return {
+    name: stringOr(element.name, ""),
+    brief: stringOr(element.brief, ""),
+    description: stringOr(element.description, ""),
+    parameters: parseParameterList(element.parameters),
+    returnValues: parseParameterList(element.returnvalues),
+  };
+}
+
+function parseVariable(element: Record<string, unknown>): ApiVariable {
+  return {
+    name: stringOr(element.name, ""),
+    brief: stringOr(element.brief, ""),
+    description: stringOr(element.description, ""),
+    types: parseStringArray(element.types),
+  };
+}
+
+function parseParameterList(raw: unknown): ApiParameter[] {
+  if (!Array.isArray(raw)) return [];
+  const out: ApiParameter[] = [];
+  for (const item of raw) {
+    if (!isRecord(item)) continue;
+    out.push({
+      name: stringOr(item.name, ""),
+      doc: stringOr(item.doc, ""),
+      types: parseStringArray(item.types),
+      isOptional: item.is_optional === "True",
+    });
+  }
+  return out;
+}
+
+function parseStringArray(raw: unknown): string[] {
+  if (!Array.isArray(raw)) return [];
+  const out: string[] = [];
+  for (const item of raw) {
+    if (typeof item === "string") out.push(item);
+  }
+  return out;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function stringOr(value: unknown, fallback: string): string {
+  return typeof value === "string" ? value : fallback;
+}
+
+function describeKind(value: unknown): string {
+  if (value === null) return "null";
+  if (Array.isArray(value)) return "array";
+  return typeof value;
+}

package/src/core-types.ts

@@ -0,0 +1,121 @@
+/// <reference types="@typescript-to-lua/language-extensions" />
+
+export interface Vector {
+  readonly [index: number]: number;
+  readonly length: number;
+}
+
+export interface Vector3 {
+  x: number;
+  y: number;
+  z: number;
+  add: LuaAdditionMethod<Vector3, Vector3>;
+  sub: LuaSubtractionMethod<Vector3, Vector3>;
+  mul: LuaMultiplicationMethod<number, Vector3>;
+  div: LuaDivisionMethod<number, Vector3>;
+  /**
+   * @remarks
+   * Prefer `v.unm()` over `-v` — TypeScript does not flag unary `-` on object
+   * types and silently produces `number`. See
+   * `docs/guide/typescript-gotchas.md` for the full story.
+   */
+  unm: LuaNegationMethod<Vector3>;
+}
+
+export interface Vector4 {
+  x: number;
+  y: number;
+  z: number;
+  w: number;
+  add: LuaAdditionMethod<Vector4, Vector4>;
+  sub: LuaSubtractionMethod<Vector4, Vector4>;
+  mul: LuaMultiplicationMethod<number, Vector4>;
+  div: LuaDivisionMethod<number, Vector4>;
+  /**
+   * @remarks
+   * Prefer `v.unm()` over `-v` — TypeScript does not flag unary `-` on object
+   * types and silently produces `number`. See
+   * `docs/guide/typescript-gotchas.md` for the full story.
+   */
+  unm: LuaNegationMethod<Vector4>;
+}
+
+export interface Quaternion {
+  x: number;
+  y: number;
+  z: number;
+  w: number;
+  mul: LuaMultiplicationMethod<Quaternion, Quaternion>;
+}
+
+export interface Matrix4 {
+  m00: number;
+  m01: number;
+  m02: number;
+  m03: number;
+  m10: number;
+  m11: number;
+  m12: number;
+  m13: number;
+  m20: number;
+  m21: number;
+  m22: number;
+  m23: number;
+  m30: number;
+  m31: number;
+  m32: number;
+  m33: number;
+  c0: Vector4;
+  c1: Vector4;
+  c2: Vector4;
+  c3: Vector4;
+  mul: LuaMultiplicationMethod<Matrix4, Matrix4> & LuaMultiplicationMethod<Vector4, Vector4>;
+}
+
+declare const HashBrand: unique symbol;
+export interface Hash {
+  readonly [HashBrand]: "Hash";
+}
+
+declare const OpaqueBrand: unique symbol;
+export interface Opaque<Name extends string> {
+  readonly [OpaqueBrand]: Name;
+}
+
+export interface Url {
+  readonly socket: Hash;
+  readonly path: Hash;
+  readonly fragment: Hash | undefined;
+}
+
+export const DEFOLD_TYPE_MAP: Readonly<Record<string, string>> = {
+  number: "number",
+  int: "number",
+  integer: "number",
+  string: "string",
+  boolean: "boolean",
+  table: "Record<string | number, unknown>",
+  function: "(...args: unknown[]) => unknown",
+  vector: "Vector",
+  vector3: "Vector3",
+  vector4: "Vector4",
+  quaternion: "Quaternion",
+  matrix4: "Matrix4",
+  hash: "Hash",
+  url: "Url",
+  node: 'Opaque<"node">',
+  texture: 'Opaque<"texture">',
+  render_target: 'Opaque<"render_target">',
+  constant: 'Opaque<"constant">',
+  constant_buffer: 'Opaque<"constant_buffer">',
+  buffer: 'Opaque<"buffer">',
+  bufferstream: 'Opaque<"bufferstream">',
+  userdata: 'Opaque<"userdata">',
+  resource: 'Opaque<"resource">',
+  b2World: 'Opaque<"b2World">',
+  b2Body: 'Opaque<"b2Body">',
+  client: 'Opaque<"client">',
+  master: 'Opaque<"master">',
+  unconnected: 'Opaque<"unconnected">',
+  any: "unknown",
+} as const;