@intellectual-frontiers/ergonex 0.3.1 → 0.3.3

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 (54) hide show
  1. package/dist/desired.d.ts +1 -1
  2. package/dist/mod.js +853 -955
  3. package/dist/modules/external.d.ts +1 -1
  4. package/dist/modules/registry.d.ts +1 -1
  5. package/dist/modules/types.d.ts +2 -2
  6. package/dist/plan.d.ts +1 -1
  7. package/dist/render.d.ts +2 -2
  8. package/dist/state-record.d.ts +2 -2
  9. package/dist/tools/catalog.d.ts +1 -1
  10. package/dist/vendor/ts/runtime/http-client.d.ts +1 -1
  11. package/ergonex.mjs +3641 -3638
  12. package/package.json +5 -4
  13. package/dist/vendor/ts/kernel/archive.d.ts +0 -147
  14. package/dist/vendor/ts/kernel/assess.d.ts +0 -247
  15. package/dist/vendor/ts/kernel/attest.d.ts +0 -164
  16. package/dist/vendor/ts/kernel/base64.d.ts +0 -24
  17. package/dist/vendor/ts/kernel/cbor.d.ts +0 -39
  18. package/dist/vendor/ts/kernel/cms.d.ts +0 -106
  19. package/dist/vendor/ts/kernel/cose.d.ts +0 -34
  20. package/dist/vendor/ts/kernel/crypt.d.ts +0 -30
  21. package/dist/vendor/ts/kernel/csv.d.ts +0 -38
  22. package/dist/vendor/ts/kernel/der.d.ts +0 -67
  23. package/dist/vendor/ts/kernel/documentation.d.ts +0 -118
  24. package/dist/vendor/ts/kernel/dsse.d.ts +0 -137
  25. package/dist/vendor/ts/kernel/evidence.d.ts +0 -212
  26. package/dist/vendor/ts/kernel/glob.d.ts +0 -64
  27. package/dist/vendor/ts/kernel/grc.d.ts +0 -356
  28. package/dist/vendor/ts/kernel/http.d.ts +0 -46
  29. package/dist/vendor/ts/kernel/json5.d.ts +0 -46
  30. package/dist/vendor/ts/kernel/layers.d.ts +0 -35
  31. package/dist/vendor/ts/kernel/md5.d.ts +0 -19
  32. package/dist/vendor/ts/kernel/media-types.d.ts +0 -28
  33. package/dist/vendor/ts/kernel/mod.d.ts +0 -89
  34. package/dist/vendor/ts/kernel/ocsf-types.auto.d.ts +0 -4374
  35. package/dist/vendor/ts/kernel/ocsf.d.ts +0 -160
  36. package/dist/vendor/ts/kernel/oscal.d.ts +0 -356
  37. package/dist/vendor/ts/kernel/otel.d.ts +0 -365
  38. package/dist/vendor/ts/kernel/otlp.d.ts +0 -83
  39. package/dist/vendor/ts/kernel/png.d.ts +0 -124
  40. package/dist/vendor/ts/kernel/render.d.ts +0 -111
  41. package/dist/vendor/ts/kernel/schedule.d.ts +0 -207
  42. package/dist/vendor/ts/kernel/semver.d.ts +0 -94
  43. package/dist/vendor/ts/kernel/sha256.d.ts +0 -29
  44. package/dist/vendor/ts/kernel/signals.d.ts +0 -371
  45. package/dist/vendor/ts/kernel/sigv4.d.ts +0 -67
  46. package/dist/vendor/ts/kernel/test-record.d.ts +0 -222
  47. package/dist/vendor/ts/kernel/test-report.d.ts +0 -294
  48. package/dist/vendor/ts/kernel/toml.d.ts +0 -51
  49. package/dist/vendor/ts/kernel/trace.d.ts +0 -169
  50. package/dist/vendor/ts/kernel/ts-literal.d.ts +0 -62
  51. package/dist/vendor/ts/kernel/uuid.d.ts +0 -53
  52. package/dist/vendor/ts/kernel/webauthn.d.ts +0 -212
  53. package/dist/vendor/ts/kernel/xml.d.ts +0 -73
  54. package/dist/vendor/ts/kernel/yaml.d.ts +0 -44
@@ -1,365 +0,0 @@
1
- /**
2
- * The OpenTelemetry data model, written from the OpenTelemetry specification itself (commons 0006-signals FR-001 to FR-008): attribute
3
- * values and log bodies, trace and span ids as brands made only from bytes the caller gives (the kernel has no randomness of its own), W3C
4
- * Trace Context Level 2 `traceparent` and `tracestate`, resources, scopes, finished spans, log records and metric points, the
5
- * configuration read from the `OTEL_*` environment variables (given as a record: the kernel reads no environment), redaction of what must
6
- * never leave a process, the attribute, event and link limits, and the samplers OpenTelemetry names.
7
- *
8
- * @example
9
- * ```ts
10
- * import { formatTraceparent, parseTraceparent, redactUrl, resolveConfig } from "./otel.js";
11
- * const parent = parseTraceparent("00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01");
12
- * if (parent.kind === "ok") formatTraceparent(parent.value); // the same header back
13
- * redactUrl("https://user:pw@host/x?token=abc&page=2"); // "https://REDACTED:REDACTED@host/x?token=REDACTED&page=2"
14
- * resolveConfig({ OTEL_SERVICE_NAME: "build" }).config.resource; // { "service.name": "build" }
15
- * ```
16
- *
17
- * @module
18
- */
19
- import { type Result } from "@intellectual-frontiers/core";
20
- import type { Brand } from "@intellectual-frontiers/core";
21
- /**
22
- * An attribute's value: a string, a boolean, an integer (`bigint`, OTLP's int64), a double (`number`), bytes, or a homogeneous array of
23
- * one of the primitive types. Nothing else is representable (FR-001).
24
- */
25
- export type AttributeValue = string | boolean | bigint | number | Uint8Array | readonly string[] | readonly boolean[] | readonly bigint[] | readonly number[];
26
- /** A set of attributes: names to values. */
27
- export type Attributes = Readonly<Record<string, AttributeValue>>;
28
- /** A log body, as OTLP's `AnyValue`: what an attribute may be, and also a map or an array of mixed values (FR-001). */
29
- export type AnyValue = AttributeValue | readonly AnyValue[] | AnyMap;
30
- /** A map of `AnyValue`s, as OTLP's `KeyValueList`. */
31
- export type AnyMap = {
32
- readonly [key: string]: AnyValue;
33
- };
34
- /** A trace id: 32 lower-case hexadecimal digits, not all zeros (FR-002). */
35
- export type TraceId = Brand<string, "TraceId">;
36
- /** A span id: 16 lower-case hexadecimal digits, not all zeros (FR-002). */
37
- export type SpanId = Brand<string, "SpanId">;
38
- /** A trace id from 16 bytes a caller gives (`traceIdFrom(random(16))`); other lengths and all zeros are refused (FR-002). */
39
- export declare function traceIdFrom(bytes: Uint8Array): Result<TraceId, string>;
40
- /** A span id from 8 bytes a caller gives (`spanIdFrom(random(8))`); other lengths and all zeros are refused (FR-002). */
41
- export declare function spanIdFrom(bytes: Uint8Array): Result<SpanId, string>;
42
- /** A trace id from its text: 32 lower-case hexadecimal digits, not all zeros. */
43
- export declare function parseTraceId(text: string): Result<TraceId, string>;
44
- /** A span id from its text: 16 lower-case hexadecimal digits, not all zeros. */
45
- export declare function parseSpanId(text: string): Result<SpanId, string>;
46
- /** One `tracestate` member. */
47
- export type TraceStateMember = {
48
- readonly key: string;
49
- readonly value: string;
50
- };
51
- /** A `tracestate`: its members, newest first, at most 32, each key once. */
52
- export type TraceState = readonly TraceStateMember[];
53
- /** The `sampled` trace flag. */
54
- export declare const SAMPLED = 1;
55
- /** The `random` trace flag of Level 2: the trace id's right-most 7 bytes are random. */
56
- export declare const RANDOM = 2;
57
- /** The most members a `tracestate` keeps. */
58
- export declare const TRACESTATE_MAX_MEMBERS = 32;
59
- /** What propagates: the ids, the flags, the trace state, and whether it came from another process. */
60
- export type SpanContext = {
61
- readonly traceId: TraceId;
62
- readonly spanId: SpanId;
63
- readonly traceFlags: number;
64
- readonly traceState: TraceState;
65
- readonly isRemote: boolean;
66
- };
67
- /** Whether a context's `sampled` flag is set. */
68
- export declare function isSampled(context: {
69
- readonly traceFlags: number;
70
- }): boolean;
71
- /**
72
- * A `traceparent` header read (FR-003): version `00` exactly as written (55 characters, lower-case hexadecimal, ids not all zeros),
73
- * version `ff` refused, a later version read by its first four fields. The context is remote and its trace state empty; the flags this
74
- * version does not define are dropped.
75
- */
76
- export declare function parseTraceparent(header: string): Result<SpanContext, string>;
77
- /** A `traceparent` header (version `00`) for a context. */
78
- export declare function formatTraceparent(context: {
79
- readonly traceId: TraceId;
80
- readonly spanId: SpanId;
81
- readonly traceFlags: number;
82
- }): string;
83
- /** Whether a key is a `tracestate` key of the grammar. */
84
- export declare function isTraceStateKey(key: string): boolean;
85
- /** Whether a value is a `tracestate` value of the grammar. */
86
- export declare function isTraceStateValue(value: string): boolean;
87
- /**
88
- * A `tracestate` header read (FR-003): members split on commas with optional white space, a member that breaks the grammar or repeats a
89
- * key dropped (never the header), at most 32 members kept. Several header fields are read joined with commas.
90
- */
91
- export declare function parseTracestate(header: string): TraceState;
92
- /** A `tracestate` header: the members newest first, as they are held. */
93
- export declare function formatTracestate(state: TraceState): string;
94
- /** The value of a key in a trace state. */
95
- export declare function traceStateGet(state: TraceState, key: string): string | undefined;
96
- /** A trace state with a key set: the member moved to the front (newest), the oldest dropped beyond 32; a key or value of no grammar refused. */
97
- export declare function traceStateSet(state: TraceState, key: string, value: string): Result<TraceState, string>;
98
- /** A trace state without a key. */
99
- export declare function traceStateDelete(state: TraceState, key: string): TraceState;
100
- /**
101
- * The context carried by a `traceparent` and a `tracestate` (an HTTP request's headers, or the `TRACEPARENT` and `TRACESTATE` of the
102
- * environment): undefined when there is no valid `traceparent`, whose `tracestate` is then ignored too.
103
- */
104
- export declare function extractContext(traceparent: string | undefined, tracestate: string | undefined): SpanContext | undefined;
105
- /** The entity that makes the signals: `service.name` and the others. */
106
- export type Resource = {
107
- readonly attributes: Attributes;
108
- };
109
- /** The instrumentation scope: the library or harness that makes the signals. */
110
- export type Scope = {
111
- readonly name: string;
112
- readonly version?: string;
113
- readonly attributes?: Attributes;
114
- };
115
- /** A span's kind. */
116
- export type SpanKind = "internal" | "server" | "client" | "producer" | "consumer";
117
- /** A span's status: unset, ok, or an error with its description. */
118
- export type SpanStatus = {
119
- readonly kind: "unset";
120
- } | {
121
- readonly kind: "ok";
122
- } | {
123
- readonly kind: "error";
124
- readonly message: string;
125
- };
126
- /** Something that happened at a time during a span. */
127
- export type SpanEvent = {
128
- readonly name: string;
129
- readonly time: bigint;
130
- readonly attributes: Attributes;
131
- readonly droppedAttributesCount: number;
132
- };
133
- /** A span's link to another span's context. */
134
- export type SpanLink = {
135
- readonly traceId: TraceId;
136
- readonly spanId: SpanId;
137
- readonly traceState: TraceState;
138
- readonly traceFlags: number;
139
- readonly attributes: Attributes;
140
- readonly droppedAttributesCount: number;
141
- };
142
- /** A finished span. Times are nanoseconds since the Unix epoch. */
143
- export type SpanData = {
144
- readonly name: string;
145
- readonly context: SpanContext;
146
- readonly parentSpanId?: SpanId;
147
- readonly kind: SpanKind;
148
- readonly startTime: bigint;
149
- readonly endTime: bigint;
150
- readonly attributes: Attributes;
151
- readonly events: readonly SpanEvent[];
152
- readonly links: readonly SpanLink[];
153
- readonly status: SpanStatus;
154
- readonly droppedAttributesCount: number;
155
- readonly droppedEventsCount: number;
156
- readonly droppedLinksCount: number;
157
- };
158
- /** A severity number of the log data model, 1 (TRACE) to 24 (FATAL4). */
159
- export type SeverityNumber = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24;
160
- /** The first severity number of each range of the log data model. */
161
- export declare const SEVERITY: {
162
- readonly TRACE: 1;
163
- readonly DEBUG: 5;
164
- readonly INFO: 9;
165
- readonly WARN: 13;
166
- readonly ERROR: 17;
167
- readonly FATAL: 21;
168
- };
169
- /** Whether a number is a severity number (an integer from 1 to 24). */
170
- export declare function isSeverityNumber(n: number): n is SeverityNumber;
171
- /** The short name the log data model gives a severity number: `INFO`, `INFO2`, ... `FATAL4`. */
172
- export declare function severityText(n: SeverityNumber): string;
173
- /** A log record. Times are nanoseconds since the Unix epoch. */
174
- export type LogRecord = {
175
- readonly time: bigint;
176
- readonly observedTime: bigint;
177
- readonly severityNumber: SeverityNumber;
178
- readonly severityText: string;
179
- readonly body?: AnyValue;
180
- readonly attributes: Attributes;
181
- readonly droppedAttributesCount: number;
182
- readonly eventName?: string;
183
- readonly traceId?: TraceId;
184
- readonly spanId?: SpanId;
185
- readonly traceFlags?: number;
186
- };
187
- /** How a sum or a histogram accumulates: since the last collection, or since the series began. */
188
- export type Temporality = "delta" | "cumulative";
189
- /** A point of a sum or a gauge: an integer (`bigint`) or a double. */
190
- export type NumberPoint = {
191
- readonly attributes: Attributes;
192
- readonly startTime: bigint;
193
- readonly time: bigint;
194
- readonly value: bigint | number;
195
- };
196
- /** A point of an explicit-bucket histogram: `bucketCounts` has one more element than `bounds`, bucket `i` holding (bounds[i-1], bounds[i]]. */
197
- export type HistogramPoint = {
198
- readonly attributes: Attributes;
199
- readonly startTime: bigint;
200
- readonly time: bigint;
201
- readonly count: number;
202
- readonly sum?: number;
203
- readonly min?: number;
204
- readonly max?: number;
205
- readonly bounds: readonly number[];
206
- readonly bucketCounts: readonly number[];
207
- };
208
- /** The data of a metric: a sum (monotonic or not), a gauge, or a histogram. */
209
- export type MetricData = {
210
- readonly kind: "sum";
211
- readonly temporality: Temporality;
212
- readonly monotonic: boolean;
213
- readonly points: readonly NumberPoint[];
214
- } | {
215
- readonly kind: "gauge";
216
- readonly points: readonly NumberPoint[];
217
- } | {
218
- readonly kind: "histogram";
219
- readonly temporality: Temporality;
220
- readonly points: readonly HistogramPoint[];
221
- };
222
- /** A metric: its name, description, unit and data. */
223
- export type Metric = {
224
- readonly name: string;
225
- readonly description: string;
226
- readonly unit: string;
227
- readonly data: MetricData;
228
- };
229
- /** OpenTelemetry's default explicit bucket bounds for a histogram (FR-013). */
230
- export declare const DEFAULT_HISTOGRAM_BOUNDS: readonly number[];
231
- /** The limits of FR-005, applied by FR-007. `attributeValueLength` is `Infinity` where there is none. */
232
- export type Limits = {
233
- readonly attributeValueLength: number;
234
- readonly attributeCount: number;
235
- readonly eventCount: number;
236
- readonly linkCount: number;
237
- };
238
- /** OpenTelemetry's default limits: no value length limit, 128 attributes, events and links. */
239
- export declare const DEFAULT_LIMITS: Limits;
240
- /** A value cut to the value length limit: a string, or each string of an array of strings; other values unchanged. */
241
- export declare function truncateValue(value: AttributeValue, length: number): AttributeValue;
242
- /**
243
- * Attributes added to others under the limits (FR-007): a value cut to the length limit, an existing key replaced, a new key beyond the
244
- * count dropped and counted.
245
- */
246
- export declare function mergeAttributes(current: Attributes, added: Attributes, limits: Pick<Limits, "attributeValueLength" | "attributeCount">): {
247
- readonly attributes: Attributes;
248
- readonly dropped: number;
249
- };
250
- /** Attributes under the limits: what `mergeAttributes` gives from none. */
251
- export declare function limitAttributes(attributes: Attributes, limits: Pick<Limits, "attributeValueLength" | "attributeCount">): {
252
- readonly attributes: Attributes;
253
- readonly dropped: number;
254
- };
255
- /** A sampler for a span with no parent. */
256
- export type RootSampler = {
257
- readonly kind: "always_on";
258
- } | {
259
- readonly kind: "always_off";
260
- } | {
261
- readonly kind: "traceidratio";
262
- readonly ratio: number;
263
- };
264
- /** A sampler: a root sampler, or `parentbased` (the parent's `sampled` flag where there is a parent, `root` where there is none). */
265
- export type Sampler = RootSampler | {
266
- readonly kind: "parentbased";
267
- readonly root: RootSampler;
268
- };
269
- /** OpenTelemetry's default sampler: `parentbased_always_on`. */
270
- export declare const DEFAULT_SAMPLER: Sampler;
271
- /**
272
- * The rejection threshold of `TraceIdRatioBased` for a ratio: a trace is sampled where its trace id's right-most 56 bits, read as an
273
- * unsigned integer, are at least the threshold (`(1 - ratio) * 2^56`). Every process of a trace decides alike from the id alone.
274
- */
275
- export declare function ratioThreshold(ratio: number): bigint;
276
- /** Whether a sampler samples a new span of a trace, given its parent (FR-008). */
277
- export declare function shouldSample(sampler: Sampler, traceId: TraceId, parent: SpanContext | undefined): boolean;
278
- /** What a redacted secret is written as. */
279
- export declare const REDACTED = "REDACTED";
280
- /** Whether a query parameter's or a field's name says it holds a credential (`token`, `key`, `secret`, `password`, `signature`, `code`, ...). */
281
- export declare function isCredentialName(name: string): boolean;
282
- /**
283
- * A URL with its secrets replaced (FR-006): the user and password of its authority, and the value of each query parameter whose name says
284
- * it is a credential, become `REDACTED`. The rest of the text is kept as written.
285
- */
286
- export declare function redactUrl(url: string): string;
287
- /**
288
- * Whether a field's name in text says its value is a secret (FR-006): it ends in `token`, `secret`, `password`, `passwd`, `passphrase`,
289
- * `apikey`, `accesskey`, `secretkey`, `privatekey`, `credential` or `signature`, with case, `-`, `_` and `.` ignored (`api_token`,
290
- * `AWS_SECRET_ACCESS_KEY`, `X-Amz-Signature`, `clientSecret`), but not `max_tokens` or `token_type`. Narrower than
291
- * {@link isCredentialName}, which judges a URL's query parameters, because prose is full of `code=` and `key:`.
292
- */
293
- export declare function isSecretFieldName(name: string): boolean;
294
- /**
295
- * Text with its secrets replaced (FR-006), the one redaction for signals and for what a harness mails: each exact secret named in
296
- * `secrets` (four characters or more; a shorter one would garble the text and hide nothing), a private key block, each URL as
297
- * `redactUrl` writes it, a bearer token, a basic credential (base64 of `user:pass`), the credential of an `Authorization` header with any
298
- * scheme, the value of a `name=value` or `name: value` pair whose name {@link isSecretFieldName} judges secret (quoted or bare, in prose,
299
- * JSON, YAML or an environment file), and the token formats that announce themselves (GitHub, GitLab, Slack, Google, Cloudflare,
300
- * Anthropic, OpenAI, Stripe, npm, DigitalOcean, Docker, Hugging Face, Linear, Atlassian, JSON Web Tokens) and crypt password hashes
301
- * become `REDACTED`.
302
- */
303
- export declare function redactText(text: string, secrets?: Iterable<string>): string;
304
- /** An attribute value with its secrets replaced: `redactText` on a string and on each string of an array. */
305
- export declare function redactValue(value: AttributeValue): AttributeValue;
306
- /** A log body with its secrets replaced, at every depth. */
307
- export declare function redactAnyValue(value: AnyValue): AnyValue;
308
- /** Attributes with the secret ones left out (never written, FR-006) and every other string redacted by `redactText`. */
309
- export declare function redactAttributes(attributes: Attributes, secretKeys?: Iterable<string>): Attributes;
310
- /**
311
- * A command line as it may be recorded (FR-006): the program's name (its last path segment) and the names of its options alone, never a
312
- * value, an operand or a subcommand. `--opt=value` is kept as `--opt`, a short option as its first letter (`-pSECRET` as `-p`), and
313
- * nothing after `--`.
314
- */
315
- export declare function commandShape(argv: readonly string[]): readonly string[];
316
- /** The three signals. */
317
- export type SignalName = "traces" | "logs" | "metrics";
318
- /** Where and how one signal is exported. `endpoint` is undefined where none is configured (the runtime then probes the default). */
319
- export type ExporterConfig = {
320
- readonly enabled: boolean;
321
- readonly endpoint: string | undefined;
322
- readonly headers: Readonly<Record<string, string>>;
323
- readonly timeoutMs: number;
324
- };
325
- /** The settings of a batch processor (`OTEL_BSP_*`, `OTEL_BLRP_*`). */
326
- export type BatchConfig = {
327
- readonly scheduleDelayMs: number;
328
- readonly exportTimeoutMs: number;
329
- readonly maxQueueSize: number;
330
- readonly maxExportBatchSize: number;
331
- };
332
- /** The SDK's own log level (`OTEL_LOG_LEVEL`). */
333
- export type LogLevel = "none" | "error" | "warn" | "info" | "debug" | "verbose" | "all";
334
- /** The configuration the `OTEL_*` variables give. */
335
- export type OtelConfig = {
336
- readonly disabled: boolean;
337
- readonly resource: Attributes;
338
- readonly exporters: {
339
- readonly [S in SignalName]: ExporterConfig;
340
- };
341
- readonly sampler: Sampler;
342
- readonly spanBatch: BatchConfig;
343
- readonly logBatch: BatchConfig;
344
- readonly metricExportIntervalMs: number;
345
- readonly metricExportTimeoutMs: number;
346
- readonly limits: Limits;
347
- readonly logLevel: LogLevel;
348
- };
349
- /** The endpoint an OTLP/HTTP exporter uses where none is configured. */
350
- export declare const DEFAULT_OTLP_ENDPOINT = "http://localhost:4318";
351
- /** The path of each signal under a base endpoint. */
352
- export declare const SIGNAL_PATHS: {
353
- readonly [S in SignalName]: string;
354
- };
355
- /** A base endpoint with a signal's path appended, with one `/` between them. */
356
- export declare function signalEndpoint(base: string, signal: SignalName): string;
357
- /**
358
- * The configuration of the OpenTelemetry environment variables, from a record of them (FR-005): the kernel reads no environment. A value
359
- * that is not valid is a warning and its default is used; an empty value counts as unset; no vendor's variable is read. A protocol other
360
- * than `http/json` is a warning and disables the export of that signal.
361
- */
362
- export declare function resolveConfig(env: Readonly<Record<string, string | undefined>>): {
363
- readonly config: OtelConfig;
364
- readonly warnings: readonly string[];
365
- };
@@ -1,83 +0,0 @@
1
- /**
2
- * OTLP/HTTP with JSON, both ways (commons 0006-signals FR-004): export requests of traces, logs and metrics as the OTLP specification's
3
- * JSON encoding writes them (camel-case field names, trace and span ids as hexadecimal, 64-bit integers as decimal strings, enumerations as
4
- * integers, bytes as base64, signals grouped by resource and scope), the export responses with their partial success, and the decoding of
5
- * each back to the values of `./otel.ts`: a failure is a `Result` naming the path, a 64-bit integer is read from a JSON number or a string,
6
- * an enumeration from its number or its name, and a field the decoder does not know is ignored.
7
- *
8
- * @example
9
- * ```ts
10
- * import { decodeTraces, encodeTraces } from "./otlp.js";
11
- * const request = encodeTraces([{ resource: { attributes: { "service.name": "build" } }, scope: { name: "ifc" }, spans: [] }]);
12
- * decodeTraces(JSON.parse(JSON.stringify(request))); // { kind: "ok", value: [ ...the same batch ] }
13
- * ```
14
- *
15
- * @module
16
- */
17
- import { type Result } from "@intellectual-frontiers/core";
18
- import type { DecodeError, Decoder } from "@intellectual-frontiers/core";
19
- import type { Json, JsonObject } from "./json5.js";
20
- import { type AnyValue, type AttributeValue, type Attributes, type LogRecord, type Metric, type Resource, type Scope, type SignalName, type SpanData } from "./otel.js";
21
- /** The spans of one resource and scope, as OTLP groups them. */
22
- export type TraceBatch = {
23
- readonly resource: Resource;
24
- readonly scope: Scope;
25
- readonly spans: readonly SpanData[];
26
- };
27
- /** The log records of one resource and scope, as OTLP groups them. */
28
- export type LogBatch = {
29
- readonly resource: Resource;
30
- readonly scope: Scope;
31
- readonly records: readonly LogRecord[];
32
- };
33
- /** The metrics of one resource and scope, as OTLP groups them. */
34
- export type MetricBatch = {
35
- readonly resource: Resource;
36
- readonly scope: Scope;
37
- readonly metrics: readonly Metric[];
38
- };
39
- /** An export response: how many signals were rejected (spans, log records or data points) and why; zero and `""` for full success. */
40
- export type ExportResponse = {
41
- readonly rejected: number;
42
- readonly errorMessage: string;
43
- };
44
- /** A value as OTLP's JSON `AnyValue`. */
45
- export declare function encodeAnyValue(value: AnyValue): JsonObject;
46
- /** Attributes as OTLP's JSON list of `KeyValue`. */
47
- export declare function encodeAttributes(attributes: Attributes): Json[];
48
- /** A finished span as OTLP's JSON `Span`. */
49
- export declare function encodeSpan(s: SpanData): JsonObject;
50
- /** A log record as OTLP's JSON `LogRecord`. */
51
- export declare function encodeLogRecord(r: LogRecord): JsonObject;
52
- /** A metric as OTLP's JSON `Metric`. */
53
- export declare function encodeMetric(m: Metric): JsonObject;
54
- /** Trace batches as an OTLP/JSON `ExportTraceServiceRequest`. */
55
- export declare function encodeTraces(batches: readonly TraceBatch[]): JsonObject;
56
- /** Log batches as an OTLP/JSON `ExportLogsServiceRequest`. */
57
- export declare function encodeLogs(batches: readonly LogBatch[]): JsonObject;
58
- /** Metric batches as an OTLP/JSON `ExportMetricsServiceRequest`. */
59
- export declare function encodeMetrics(batches: readonly MetricBatch[]): JsonObject;
60
- /** An export response as OTLP/JSON: `{}` for full success, else `partialSuccess` with the rejected count (a decimal string) and the message. */
61
- export declare function encodeResponse(signal: SignalName, response: ExportResponse): JsonObject;
62
- /** OTLP's JSON `AnyValue` as a value; an `AnyValue` that holds none is refused. */
63
- export declare const decodeAnyValue: Decoder<AnyValue>;
64
- /** An `AnyValue` that is an attribute value: a primitive, or an array of primitives of one type. */
65
- export declare const decodeAttributeValue: Decoder<AttributeValue>;
66
- /** OTLP's JSON list of `KeyValue` as attributes. */
67
- export declare const decodeAttributes: Decoder<Attributes>;
68
- /** OTLP's JSON `Span` as a finished span. */
69
- export declare const decodeSpan: Decoder<SpanData>;
70
- /** OTLP's JSON `LogRecord` as a log record; its severity number must be 1 to 24. */
71
- export declare const decodeLogRecord: Decoder<LogRecord>;
72
- /** OTLP's JSON `Metric` as a metric: a sum, a gauge or a histogram (other data is refused). */
73
- export declare const decodeMetric: Decoder<Metric>;
74
- /** An OTLP/JSON `ExportTraceServiceRequest` as trace batches, one for each scope of each resource; a failure names its path. */
75
- export declare function decodeTraces(input: unknown): Result<readonly TraceBatch[], DecodeError>;
76
- /** An OTLP/JSON `ExportLogsServiceRequest` as log batches, one for each scope of each resource; a failure names its path. */
77
- export declare function decodeLogs(input: unknown): Result<readonly LogBatch[], DecodeError>;
78
- /** An OTLP/JSON `ExportMetricsServiceRequest` as metric batches, one for each scope of each resource; a failure names its path. */
79
- export declare function decodeMetrics(input: unknown): Result<readonly MetricBatch[], DecodeError>;
80
- /** An OTLP/JSON export response; an absent `partialSuccess` is full success. */
81
- export declare function decodeResponse(signal: SignalName, input: unknown): Result<ExportResponse, DecodeError>;
82
- /** The number of signals in trace, log or metric batches: spans, log records, or data points (what a partial success counts). */
83
- export declare function countSignals(batches: readonly TraceBatch[] | readonly LogBatch[] | readonly MetricBatch[]): number;
@@ -1,124 +0,0 @@
1
- /**
2
- * Pictures with no outside package (commons 0005-typescript-runtime FR-043): a PNG read into eight-bit RGBA and written back, a picture
3
- * resized with Pillow's Lanczos filter in its fixed point (on premultiplied alpha for RGBA), laid over another as Pillow's `alpha_composite`
4
- * lays it, fitted as Pillow's `thumbnail` fits it, gathered into a multi-size icon file of PNG frames and read back from one, and two files
5
- * compared by their pixels rather than their bytes (two zlib encoders give different bytes for one picture). Also a `#rrggbb` colour read
6
- * into its channels and its relative luminance as WCAG measures it.
7
- *
8
- * The reader takes every PNG that is not interlaced: greyscale at 1, 2, 4, 8 and 16 bits, palette at 1, 2, 4 and 8 bits, and RGB,
9
- * greyscale with alpha and RGBA at 8 and 16 bits, with `tRNS` transparency for greyscale, RGB and palette, and every filter (None, Sub,
10
- * Up, Average, Paeth). Sixteen-bit samples keep their high byte. It refuses what is not a PNG it can trust, with a typed `PngError`: a bad
11
- * signature, a chunk whose CRC-32 is wrong, data cut short, a colour type and bit depth PNG does not define, an interlaced (Adam7) picture,
12
- * an unknown critical chunk, and a picture of more than `MAX_PIXELS` pixels, refused before anything is allocated or inflated for it; the
13
- * inflater is stopped as soon as it gives more bytes than the picture needs, so a small hostile file cannot make it allocate more.
14
- * Writers take a well-formed picture; a malformed one (a size that is not a positive integer, data of the wrong length) is a programming
15
- * error and throws a `RangeError`.
16
- *
17
- * Taken from erga's `lib/ts/png`. What changed: readers return a typed error rather than a sentence, check every chunk's CRC and the
18
- * picture's size, read the sub-byte depths and the `tRNS` of greyscale and RGB that erga ignored, and refuse an out-of-range palette index;
19
- * erga's `resize` (each channel alone) is `resizeChannels` and its `resized` (on premultiplied alpha) is `resize`; `hexRgb` returns
20
- * `undefined` for what is not a colour rather than black, and `luminance` takes channels rather than a hex string; `composite` clips an
21
- * overlay that starts left of or above its base, and `premultiply` leaves a picture without alpha as it is.
22
- *
23
- * @example
24
- * ```ts
25
- * import { filled, readPng, writePng } from "./png.js";
26
- * const png = await writePng(filled(2, 2, [255, 0, 0, 128]));
27
- * await readPng(png); // { kind: "ok", value: { width: 2, height: 2, channels: 4, data: Uint8Array [255, 0, 0, 128, ...] } }
28
- * ```
29
- *
30
- * @module
31
- */
32
- import { type Result } from "@intellectual-frontiers/core";
33
- /** A raster: its size, its channels (3 for RGB, 4 for RGBA) and its bytes, row by row, eight bits a channel. */
34
- export type Picture = {
35
- readonly width: number;
36
- readonly height: number;
37
- readonly channels: 3 | 4;
38
- readonly data: Uint8Array;
39
- };
40
- /** A colour's red, green and blue, each 0 to 255. */
41
- export type Rgb = readonly [number, number, number];
42
- /** A colour's red, green, blue and alpha, each 0 to 255. */
43
- export type Rgba = readonly [number, number, number, number];
44
- /**
45
- * The most pixels a picture read may have: 2^24 (16,777,216, a 4096 by 4096 square). Its RGBA is then at most 64 MiB, and the inflated
46
- * data of the largest kind (16-bit RGBA) at most 128 MiB. A file that declares more is refused as `too-large` before anything is read.
47
- */
48
- export declare const MAX_PIXELS: number;
49
- /** Why bytes are not a PNG or icon file this reader takes. */
50
- export type PngError = {
51
- readonly kind: "signature";
52
- readonly format: "png" | "ico";
53
- } | {
54
- readonly kind: "crc";
55
- readonly chunk: string;
56
- readonly at: number;
57
- } | {
58
- readonly kind: "truncated";
59
- readonly message: string;
60
- } | {
61
- readonly kind: "malformed";
62
- readonly message: string;
63
- } | {
64
- readonly kind: "unsupported";
65
- readonly message: string;
66
- } | {
67
- readonly kind: "interlaced";
68
- } | {
69
- readonly kind: "too-large";
70
- readonly width: number;
71
- readonly height: number;
72
- readonly limit: number;
73
- } | {
74
- readonly kind: "ico-frame";
75
- readonly index: number;
76
- readonly error: PngError;
77
- };
78
- /** A PNG error as one sentence. */
79
- export declare function formatPngError(e: PngError): string;
80
- /** A picture of one colour, RGBA. A size that is not a positive integer throws a `RangeError`. */
81
- export declare function filled(width: number, height: number, rgba: Rgba): Picture;
82
- /** The picture without its alpha; a picture without alpha as it is. */
83
- export declare function rgbOf(p: Picture): Picture;
84
- /** The picture with alpha, opaque where it had none; a picture with alpha as it is. */
85
- export declare function rgbaOf(p: Picture): Picture;
86
- /** A PNG read into eight-bit RGBA, its filters undone and its palette and transparency applied; or why it cannot be. */
87
- export declare function readPng(bytes: Uint8Array): Promise<Result<Picture, PngError>>;
88
- /** A picture written as an eight-bit RGB or RGBA PNG, each row unfiltered, its zlib stream the platform's `CompressionStream`. */
89
- export declare function writePng(p: Picture): Promise<Uint8Array>;
90
- /** The picture with each colour channel multiplied by its alpha, rounded as Pillow rounds; a picture without alpha as it is. */
91
- export declare function premultiply(p: Picture): Picture;
92
- /** The picture with each colour channel divided by its alpha again, as Pillow divides; a picture without alpha as it is. */
93
- export declare function unpremultiply(p: Picture): Picture;
94
- /**
95
- * A picture resized with Pillow's Lanczos filter in its fixed point, each channel filtered on its own (alpha too, and the colour channels
96
- * without regard to it). A size that is not a positive integer throws a `RangeError`.
97
- */
98
- export declare function resizeChannels(p: Picture, width: number, height: number): Picture;
99
- /** A picture resized as Pillow resizes it with its Lanczos filter: an RGBA picture on premultiplied alpha. The same size gives it back. */
100
- export declare function resize(p: Picture, width: number, height: number): Picture;
101
- /**
102
- * `over` laid on `base` with its top left corner at `(left, top)`, as Pillow's `alpha_composite` lays it; what falls outside `base` is
103
- * cut off. The result has alpha; a picture without alpha is taken as opaque.
104
- */
105
- export declare function composite(base: Picture, over: Picture, left: number, top: number): Picture;
106
- /** `art` laid at `(left, top)` on an opaque canvas of `colour`, the result without alpha. */
107
- export declare function flatOn(colour: Rgb, width: number, height: number, art: Picture, left: number, top: number): Picture;
108
- /** The size Pillow's `thumbnail` gives a picture fitted in `width` by `height`, its aspect kept; `undefined` where it already fits. */
109
- export declare function thumbnailSize(p: Picture, width: number, height: number): readonly [number, number] | undefined;
110
- /**
111
- * A multi-size icon file of PNG frames, as Pillow writes one: one frame for each size asked that is at most the picture's width, height
112
- * and 256, smallest first, each the picture fitted in that square (`thumbnailSize`) and resized (`resize`).
113
- */
114
- export declare function writeIco(p: Picture, sizes: readonly number[]): Promise<Uint8Array>;
115
- /** Every frame of an icon file whose frames are PNGs, in the order of its directory; or why it cannot be read. */
116
- export declare function readIco(bytes: Uint8Array): Promise<Result<readonly Picture[], PngError>>;
117
- /** Whether two pictures have the same size and the same RGBA pixels (a picture without alpha taken as opaque). */
118
- export declare function samePixels(a: Picture, b: Picture): boolean;
119
- /** Whether two PNG files, or two icon files, hold the same pictures pixel for pixel, whatever their zlib streams; false where either cannot be read. */
120
- export declare function samePicture(a: Uint8Array, b: Uint8Array): Promise<boolean>;
121
- /** A `#rrggbb` or `#rgb` colour (the `#` optional, any case) as its channels; `undefined` for what is not one. */
122
- export declare function hexRgb(hex: string): Rgb | undefined;
123
- /** A colour's relative luminance as WCAG 2 measures it, from 0 (black) to 1 (white). */
124
- export declare function luminance(rgb: Rgb): number;