@alienplatform/bindings 1.0.0 → 1.14.1-dev.e74fae6cd01b61e77a285276f264b5480977f41a

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (55) hide show
  1. package/README.md +59 -0
  2. package/dist/errors.d.ts +56 -0
  3. package/dist/errors.d.ts.map +1 -0
  4. package/dist/factories.d.ts +26 -0
  5. package/dist/factories.d.ts.map +1 -0
  6. package/dist/index.d.ts +19 -1768
  7. package/dist/index.d.ts.map +1 -1
  8. package/dist/index.js +23 -44772
  9. package/dist/loader.d.ts +171 -0
  10. package/dist/loader.d.ts.map +1 -0
  11. package/dist/loader.js +3712 -0
  12. package/dist/native.d.ts +41 -0
  13. package/dist/native.d.ts.map +1 -0
  14. package/dist/native.js +46 -0
  15. package/dist/types.d.ts +150 -0
  16. package/dist/types.d.ts.map +1 -0
  17. package/package.json +46 -27
  18. package/AGENTS.md +0 -70
  19. package/dist/index.js.map +0 -1
  20. package/scripts/generate-proto.sh +0 -46
  21. package/src/bindings/AGENTS.md +0 -105
  22. package/src/bindings/artifact-registry.ts +0 -314
  23. package/src/bindings/build.ts +0 -195
  24. package/src/bindings/function.ts +0 -164
  25. package/src/bindings/index.ts +0 -12
  26. package/src/bindings/kv.ts +0 -240
  27. package/src/bindings/queue.ts +0 -191
  28. package/src/bindings/service-account.ts +0 -113
  29. package/src/bindings/storage.ts +0 -535
  30. package/src/bindings/vault.ts +0 -133
  31. package/src/channel.ts +0 -94
  32. package/src/commands.ts +0 -76
  33. package/src/context.ts +0 -368
  34. package/src/errors.ts +0 -259
  35. package/src/events.ts +0 -463
  36. package/src/generated/artifact_registry.ts +0 -1934
  37. package/src/generated/build.ts +0 -1263
  38. package/src/generated/container.ts +0 -485
  39. package/src/generated/control.ts +0 -1574
  40. package/src/generated/function.ts +0 -741
  41. package/src/generated/google/protobuf/duration.ts +0 -196
  42. package/src/generated/google/protobuf/timestamp.ts +0 -225
  43. package/src/generated/kv.ts +0 -1137
  44. package/src/generated/queue.ts +0 -729
  45. package/src/generated/service_account.ts +0 -766
  46. package/src/generated/storage.ts +0 -3653
  47. package/src/generated/vault.ts +0 -519
  48. package/src/generated/wait_until.ts +0 -781
  49. package/src/global.ts +0 -316
  50. package/src/grpc-utils.ts +0 -159
  51. package/src/index.ts +0 -156
  52. package/src/types.ts +0 -384
  53. package/src/wait-until.ts +0 -257
  54. package/tsconfig.json +0 -8
  55. package/tsdown.config.ts +0 -14
@@ -0,0 +1,171 @@
1
+ /**
2
+ * Native addon loader.
3
+ *
4
+ * Resolves the napi-rs addon for the current platform, in order:
5
+ *
6
+ * 1. `ALIEN_BINDINGS_ADDON_PATH` — an explicit path to a `.node` file. This is
7
+ * a dev/test-only escape hatch and is never set in published installs.
8
+ * 2. The per-platform prebuild package from `optionalDependencies`
9
+ * (`@alienplatform/bindings-<triple>`) — how end users get the addon.
10
+ * `optionalDependencies` only exists in the *published* manifest: the
11
+ * release pipeline injects the exact-version package list with
12
+ * `scripts/inject-optional-deps.mjs`. The workspace source manifest carries
13
+ * no `optionalDependencies`, so this path is a no-op
14
+ * (module-not-found) in every dev/test checkout — expected, and why step 3
15
+ * exists below. Its reported version must match this wrapper package;
16
+ * mixed wrapper/prebuild versions are rejected before any binding runs.
17
+ * 3. Dev fallback: the locally-built addon under
18
+ * `crates/alien-bindings-node/alien-bindings-node.<triple>.node`, located by
19
+ * walking up from this module. This lets the repo run against a
20
+ * `napi build`-produced `.node` without publishing a prebuild. Before
21
+ * trusting this addon, its `version()` is compared against this
22
+ * package's own `package.json` version; a mismatch (a stale local build
23
+ * left over from an earlier checkout) is logged and rejected rather than
24
+ * loaded, falling through to the same "cannot load" error as if no addon
25
+ * had been found at all.
26
+ *
27
+ * Loading is deferred: `loadAddon()` is only called on the first binding
28
+ * operation (see `factories.ts`), never at module import. That is what makes the
29
+ * package safe to mark `sideEffects: false` — importing it performs no I/O and
30
+ * requires no addon.
31
+ */
32
+ /** Raw napi scan page. */
33
+ export interface RawKvItem {
34
+ key: string;
35
+ value: Buffer;
36
+ }
37
+ /** Raw napi scan result. */
38
+ export interface RawScanResult {
39
+ items: RawKvItem[];
40
+ nextCursor?: string;
41
+ }
42
+ /** Raw napi object metadata. */
43
+ export interface RawObjectMeta {
44
+ location: string;
45
+ size: number;
46
+ lastModified: string;
47
+ }
48
+ /** Raw napi presigned request. */
49
+ export interface RawPresignedRequest {
50
+ url: string;
51
+ method: string;
52
+ headers: Record<string, string>;
53
+ }
54
+ /** Raw napi queue message. */
55
+ export interface RawQueueMessage {
56
+ payloadType: "json" | "text";
57
+ payload: string;
58
+ receiptHandle: string;
59
+ attempt: number;
60
+ }
61
+ /** Raw napi storage handle. */
62
+ export interface RawStorageHandle {
63
+ get(path: string): Promise<Buffer>;
64
+ put(path: string, data: Buffer): Promise<void>;
65
+ delete(path: string): Promise<void>;
66
+ list(prefix?: string | null): Promise<RawObjectMeta[]>;
67
+ head(path: string): Promise<RawObjectMeta>;
68
+ copy(from: string, to: string): Promise<void>;
69
+ signedUrl(method: string, path: string, expiresInSecs: number): Promise<RawPresignedRequest>;
70
+ }
71
+ /** Raw napi key-value handle. */
72
+ export interface RawKvHandle {
73
+ get(key: string): Promise<Buffer | null>;
74
+ put(key: string, value: Buffer, ttlSecs?: number | null, ifNotExists?: boolean | null): Promise<boolean>;
75
+ delete(key: string): Promise<void>;
76
+ exists(key: string): Promise<boolean>;
77
+ scan(prefix: string, limit?: number | null, cursor?: string | null): Promise<RawScanResult>;
78
+ }
79
+ /** Raw napi queue handle. Every method takes the queue name as its first arg. */
80
+ export interface RawQueueHandle {
81
+ sendJson(queue: string, jsonString: string): Promise<void>;
82
+ sendText(queue: string, text: string): Promise<void>;
83
+ receive(queue: string, max: number): Promise<RawQueueMessage[]>;
84
+ ack(queue: string, receipt: string): Promise<void>;
85
+ nack(queue: string, receipt: string): Promise<void>;
86
+ purge(queue: string): Promise<void>;
87
+ }
88
+ /** Raw napi vault handle. */
89
+ export interface RawVaultHandle {
90
+ getSecret(name: string): Promise<string>;
91
+ setSecret(name: string, value: string): Promise<void>;
92
+ deleteSecret(name: string): Promise<void>;
93
+ listSecrets(): Promise<string[]>;
94
+ }
95
+ /** Raw napi bindings entry point. Construction validates the environment. */
96
+ export interface RawBindingsHandle {
97
+ storage(name: string): Promise<RawStorageHandle>;
98
+ kv(name: string): Promise<RawKvHandle>;
99
+ queue(name: string): Promise<RawQueueHandle>;
100
+ vault(name: string): Promise<RawVaultHandle>;
101
+ }
102
+ /** The complete napi addon module surface consumed by the wrapper. */
103
+ export interface NativeAddon {
104
+ BindingsHandle: new () => RawBindingsHandle;
105
+ version(): string;
106
+ }
107
+ /** The Linux C library a prebuild is compiled against. */
108
+ export type LinuxLibc = "gnu" | "musl";
109
+ /**
110
+ * Detect the Linux C library (glibc vs musl) of the current process, using the
111
+ * same signal as napi-rs's generated loader: a glibc runtime reports a
112
+ * `glibcVersionRuntime` in its process report; a musl runtime (Alpine, etc.)
113
+ * does not. Falls back to the Alpine marker file when the report is
114
+ * unavailable.
115
+ *
116
+ * Only meaningful on Linux — `platformTriple` consults the result solely on the
117
+ * `linux` branch, so the value returned on other platforms is unused.
118
+ */
119
+ export declare function detectLinuxLibc(): LinuxLibc;
120
+ /**
121
+ * Map `process.platform` / `process.arch` to the napi triple used in both the
122
+ * prebuild package name and the locally-built `.node` file name. Mirrors the
123
+ * `optionalDependencies` set pinned in PACKAGE_LAYOUT.md.
124
+ *
125
+ * Only glibc Linux prebuilds are published (`…-gnu`; see PACKAGE_LAYOUT.md), so
126
+ * a musl host (Alpine and friends) has no addon: this throws a clear
127
+ * unsupported-platform error naming musl rather than silently selecting the
128
+ * glibc triple, which would otherwise fail to resolve — or, worse, load a glibc
129
+ * `.node` into a musl process and crash on the first binding call.
130
+ *
131
+ * Exported for unit testing: accepts `platform`/`arch`/`libc` explicitly
132
+ * (defaulting to the detected values) so every supported pair — and the
133
+ * unsupported cases — can be exercised directly, without stubbing `process`.
134
+ */
135
+ export declare function platformTriple(platform?: NodeJS.Platform, arch?: NodeJS.Architecture, libc?: LinuxLibc): string;
136
+ /**
137
+ * Walk up from `startDir` (default: this module's directory) looking for the
138
+ * locally-built addon under `crates/alien-bindings-node`, returning its path or
139
+ * `undefined` if the walk reaches the filesystem root without finding it.
140
+ * Repo-internal dev/test only. Also reused by `scripts/compile-smoke.ts`.
141
+ */
142
+ export declare function findLocalAddon(triple: string, startDir?: string): string | undefined;
143
+ /**
144
+ * Reject wrapper/addon version skew before the native module is used.
145
+ *
146
+ * The wrapper and every platform prebuild are published as one release. npm
147
+ * normally installs the exact version pinned in `optionalDependencies`, but a
148
+ * stale lockfile, package-manager override, or copied `node_modules` can still
149
+ * leave a different native binary on disk. Loading that binary risks calling
150
+ * an incompatible napi surface, so fail with the two observed versions.
151
+ */
152
+ export declare function assertAddonVersion(addon: NativeAddon, expected: string, source: string): void;
153
+ /**
154
+ * Register an addon that is already resident in the process — the one bun
155
+ * embeds into a `bun build --compile` binary through the `./native` entry.
156
+ *
157
+ * A compiled workload has no filesystem prebuild and no dev checkout to walk,
158
+ * so none of the resolution steps in {@link loadAddon} can find the addon. The
159
+ * build makes the compiled entry import `@alienplatform/bindings/native`, whose
160
+ * `installEmbeddedAddon()` calls this so the ordinary `@alienplatform/bindings`
161
+ * factories (which go through {@link loadAddon}) use the embedded addon. In a
162
+ * non-compiled dev/test run nothing imports `./native`, so this is never called
163
+ * and {@link loadAddon} falls through to its normal resolution.
164
+ */
165
+ export declare function registerEmbeddedAddon(addon: NativeAddon): void;
166
+ /**
167
+ * Load (and memoize) the native addon. Throws if no addon can be resolved for
168
+ * the current platform. Called lazily on the first binding operation.
169
+ */
170
+ export declare function loadAddon(): NativeAddon;
171
+ //# sourceMappingURL=loader.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../src/loader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AASH,0BAA0B;AAC1B,MAAM,WAAW,SAAS;IACxB,GAAG,EAAE,MAAM,CAAA;IACX,KAAK,EAAE,MAAM,CAAA;CACd;AAED,4BAA4B;AAC5B,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,SAAS,EAAE,CAAA;IAClB,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AAED,gCAAgC;AAChC,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,MAAM,CAAA;IAChB,IAAI,EAAE,MAAM,CAAA;IACZ,YAAY,EAAE,MAAM,CAAA;CACrB;AAED,kCAAkC;AAClC,MAAM,WAAW,mBAAmB;IAClC,GAAG,EAAE,MAAM,CAAA;IACX,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAChC;AAED,8BAA8B;AAC9B,MAAM,WAAW,eAAe;IAC9B,WAAW,EAAE,MAAM,GAAG,MAAM,CAAA;IAC5B,OAAO,EAAE,MAAM,CAAA;IACf,aAAa,EAAE,MAAM,CAAA;IACrB,OAAO,EAAE,MAAM,CAAA;CAChB;AAED,+BAA+B;AAC/B,MAAM,WAAW,gBAAgB;IAC/B,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;IAClC,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAC9C,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACnC,IAAI,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC,CAAA;IACtD,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAAA;IAC1C,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAC7C,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAA;CAC7F;AAED,iCAAiC;AACjC,MAAM,WAAW,WAAW;IAC1B,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAA;IACxC,GAAG,CACD,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,EACvB,WAAW,CAAC,EAAE,OAAO,GAAG,IAAI,GAC3B,OAAO,CAAC,OAAO,CAAC,CAAA;IACnB,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAClC,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IACrC,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,aAAa,CAAC,CAAA;CAC5F;AAED,iFAAiF;AACjF,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAC1D,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACpD,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC,CAAA;IAC/D,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAClD,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACnD,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CACpC;AAED,6BAA6B;AAC7B,MAAM,WAAW,cAAc;IAC7B,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;IACxC,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACrD,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACzC,WAAW,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC,CAAA;CACjC;AAED,6EAA6E;AAC7E,MAAM,WAAW,iBAAiB;IAChC,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAA;IAChD,EAAE,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAAA;IACtC,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,CAAA;IAC5C,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,CAAA;CAC7C;AAED,sEAAsE;AACtE,MAAM,WAAW,WAAW;IAC1B,cAAc,EAAE,UAAU,iBAAiB,CAAA;IAC3C,OAAO,IAAI,MAAM,CAAA;CAClB;AAED,0DAA0D;AAC1D,MAAM,MAAM,SAAS,GAAG,KAAK,GAAG,MAAM,CAAA;AAEtC;;;;;;;;;GASG;AACH,wBAAgB,eAAe,IAAI,SAAS,CAW3C;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,cAAc,CAC5B,QAAQ,GAAE,MAAM,CAAC,QAA2B,EAC5C,IAAI,GAAE,MAAM,CAAC,YAA2B,EACxC,IAAI,GAAE,SAA4D,GACjE,MAAM,CAaR;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,MAAM,EACd,QAAQ,GAAE,MAAgD,GACzD,MAAM,GAAG,SAAS,CAWpB;AASD;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAO7F;AAKD;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,WAAW,GAAG,IAAI,CAE9D;AAED;;;GAGG;AACH,wBAAgB,SAAS,IAAI,WAAW,CA0DvC"}