alef 0.114.0

Opinionated polyglot binding generator for Rust libraries
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137

// DO NOT EDIT - auto-generated by alef
"use strict";

// The native binding attaches the structured properties of a failed call to the thrown error as
// the JSON message of its `cause`: the napi runtime cannot set own properties on an error that an
// async Rust function returns. This module moves those properties onto the error itself, so a
// caller reads `error.kind`, `error.statusCode`, `error.retryAfter` and the rest as declared in
// `index.d.ts`. It wraps every exported function, every static and prototype method of an
// exported class, and the async iterator a streaming call returns.
// Constructors are not wrapped: a constructor that throws keeps the plain native error.

const MARKER = "alef:error-info:";
const SKIP = new Set(["constructor", "length", "name", "prototype", "caller", "arguments"]);
const patched = new WeakSet();
const iterables = new WeakSet();

function decorate(error) {
  if (error === null || typeof error !== "object") return error;
  const cause = error.cause;
  if (cause === null || typeof cause !== "object" || typeof cause.message !== "string") return error;
  if (!cause.message.startsWith(MARKER)) return error;
  let info;
  try {
    info = JSON.parse(cause.message.slice(MARKER.length));
  } catch {
    return error;
  }
  for (const [name, value] of Object.entries(info)) {
    Object.defineProperty(error, name, { value, enumerable: true, writable: true, configurable: true });
  }
  try {
    delete error.cause;
  } catch {
    // The payload stays on the cause when the runtime refuses the delete.
  }
  return error;
}

function rethrow(error) {
  throw decorate(error);
}

function wrapIterator(iterator) {
  if (iterator === null || typeof iterator !== "object") return iterator;
  for (const name of ["next", "return", "throw"]) {
    const original = iterator[name];
    if (typeof original !== "function") continue;
    try {
      Object.defineProperty(iterator, name, {
        configurable: true,
        writable: true,
        value: function (...args) {
          return Promise.resolve(original.apply(this, args)).then(undefined, rethrow);
        },
      });
    } catch {
      // A frozen iterator keeps its plain errors.
    }
  }
  return iterator;
}

function wrapIterable(value) {
  if (value === null || typeof value !== "object") return value;
  const open = value[Symbol.asyncIterator];
  if (typeof open !== "function" || iterables.has(value)) return value;
  iterables.add(value);
  try {
    Object.defineProperty(value, Symbol.asyncIterator, {
      configurable: true,
      writable: true,
      value: function () {
        return wrapIterator(open.call(this));
      },
    });
  } catch {
    return value;
  }
  wrapIterator(value);
  return value;
}

function settle(result) {
  if (result !== null && typeof result === "object" && typeof result.then === "function") {
    return result.then(wrapIterable, rethrow);
  }
  return wrapIterable(result);
}

function wrapFunction(fn) {
  return function (...args) {
    let result;
    try {
      result = fn.apply(this, args);
    } catch (error) {
      throw decorate(error);
    }
    return settle(result);
  };
}

function patchMethods(target) {
  if (target === null || (typeof target !== "object" && typeof target !== "function")) return;
  if (patched.has(target)) return;
  patched.add(target);
  for (const key of Reflect.ownKeys(target)) {
    if (typeof key === "string" && SKIP.has(key)) continue;
    const descriptor = Object.getOwnPropertyDescriptor(target, key);
    if (!descriptor || typeof descriptor.value !== "function" || !descriptor.configurable) continue;
    try {
      Object.defineProperty(target, key, { ...descriptor, value: wrapFunction(descriptor.value) });
    } catch {
      // A method the runtime refuses to redefine keeps its plain errors.
    }
  }
}

function wrapExport(value) {
  if (typeof value !== "function") return value;
  patchMethods(value);
  patchMethods(value.prototype);
  // Only `apply` is trapped, so `new`, `instanceof` and static access reach the native class.
  return new Proxy(value, {
    apply(target, thisArg, args) {
      return wrapFunction(target).apply(thisArg, args);
    },
  });
}

module.exports = function decorateBinding(native) {
  const decorated = {};
  for (const key of Object.keys(native)) {
    decorated[key] = wrapExport(native[key]);
  }
  return decorated;
};
module.exports.decorate = decorate;