@defold-typescript/types 0.51.0 → 0.53.0

package/src/msg-overloads.d.ts

@@ -100,17 +100,24 @@ declare global {
      * Only the following arities are supported at runtime:
      *
      * - `msg.url()` — no-arg.
-     * - `msg.url("[socket:][path][#fragment]")` — one string, the full URL.
-     * - `msg.url(socket, path, fragment)` — three required args.
+     * - `msg.url(urlstring)` — one argument: a `"[socket:][path][#fragment]"`
+     *   string, a `Hash`, or a `Url`.
+     * - `msg.url(socket, path, fragment)` — three positions, each of which may
+     *   be `undefined` (Lua `nil`).
      *
      * The two-arg form `msg.url(socket, path)` is a runtime error.
      *
-     * `socket` may be `undefined` (Lua `nil`), which addresses the current
-     * game world, exactly as the runtime's own examples do.
+     * In the one-argument form, a `Hash` is a path in the current world with no
+     * fragment, and a `Url` is copied. `undefined` is equivalent to `msg.url()`
+     * — the URL of the current script.
      *
-     * The one-argument form's `urlstring` may likewise be `undefined` (Lua
-     * `nil`), which the ref-doc calls equivalent to `msg.url()` — the URL of the
-     * current script.
+     * In the three-argument form, an `undefined` `socket` addresses the current
+     * game world, exactly as the runtime's own examples do. An `undefined`
+     * `path` with an `undefined` socket is the current path. An `undefined`
+     * `fragment` is no fragment, unless `socket` and `path` are both
+     * `undefined`, which keeps the current fragment. A `socket` and `fragment`
+     * with an `undefined` `path` raise "Can't resolve id with specified socket
+     * and fragment."
      *
      * In the same world, address a sibling **relatively** — by bare id
      * (`msg.url("camera")`), absolute path (`msg.url("/camera")`), or
@@ -139,6 +146,9 @@ declare global {
      * // A component on a sibling.
      * const comp: Url = msg.url("camera#script");
      *
+     * // A hashed path in the current world.
+     * const door: Url = msg.url(hash("/door"));
+     *
      * // Crossing into a proxy-loaded world — `socket` is the world name.
      * const proxied: Url = msg.url(hash("level1"), hash("/door"), hash("script"));
      *
@@ -147,18 +157,20 @@ declare global {
      * ```
      */
     function url(): Url;
-    function url(urlstring: SceneAddress | undefined): Url;
+    function url(urlstring: SceneAddress | Hash | Url | undefined): Url;
     function url(
       socket: string | Hash | undefined,
-      path: string | Hash,
-      fragment: string | Hash,
+      path: string | Hash | undefined,
+      fragment: string | Hash | undefined,
     ): Url;
     function url<M extends object>(): ReceiverUrl<M>;
-    function url<M extends object>(urlstring: SceneAddress | undefined): ReceiverUrl<M>;
+    function url<M extends object>(
+      urlstring: SceneAddress | Hash | Url | undefined,
+    ): ReceiverUrl<M>;
     function url<M extends object>(
       socket: string | Hash | undefined,
-      path: string | Hash,
-      fragment: string | Hash,
+      path: string | Hash | undefined,
+      fragment: string | Hash | undefined,
     ): ReceiverUrl<M>;
   }
 }

package/src/signature-store.ts

@@ -9,6 +9,10 @@ export interface SignatureOverride {
   // than `signatures` keeps the ref-doc fixture description for those rows. Every
   // existing override omits `docs` and renders exactly as before.
   docs?: (string | null)[];
+  // Optional per-overload first release, parallel to `signatures`: entry `i` is
+  // the bare semver from which row `i` exists, or `null` for a row every target
+  // declares. An absent array means every row is ungated.
+  since?: (string | null)[];
 }
 
 // An FQN (`io.open`, `file:read`, …) maps to one override. An element with
@@ -23,3 +27,49 @@ export type SignatureStore = Record<string, SignatureOverride>;
 export function lookupSignature(store: SignatureStore, fqn: string): SignatureOverride | null {
   return store[fqn] ?? null;
 }
+
+function versionParts(version: string): number[] {
+  return version.split(".").map((part) => Number.parseInt(part, 10));
+}
+
+function versionAtLeast(version: string, since: string): boolean {
+  const [have, need] = [versionParts(version), versionParts(since)];
+  for (let index = 0; index < Math.max(have.length, need.length); index += 1) {
+    const diff = (have[index] ?? 0) - (need[index] ?? 0);
+    if (diff !== 0) return diff > 0;
+  }
+  return true;
+}
+
+// The override as a target at `version` declares it: only the rows whose `since`
+// is absent, `null`, or at most `version`, with `docs` and `since` kept parallel.
+export function signatureArmsFor(override: SignatureOverride, version: string): SignatureOverride {
+  const since = override.since;
+  if (since === undefined) return override;
+  const kept = override.signatures
+    .map((_, index) => index)
+    .filter((index) => {
+      const first = since[index];
+      return first == null || versionAtLeast(version, first);
+    });
+  if (kept.length === override.signatures.length) return override;
+  const docs = override.docs;
+  return {
+    signatures: kept.map((index) => override.signatures[index] as string),
+    ...(docs === undefined
+      ? {}
+      : { docs: kept.filter((index) => index < docs.length).map((index) => docs[index] ?? null) }),
+    since: kept.map((index) => since[index] ?? null),
+  };
+}
+
+// The store as one version declares it: each entry keeps only the arms whose
+// `since` the version meets, and an entry left with none is dropped.
+export function signatureStoreFor(store: SignatureStore, version: string): SignatureStore {
+  const scoped: SignatureStore = {};
+  for (const [fqn, override] of Object.entries(store)) {
+    const arms = signatureArmsFor(override, version);
+    if (arms.signatures.length > 0) scoped[fqn] = arms;
+  }
+  return scoped;
+}

package/src/socket-types.d.ts

@@ -9,7 +9,7 @@
 //
 //   const opt: socket.TCPOptions = 'keepalive';
 //   // TCP/UDP are convenience intersections for consumer annotations;
-//   // no socket.* function returns them (tcp() yields a `master` handle).
+//   // no socket.* function returns them (tcp() yields a `SocketMaster` handle).
 //
 // The literal unions are LuaSocket-domain, not engine-ref-doc, so they live
 // here rather than in the regen pipeline.
@@ -17,7 +17,7 @@
 declare global {
   namespace socket {
     /** A TCP handle in any of its three lifecycle roles. */
-    type TCP = client & master & server;
+    type TCP = SocketClient & SocketMaster & SocketServer;
     /** Option names accepted by a TCP handle's `setoption`. */
     type TCPOptions = "ipv6-v6only" | "keepalive" | "linger" | "reuseaddr" | "tcp-nodelay";
     /** Error string a TCP `receive` may return. */
@@ -29,7 +29,7 @@ declare global {
     /** Blocking mode passed to a TCP handle's `settimeout`. */
     type TCPTimeoutMode = "b" | "t";
     /** A UDP handle in either of its two lifecycle roles. */
-    type UDP = connected & unconnected;
+    type UDP = SocketConnected & SocketUnconnected;
     /** Option names accepted by a UDP handle's `setoption`. */
     type UDPOptions =
       | "broadcast"

package/src/timers.d.ts

@@ -3,7 +3,8 @@
 // as an isolated Lua chunk with no shared global scope and no JS event loop, so
 // these are named module exports (lowered to a `require`), not ambient globals:
 // pay-for-use and explicit. The transpiler emits the runtime and the CLI writes
-// it to the output root; the import lowers to `require("defold_typescript_timers")`.
+// it to `lib/defold_typescript/timers.lua` (moved by `runtime-dir`), respelling
+// the import's `require` to that path.
 declare module "@defold-typescript/types/timers" {
   /**
    * Run `callback` once after `delayMs` milliseconds, backed by Defold's

package/src/vmath-overloads.d.ts

@@ -85,6 +85,32 @@ declare global {
      * @returns multiplied vector
      */
     function mul_per_elem<T extends Vector3 | Vector4>(v1: T, v2: T): T;
+    /**
+     * The returned value is a scalar defined as:
+     * `P ⋅ Q = |P| |Q| cos θ`
+     * where θ is the angle between the vectors P and Q.
+     *
+     * - If the dot product is positive then the angle between the vectors is below 90 degrees.
+     * - If the dot product is zero the vectors are perpendicular (at right-angles to each other).
+     * - If the dot product is negative then the angle between the vectors is more than 90 degrees.
+     *
+     * Both vectors must have the same type: a vector3 paired with a vector4 raises.
+     *
+     * @param v1 - first vector
+     * @param v2 - second vector
+     * @returns dot product
+     * @example
+     * ```ts
+     * const vector1 = vmath.vector3(1, 0, 0);
+     * const vector2 = vmath.vector3(0, 1, 0);
+     *
+     * if (vmath.dot(vector1, vector2) === 0) {
+     *   // The two vectors are perpendicular (at right-angles to each other)
+     *   // ...
+     * }
+     * ```
+     */
+    function dot<T extends Vector3 | Vector4>(v1: T, v2: T): number;
     /**
      * Normalizes a vector, i.e. returns a new vector with the same
      * direction as the input vector, but with length 1.