diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index 5f09f9587c00..1c7d639db7ed 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -445,7 +445,7 @@ jobs: - name: Set up Deno uses: denoland/setup-deno@v1.1.3 with: - deno-version: v1.37.1 + deno-version: v1.38.5 - name: Restore caches uses: ./.github/actions/restore-cache env: @@ -864,13 +864,16 @@ jobs: 'create-remix-app-v2', 'debug-id-sourcemaps', 'nextjs-app-dir', + 'nextjs-14', 'react-create-hash-router', 'react-router-6-use-routes', 'standard-frontend-react', 'standard-frontend-react-tracing-import', 'sveltekit', + 'sveltekit-2', 'generic-ts3.8', 'node-experimental-fastify-app', + 'node-hapi-app', ] build-command: - false diff --git a/.github/workflows/canary.yml b/.github/workflows/canary.yml index ed05e9bfd1af..9801407515cd 100644 --- a/.github/workflows/canary.yml +++ b/.github/workflows/canary.yml @@ -73,6 +73,12 @@ jobs: - test-application: 'nextjs-app-dir' build-command: 'test:build-latest' label: 'nextjs-app-dir (latest)' + - test-application: 'nextjs-14' + build-command: 'test:build-canary' + label: 'nextjs-14 (canary)' + - test-application: 'nextjs-14' + build-command: 'test:build-latest' + label: 'nextjs-14 (latest)' - test-application: 'react-create-hash-router' build-command: 'test:build-canary' label: 'react-create-hash-router (canary)' diff --git a/.gitignore b/.gitignore index 813a38ad89d2..8d7413d26757 100644 --- a/.gitignore +++ b/.gitignore @@ -50,6 +50,9 @@ tmp.js .eslintcache **/eslintcache/* +# node worker scripts +packages/node/src/integrations/anr/worker-script.* + # deno packages/deno/build-types packages/deno/build-test diff --git a/.size-limit.js b/.size-limit.js index 599f59e07170..5d690d69768a 100644 --- a/.size-limit.js +++ b/.size-limit.js @@ -86,18 +86,21 @@ module.exports = [ name: '@sentry/browser (incl. Tracing, Replay) - ES6 CDN Bundle (minified & uncompressed)', path: 'packages/browser/build/bundles/bundle.tracing.replay.min.js', gzip: false, + brotli: false, limit: '260 KB', }, { name: '@sentry/browser (incl. Tracing) - ES6 CDN Bundle (minified & uncompressed)', path: 'packages/browser/build/bundles/bundle.tracing.min.js', gzip: false, + brotli: false, limit: '100 KB', }, { name: '@sentry/browser - ES6 CDN Bundle (minified & uncompressed)', path: 'packages/browser/build/bundles/bundle.min.js', gzip: false, + brotli: false, limit: '70 KB', }, diff --git a/.vscode/settings.json b/.vscode/settings.json index d60ded5fea96..7835767bad18 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -30,8 +30,8 @@ ], "deno.enablePaths": ["packages/deno/test"], "editor.codeActionsOnSave": { - "source.organizeImports.biome": true, - "quickfix.biome": true + "source.organizeImports.biome": "explicit", + "quickfix.biome": "explicit" }, "editor.defaultFormatter": "biomejs.biome" } diff --git a/CHANGELOG.md b/CHANGELOG.md index 41aebacf874f..4345f368f6fd 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,145 @@ - "You miss 100 percent of the chances you don't take. — Wayne Gretzky" — Michael Scott +## 7.89.0 + +### Important Changes + +#### Deprecations + +- **feat(core): Deprecate `configureScope` (#9887)** +- **feat(core): Deprecate `pushScope` & `popScope` (#9890)** + +This release deprecates `configureScope`, `pushScope`, and `popScope`, which will be removed in the upcoming v8 major release. + +#### Hapi Integration + +- **feat(node): Add Hapi Integration (#9539)** + +This release adds an integration for Hapi. It can be used as follows: + +```ts +const Sentry = require('@sentry/node'); +const Hapi = require('@hapi/hapi'); + +const init = async () => { + const server = Hapi.server({ + // your server configuration ... + }); + + Sentry.init({ + dsn: '__DSN__', + tracesSampleRate: 1.0, + integrations: [ + new Sentry.Integrations.Hapi({ server }), + ], + }); + + server.route({ + // your route configuration ... + }); + + await server.start(); +}; +``` + +#### SvelteKit 2.0 + +- **chore(sveltekit): Add SvelteKit 2.0 to peer dependencies (#9861)** + +This release adds support for SvelteKit 2.0 in the `@sentry/sveltekit` package. If you're upgrading from SvelteKit 1.x to 2.x and already use the Sentry SvelteKit SDK, no changes apart from upgrading to this (or a newer) version are necessary. + +### Other Changes + +- feat(core): Add type & utility for function-based integrations (#9818) +- feat(core): Update `withScope` to return callback return value (#9866) +- feat(deno): Support `Deno.CronSchedule` for cron jobs (#9880) +- feat(nextjs): Auto instrument generation functions (#9781) +- feat(nextjs): Connect server component transactions if there is no incoming trace (#9845) +- feat(node-experimental): Update to new Scope APIs (#9799) +- feat(replay): Add `canvas.type` setting (#9877) +- fix(nextjs): Export `createReduxEnhancer` (#9854) +- fix(remix): Do not capture thrown redirect responses. (#9909) +- fix(sveltekit): Add conditional exports (#9872) +- fix(sveltekit): Avoid capturing 404 errors on client side (#9902) +- fix(utils): Do not use `Event` type in worldwide (#9864) +- fix(utils): Support crypto.getRandomValues in old Chromium versions (#9251) +- fix(utils): Update `eventFromUnknownInput` to avoid scope pollution & `getCurrentHub` (#9868) +- ref: Use `addBreadcrumb` directly & allow to pass hint (#9867) + +Work in this release contributed by @adam187, and @jghinestrosa. Thank you for your contributions! + +## 7.88.0 + +### Important Changes + +- **feat(browser): Add browser metrics sdk (#9794)** + +The release adds alpha support for [Sentry developer metrics](https://github.com/getsentry/sentry/discussions/58584) in the Browser SDKs (`@sentry/browser` and related framework SDKs). Via the newly introduced APIs, you can now flush metrics directly to Sentry. + +To enable capturing metrics, you first need to add the `MetricsAggregator` integration. + +```js +Sentry.init({ + dsn: '__DSN__', + integrations: [ + new Sentry.metrics.MetricsAggregator(), + ], +}); +``` + +Then you'll be able to add `counters`, `sets`, `distributions`, and `gauges` under the `Sentry.metrics` namespace. + +```js +// Add 4 to a counter named `hits` +Sentry.metrics.increment('hits', 4); + +// Add 2 to gauge named `parallel_requests`, tagged with `happy: "no"` +Sentry.metrics.gauge('parallel_requests', 2, { tags: { happy: 'no' } }); + +// Add 4.6 to a distribution named `response_time` with unit seconds +Sentry.metrics.distribution('response_time', 4.6, { unit: 'seconds' }); + +// Add 2 to a set named `valuable.ids` +Sentry.metrics.set('valuable.ids', 2); +``` + +In a future release we'll add support for server runtimes (Node, Deno, Bun, Vercel Edge, etc.) + +- **feat(deno): Optionally instrument `Deno.cron` (#9808)** + +This releases add support for instrumenting [Deno cron's](https://deno.com/blog/cron) with [Sentry cron monitors](https://docs.sentry.io/product/crons/). This requires v1.38 of Deno run with the `--unstable` flag and the usage of the `DenoCron` Sentry integration. + +```ts +// Import from the Deno registry +import * as Sentry from "https://deno.land/x/sentry/index.mjs"; + +Sentry.init({ + dsn: '__DSN__', + integrations: [ + new Sentry.DenoCron(), + ], +}); +``` + +### Other Changes + +- feat(replay): Bump `rrweb` to 2.6.0 (#9847) +- fix(nextjs): Guard against injecting multiple times (#9807) +- ref(remix): Bump Sentry CLI to ^2.23.0 (#9773) + +## 7.87.0 + +- feat: Add top level `getCurrentScope()` method (#9800) +- feat(replay): Bump `rrweb` to 2.5.0 (#9803) +- feat(replay): Capture hydration error breadcrumb (#9759) +- feat(types): Add profile envelope types (#9798) +- fix(astro): Avoid RegExp creation during route interpolation (#9815) +- fix(browser): Avoid importing from `./exports` (#9775) +- fix(nextjs): Catch rejecting flushes (#9811) +- fix(nextjs): Fix devserver CORS blockage when `assetPrefix` is defined (#9766) +- fix(node): Capture errors in tRPC middleware (#9782) + ## 7.86.0 - feat(core): Use SDK_VERSION for hub API version (#9732) diff --git a/MIGRATION.md b/MIGRATION.md index 78f5f16d3002..101f9de4469d 100644 --- a/MIGRATION.md +++ b/MIGRATION.md @@ -8,6 +8,18 @@ npx @sentry/migr8@latest This will let you select which updates to run, and automatically update your code. Make sure to still review all code changes! +## Deprecate `pushScope` & `popScope` in favor of `withScope` + +Instead of manually pushing/popping a scope, you should use `Sentry.withScope(callback: (scope: Scope))` instead. + +## Deprecate `configureScope` in favor of using `getCurrentScope()` + +Instead of updating the scope in a callback via `configureScope()`, you should access it via `getCurrentScope()` and configure it directly: + +```js +Sentry.getCurrentScope().setTag('xx', 'yy'); +``` + ## Deprecate `addGlobalEventProcessor` in favor of `addEventProcessor` Instead of using `addGlobalEventProcessor`, you should use `addEventProcessor` which does not add the event processor globally, but to the current client. diff --git a/codecov.yml b/codecov.yml index fcc0885b060b..1013e1b11e24 100644 --- a/codecov.yml +++ b/codecov.yml @@ -3,6 +3,11 @@ codecov: notify: require_ci_to_pass: no +ai_pr_review: + enabled: true + method: "label" + label_name: "ci-codecov-ai-review" + coverage: precision: 2 round: down diff --git a/lerna.json b/lerna.json index 159f8f0d635d..35f062081888 100644 --- a/lerna.json +++ b/lerna.json @@ -1,5 +1,5 @@ { "$schema": "node_modules/lerna/schemas/lerna-schema.json", - "version": "7.86.0", + "version": "7.89.0", "npmClient": "yarn" } diff --git a/package.json b/package.json index f8bdaced8cbe..2558eb4469f5 100644 --- a/package.json +++ b/package.json @@ -88,8 +88,8 @@ "@rollup/plugin-replace": "^3.0.1", "@rollup/plugin-sucrase": "^4.0.3", "@rollup/plugin-typescript": "^8.3.1", - "@size-limit/preset-small-lib": "~9.0.0", - "@size-limit/webpack": "~9.0.0", + "@size-limit/file": "~11.0.1", + "@size-limit/webpack": "~11.0.1", "@strictsoftware/typedoc-plugin-monorepo": "^0.3.1", "@types/chai": "^4.1.3", "@types/jest": "^27.4.1", @@ -124,7 +124,7 @@ "rollup-plugin-license": "^2.6.1", "rollup-plugin-terser": "^7.0.2", "sinon": "^7.3.2", - "size-limit": "~9.0.0", + "size-limit": "~11.0.1", "ts-jest": "^27.1.4", "ts-node": "10.9.1", "typedoc": "^0.18.0", diff --git a/packages/angular-ivy/package.json b/packages/angular-ivy/package.json index 6fc7515f30e7..c1f4056887b4 100644 --- a/packages/angular-ivy/package.json +++ b/packages/angular-ivy/package.json @@ -1,6 +1,6 @@ { "name": "@sentry/angular-ivy", - "version": "7.86.0", + "version": "7.89.0", "description": "Official Sentry SDK for Angular with full Ivy Support", "repository": "git://github.com/getsentry/sentry-javascript.git", "homepage": "https://github.com/getsentry/sentry-javascript/tree/master/packages/angular-ivy", @@ -21,9 +21,9 @@ "rxjs": "^6.5.5 || ^7.x" }, "dependencies": { - "@sentry/browser": "7.86.0", - "@sentry/types": "7.86.0", - "@sentry/utils": "7.86.0", + "@sentry/browser": "7.89.0", + "@sentry/types": "7.89.0", + "@sentry/utils": "7.89.0", "tslib": "^2.4.1" }, "devDependencies": { diff --git a/packages/angular/package.json b/packages/angular/package.json index 1f9aa38de3dd..d7746b3ab222 100644 --- a/packages/angular/package.json +++ b/packages/angular/package.json @@ -1,6 +1,6 @@ { "name": "@sentry/angular", - "version": "7.86.0", + "version": "7.89.0", "description": "Official Sentry SDK for Angular", "repository": "git://github.com/getsentry/sentry-javascript.git", "homepage": "https://github.com/getsentry/sentry-javascript/tree/master/packages/angular", @@ -21,9 +21,9 @@ "rxjs": "^6.5.5 || ^7.x" }, "dependencies": { - "@sentry/browser": "7.86.0", - "@sentry/types": "7.86.0", - "@sentry/utils": "7.86.0", + "@sentry/browser": "7.89.0", + "@sentry/types": "7.89.0", + "@sentry/utils": "7.89.0", "tslib": "^2.4.1" }, "devDependencies": { diff --git a/packages/angular/src/tracing.ts b/packages/angular/src/tracing.ts index 88a2490c1d58..25ddc2fd8dcf 100644 --- a/packages/angular/src/tracing.ts +++ b/packages/angular/src/tracing.ts @@ -7,7 +7,7 @@ import type { ActivatedRouteSnapshot, Event, RouterState } from '@angular/router // eslint-disable-next-line @typescript-eslint/consistent-type-imports import { NavigationCancel, NavigationError, Router } from '@angular/router'; import { NavigationEnd, NavigationStart, ResolveEnd } from '@angular/router'; -import { WINDOW, getCurrentHub } from '@sentry/browser'; +import { WINDOW, getCurrentScope } from '@sentry/browser'; import type { Span, Transaction, TransactionContext } from '@sentry/types'; import { logger, stripUrlQueryAndFragment, timestampInSeconds } from '@sentry/utils'; import type { Observable } from 'rxjs'; @@ -50,14 +50,7 @@ export const instrumentAngularRouting = routingInstrumentation; * Grabs active transaction off scope */ export function getActiveTransaction(): Transaction | undefined { - const currentHub = getCurrentHub(); - - if (currentHub) { - const scope = currentHub.getScope(); - return scope.getTransaction(); - } - - return undefined; + return getCurrentScope().getTransaction(); } /** diff --git a/packages/angular/test/tracing.test.ts b/packages/angular/test/tracing.test.ts index e290850241c8..635c8847b9bf 100644 --- a/packages/angular/test/tracing.test.ts +++ b/packages/angular/test/tracing.test.ts @@ -21,16 +21,12 @@ jest.mock('@sentry/browser', () => { const original = jest.requireActual('@sentry/browser'); return { ...original, - getCurrentHub: () => { + getCurrentScope() { return { - getScope: () => { - return { - getTransaction: () => { - return transaction; - }, - }; + getTransaction: () => { + return transaction; }, - } as unknown as Hub; + }; }, }; }); diff --git a/packages/astro/package.json b/packages/astro/package.json index a08eeec9e566..6546a3243030 100644 --- a/packages/astro/package.json +++ b/packages/astro/package.json @@ -1,6 +1,6 @@ { "name": "@sentry/astro", - "version": "7.86.0", + "version": "7.89.0", "description": "Official Sentry SDK for Astro", "repository": "git://github.com/getsentry/sentry-javascript.git", "homepage": "https://github.com/getsentry/sentry-javascript/tree/master/packages/astro", @@ -43,11 +43,11 @@ "astro": ">=3.x || >=4.0.0-beta" }, "dependencies": { - "@sentry/browser": "7.86.0", - "@sentry/core": "7.86.0", - "@sentry/node": "7.86.0", - "@sentry/types": "7.86.0", - "@sentry/utils": "7.86.0", + "@sentry/browser": "7.89.0", + "@sentry/core": "7.89.0", + "@sentry/node": "7.89.0", + "@sentry/types": "7.89.0", + "@sentry/utils": "7.89.0", "@sentry/vite-plugin": "^2.8.0" }, "devDependencies": { diff --git a/packages/astro/src/client/sdk.ts b/packages/astro/src/client/sdk.ts index aa32e9dcc095..2fd98b8a96cd 100644 --- a/packages/astro/src/client/sdk.ts +++ b/packages/astro/src/client/sdk.ts @@ -1,6 +1,6 @@ import type { BrowserOptions } from '@sentry/browser'; import { BrowserTracing, init as initBrowserSdk } from '@sentry/browser'; -import { configureScope, hasTracingEnabled } from '@sentry/core'; +import { getCurrentScope, hasTracingEnabled } from '@sentry/core'; import { addOrUpdateIntegration } from '@sentry/utils'; import { applySdkMetadata } from '../common/metadata'; @@ -20,9 +20,7 @@ export function init(options: BrowserOptions): void { initBrowserSdk(options); - configureScope(scope => { - scope.setTag('runtime', 'browser'); - }); + getCurrentScope().setTag('runtime', 'browser'); } function addClientIntegrations(options: BrowserOptions): void { diff --git a/packages/astro/src/index.server.ts b/packages/astro/src/index.server.ts index a0c18c0cb6e7..adcf95527364 100644 --- a/packages/astro/src/index.server.ts +++ b/packages/astro/src/index.server.ts @@ -17,6 +17,7 @@ export { captureMessage, captureCheckIn, withMonitor, + // eslint-disable-next-line deprecation/deprecation configureScope, createTransport, // eslint-disable-next-line deprecation/deprecation @@ -25,6 +26,7 @@ export { getHubFromCarrier, getCurrentHub, getClient, + getCurrentScope, Hub, makeMain, Scope, diff --git a/packages/astro/src/server/meta.ts b/packages/astro/src/server/meta.ts index 4264be2733f5..7f1f544a19e6 100644 --- a/packages/astro/src/server/meta.ts +++ b/packages/astro/src/server/meta.ts @@ -1,5 +1,5 @@ import { getDynamicSamplingContextFromClient } from '@sentry/core'; -import type { Hub, Span } from '@sentry/types'; +import type { Client, Scope, Span } from '@sentry/types'; import { TRACEPARENT_REGEXP, dynamicSamplingContextToSentryBaggageHeader, @@ -22,9 +22,11 @@ import { * * @returns an object with the two serialized tags */ -export function getTracingMetaTags(span: Span | undefined, hub: Hub): { sentryTrace: string; baggage?: string } { - const scope = hub.getScope(); - const client = hub.getClient(); +export function getTracingMetaTags( + span: Span | undefined, + scope: Scope, + client: Client | undefined, +): { sentryTrace: string; baggage?: string } { const { dsc, sampled, traceId } = scope.getPropagationContext(); const transaction = span?.transaction; diff --git a/packages/astro/src/server/middleware.ts b/packages/astro/src/server/middleware.ts index 8ff33382d916..7b4a02cceddf 100644 --- a/packages/astro/src/server/middleware.ts +++ b/packages/astro/src/server/middleware.ts @@ -1,18 +1,13 @@ import { captureException, - configureScope, continueTrace, - getCurrentHub, + getClient, + getCurrentScope, runWithAsyncContext, startSpan, } from '@sentry/node'; -import type { Hub, Span } from '@sentry/types'; -import { - addNonEnumerableProperty, - objectify, - stripUrlQueryAndFragment, - tracingContextFromHeaders, -} from '@sentry/utils'; +import type { Client, Scope, Span } from '@sentry/types'; +import { addNonEnumerableProperty, objectify, stripUrlQueryAndFragment } from '@sentry/utils'; import type { APIContext, MiddlewareResponseHandler } from 'astro'; import { getTracingMetaTags } from './meta'; @@ -64,13 +59,17 @@ type AstroLocalsWithSentry = Record & { }; export const handleRequest: (options?: MiddlewareOptions) => MiddlewareResponseHandler = options => { - const handlerOptions = { trackClientIp: false, trackHeaders: false, ...options }; + const handlerOptions = { + trackClientIp: false, + trackHeaders: false, + ...options, + }; return async (ctx, next) => { // if there is an active span, we know that this handle call is nested and hence // we don't create a new domain for it. If we created one, nested server calls would // create new transactions instead of adding a child span to the currently active span. - if (getCurrentHub().getScope().getSpan()) { + if (getCurrentScope().getSpan()) { return instrumentRequest(ctx, next, handlerOptions); } return runWithAsyncContext(() => { @@ -107,24 +106,23 @@ async function instrumentRequest( } if (options.trackClientIp) { - configureScope(scope => { - scope.setUser({ ip_address: ctx.clientAddress }); - }); + getCurrentScope().setUser({ ip_address: ctx.clientAddress }); } try { + const interpolatedRoute = interpolateRouteFromUrlAndParams(ctx.url.pathname, ctx.params); // storing res in a variable instead of directly returning is necessary to // invoke the catch block if next() throws const res = await startSpan( { ...traceCtx, - name: `${method} ${interpolateRouteFromUrlAndParams(ctx.url.pathname, ctx.params)}`, + name: `${method} ${interpolatedRoute || ctx.url.pathname}`, op: 'http.server', origin: 'auto.http.astro', status: 'ok', metadata: { ...traceCtx?.metadata, - source: 'route', + source: interpolatedRoute ? 'route' : 'url', }, data: { method, @@ -141,8 +139,8 @@ async function instrumentRequest( span.setHttpStatus(originalResponse.status); } - const hub = getCurrentHub(); - const client = hub.getClient(); + const scope = getCurrentScope(); + const client = getClient(); const contentType = originalResponse.headers.get('content-type'); const isPageloadRequest = contentType && contentType.startsWith('text/html'); @@ -165,7 +163,7 @@ async function instrumentRequest( start: async controller => { for await (const chunk of originalBody) { const html = typeof chunk === 'string' ? chunk : decoder.decode(chunk); - const modifiedHtml = addMetaTagToHead(html, hub, span); + const modifiedHtml = addMetaTagToHead(html, scope, client, span); controller.enqueue(new TextEncoder().encode(modifiedHtml)); } controller.close(); @@ -187,12 +185,12 @@ async function instrumentRequest( * This function optimistically assumes that the HTML coming in chunks will not be split * within the tag. If this still happens, we simply won't replace anything. */ -function addMetaTagToHead(htmlChunk: string, hub: Hub, span?: Span): string { +function addMetaTagToHead(htmlChunk: string, scope: Scope, client: Client, span?: Span): string { if (typeof htmlChunk !== 'string') { return htmlChunk; } - const { sentryTrace, baggage } = getTracingMetaTags(span, hub); + const { sentryTrace, baggage } = getTracingMetaTags(span, scope, client); const content = `\n${sentryTrace}\n${baggage}\n`; return htmlChunk.replace('', content); } @@ -202,10 +200,76 @@ function addMetaTagToHead(htmlChunk: string, hub: Hub, span?: Span): string { * Best we can do to get a route name instead of a raw URL. * * exported for testing + * + * @param rawUrlPathname - The raw URL pathname, e.g. '/users/123/details' + * @param params - The params object, e.g. `{ userId: '123' }` + * + * @returns The interpolated route, e.g. '/users/[userId]/details' */ -export function interpolateRouteFromUrlAndParams(rawUrl: string, params: APIContext['params']): string { - return Object.entries(params).reduce((interpolateRoute, value) => { - const [paramId, paramValue] = value; - return interpolateRoute.replace(new RegExp(`(/|-)${paramValue}(/|-|$)`), `$1[${paramId}]$2`); - }, rawUrl); +export function interpolateRouteFromUrlAndParams( + rawUrlPathname: string, + params: APIContext['params'], +): string | undefined { + const decodedUrlPathname = tryDecodeUrl(rawUrlPathname); + if (!decodedUrlPathname) { + return undefined; + } + + // Invert params map so that the param values are the keys + // differentiate between rest params spanning multiple url segments + // and normal, single-segment params. + const valuesToMultiSegmentParams: Record = {}; + const valuesToParams: Record = {}; + Object.entries(params).forEach(([key, value]) => { + if (!value) { + return; + } + if (value.includes('/')) { + valuesToMultiSegmentParams[value] = key; + return; + } + valuesToParams[value] = key; + }); + + function replaceWithParamName(segment: string): string { + const param = valuesToParams[segment]; + if (param) { + return `[${param}]`; + } + return segment; + } + + // before we match single-segment params, we first replace multi-segment params + const urlWithReplacedMultiSegmentParams = Object.keys(valuesToMultiSegmentParams).reduce((acc, key) => { + return acc.replace(key, `[${valuesToMultiSegmentParams[key]}]`); + }, decodedUrlPathname); + + return urlWithReplacedMultiSegmentParams + .split('/') + .map(segment => { + if (!segment) { + return ''; + } + + if (valuesToParams[segment]) { + return replaceWithParamName(segment); + } + + // astro permits multiple params in a single path segment, e.g. /[foo]-[bar]/ + const segmentParts = segment.split('-'); + if (segmentParts.length > 1) { + return segmentParts.map(part => replaceWithParamName(part)).join('-'); + } + + return segment; + }) + .join('/'); +} + +function tryDecodeUrl(url: string): string | undefined { + try { + return decodeURI(url); + } catch { + return undefined; + } } diff --git a/packages/astro/src/server/sdk.ts b/packages/astro/src/server/sdk.ts index 8c867ca46fc2..e69d27781ed5 100644 --- a/packages/astro/src/server/sdk.ts +++ b/packages/astro/src/server/sdk.ts @@ -1,4 +1,4 @@ -import { configureScope } from '@sentry/core'; +import { getCurrentScope } from '@sentry/core'; import type { NodeOptions } from '@sentry/node'; import { init as initNodeSdk } from '@sentry/node'; @@ -13,7 +13,5 @@ export function init(options: NodeOptions): void { initNodeSdk(options); - configureScope(scope => { - scope.setTag('runtime', 'node'); - }); + getCurrentScope().setTag('runtime', 'node'); } diff --git a/packages/astro/test/server/meta.test.ts b/packages/astro/test/server/meta.test.ts index 6298f5f2a20b..279f36395107 100644 --- a/packages/astro/test/server/meta.test.ts +++ b/packages/astro/test/server/meta.test.ts @@ -10,22 +10,20 @@ const mockedSpan = { environment: 'production', }), }, -}; +} as any; -const mockedHub = { - getScope: () => ({ - getPropagationContext: () => ({ - traceId: '123', - }), +const mockedClient = {} as any; + +const mockedScope = { + getPropagationContext: () => ({ + traceId: '123', }), - getClient: () => ({}), -}; +} as any; describe('getTracingMetaTags', () => { it('returns the tracing tags from the span, if it is provided', () => { { - // @ts-expect-error - only passing a partial span object - const tags = getTracingMetaTags(mockedSpan, mockedHub); + const tags = getTracingMetaTags(mockedSpan, mockedScope, mockedClient); expect(tags).toEqual({ sentryTrace: '', @@ -35,10 +33,9 @@ describe('getTracingMetaTags', () => { }); it('returns propagationContext DSC data if no span is available', () => { - const tags = getTracingMetaTags(undefined, { - ...mockedHub, - // @ts-expect-error - only passing a partial scope object - getScope: () => ({ + const tags = getTracingMetaTags( + undefined, + { getPropagationContext: () => ({ traceId: '12345678901234567890123456789012', sampled: true, @@ -49,8 +46,9 @@ describe('getTracingMetaTags', () => { trace_id: '12345678901234567890123456789012', }, }), - }), - }); + } as any, + mockedClient, + ); expect(tags).toEqual({ sentryTrace: expect.stringMatching( @@ -73,7 +71,8 @@ describe('getTracingMetaTags', () => { toTraceparent: () => '12345678901234567890123456789012-1234567890123456-1', transaction: undefined, }, - mockedHub, + mockedScope, + mockedClient, ); expect(tags).toEqual({ @@ -93,10 +92,8 @@ describe('getTracingMetaTags', () => { toTraceparent: () => '12345678901234567890123456789012-1234567890123456-1', transaction: undefined, }, - { - ...mockedHub, - getClient: () => undefined, - }, + mockedScope, + undefined, ); expect(tags).toEqual({ diff --git a/packages/astro/test/server/middleware.test.ts b/packages/astro/test/server/middleware.test.ts index 19ee0ef1b5c6..5e56c6bd70ed 100644 --- a/packages/astro/test/server/middleware.test.ts +++ b/packages/astro/test/server/middleware.test.ts @@ -1,5 +1,6 @@ import * as SentryNode from '@sentry/node'; -import { vi } from 'vitest'; +import type { Client } from '@sentry/types'; +import { SpyInstance, vi } from 'vitest'; import { handleRequest, interpolateRouteFromUrlAndParams } from '../../src/server/middleware'; @@ -14,14 +15,17 @@ describe('sentryMiddleware', () => { const startSpanSpy = vi.spyOn(SentryNode, 'startSpan'); const getSpanMock = vi.fn(() => {}); - // @ts-expect-error only returning a partial hub here - vi.spyOn(SentryNode, 'getCurrentHub').mockImplementation(() => { - return { - getScope: () => ({ + const setUserMock = vi.fn(); + + beforeEach(() => { + vi.spyOn(SentryNode, 'getCurrentScope').mockImplementation(() => { + return { + setUser: setUserMock, + setPropagationContext: vi.fn(), getSpan: getSpanMock, - }), - getClient: () => ({}), - }; + } as any; + }); + vi.spyOn(SentryNode, 'getClient').mockImplementation(() => ({}) as Client); }); const nextResult = Promise.resolve(new Response(null, { status: 200, headers: new Headers() })); @@ -69,6 +73,43 @@ describe('sentryMiddleware', () => { expect(resultFromNext).toStrictEqual(nextResult); }); + it("sets source route if the url couldn't be decoded correctly", async () => { + const middleware = handleRequest(); + const ctx = { + request: { + method: 'GET', + url: '/a%xx', + headers: new Headers(), + }, + url: { pathname: 'a%xx', href: 'http://localhost:1234/a%xx' }, + params: {}, + }; + const next = vi.fn(() => nextResult); + + // @ts-expect-error, a partial ctx object is fine here + const resultFromNext = middleware(ctx, next); + + expect(startSpanSpy).toHaveBeenCalledWith( + { + data: { + method: 'GET', + url: 'http://localhost:1234/a%xx', + }, + metadata: { + source: 'url', + }, + name: 'GET a%xx', + op: 'http.server', + origin: 'auto.http.astro', + status: 'ok', + }, + expect.any(Function), // the `next` function + ); + + expect(next).toHaveBeenCalled(); + expect(resultFromNext).toStrictEqual(nextResult); + }); + it('throws and sends an error to sentry if `next()` throws', async () => { const captureExceptionSpy = vi.spyOn(SentryNode, 'captureException'); @@ -133,10 +174,6 @@ describe('sentryMiddleware', () => { }); it('attaches client IP and request headers if options are set', async () => { - const scope = { setUser: vi.fn(), setPropagationContext: vi.fn() }; - // @ts-expect-error, only passing a partial Scope object - const configureScopeSpy = vi.spyOn(SentryNode, 'configureScope').mockImplementation(cb => cb(scope)); - const middleware = handleRequest({ trackClientIp: true, trackHeaders: true }); const ctx = { request: { @@ -155,8 +192,7 @@ describe('sentryMiddleware', () => { // @ts-expect-error, a partial ctx object is fine here await middleware(ctx, next); - expect(configureScopeSpy).toHaveBeenCalledTimes(1); - expect(scope.setUser).toHaveBeenCalledWith({ ip_address: '192.168.0.1' }); + expect(setUserMock).toHaveBeenCalledWith({ ip_address: '192.168.0.1' }); expect(startSpanSpy).toHaveBeenCalledWith( expect.objectContaining({ @@ -299,15 +335,31 @@ describe('sentryMiddleware', () => { describe('interpolateRouteFromUrlAndParams', () => { it.each([ + ['/', {}, '/'], ['/foo/bar', {}, '/foo/bar'], ['/users/123', { id: '123' }, '/users/[id]'], ['/users/123', { id: '123', foo: 'bar' }, '/users/[id]'], ['/lang/en-US', { lang: 'en', region: 'US' }, '/lang/[lang]-[region]'], ['/lang/en-US/posts', { lang: 'en', region: 'US' }, '/lang/[lang]-[region]/posts'], + // edge cases that astro doesn't support + ['/lang/-US', { region: 'US' }, '/lang/-[region]'], + ['/lang/en-', { lang: 'en' }, '/lang/[lang]-'], ])('interpolates route from URL and params %s', (rawUrl, params, expectedRoute) => { expect(interpolateRouteFromUrlAndParams(rawUrl, params)).toEqual(expectedRoute); }); + it.each([ + ['/(a+)+/aaaaaaaaa!', { id: '(a+)+', slug: 'aaaaaaaaa!' }, '/[id]/[slug]'], + ['/([a-zA-Z]+)*/aaaaaaaaa!', { id: '([a-zA-Z]+)*', slug: 'aaaaaaaaa!' }, '/[id]/[slug]'], + ['/(a|aa)+/aaaaaaaaa!', { id: '(a|aa)+', slug: 'aaaaaaaaa!' }, '/[id]/[slug]'], + ['/(a|a?)+/aaaaaaaaa!', { id: '(a|a?)+', slug: 'aaaaaaaaa!' }, '/[id]/[slug]'], + // with URL encoding + ['/(a%7Caa)+/aaaaaaaaa!', { id: '(a|aa)+', slug: 'aaaaaaaaa!' }, '/[id]/[slug]'], + ['/(a%7Ca?)+/aaaaaaaaa!', { id: '(a|a?)+', slug: 'aaaaaaaaa!' }, '/[id]/[slug]'], + ])('handles regex characters in param values correctly %s', (rawUrl, params, expectedRoute) => { + expect(interpolateRouteFromUrlAndParams(rawUrl, params)).toEqual(expectedRoute); + }); + it('handles params across multiple URL segments in catchall routes', () => { // Ideally, Astro would let us know that this is a catchall route so we can make the param [...catchall] but it doesn't expect( @@ -324,4 +376,11 @@ describe('interpolateRouteFromUrlAndParams', () => { const expectedRoute = '/usernames/[name]'; expect(interpolateRouteFromUrlAndParams(rawUrl, params)).toEqual(expectedRoute); }); + + it('handles set but undefined params', () => { + const rawUrl = '/usernames/user'; + const params = { name: undefined, name2: '' }; + const expectedRoute = '/usernames/user'; + expect(interpolateRouteFromUrlAndParams(rawUrl, params)).toEqual(expectedRoute); + }); }); diff --git a/packages/browser-integration-tests/package.json b/packages/browser-integration-tests/package.json index 253a7ac684f0..db268b859298 100644 --- a/packages/browser-integration-tests/package.json +++ b/packages/browser-integration-tests/package.json @@ -1,6 +1,6 @@ { "name": "@sentry-internal/browser-integration-tests", - "version": "7.86.0", + "version": "7.89.0", "main": "index.js", "license": "MIT", "engines": { diff --git a/packages/browser-integration-tests/suites/replay/dsc/test.ts b/packages/browser-integration-tests/suites/replay/dsc/test.ts index ffd2cf1877da..4468a254bde4 100644 --- a/packages/browser-integration-tests/suites/replay/dsc/test.ts +++ b/packages/browser-integration-tests/suites/replay/dsc/test.ts @@ -21,6 +21,9 @@ sentryTest( const transactionReq = waitForTransactionRequest(page); + // Wait for this to be available + await page.waitForFunction('!!window.Replay'); + await page.evaluate(() => { (window as unknown as TestWindow).Replay.start(); }); @@ -28,10 +31,9 @@ sentryTest( await waitForReplayRunning(page); await page.evaluate(() => { - (window as unknown as TestWindow).Sentry.configureScope(scope => { - scope.setUser({ id: 'user123', segment: 'segmentB' }); - scope.setTransactionName('testTransactionDSC'); - }); + const scope = (window as unknown as TestWindow).Sentry.getCurrentScope(); + scope.setUser({ id: 'user123', segment: 'segmentB' }); + scope.setTransactionName('testTransactionDSC'); }); const req0 = await transactionReq; @@ -74,10 +76,9 @@ sentryTest( await waitForReplayRunning(page); await page.evaluate(() => { - (window as unknown as TestWindow).Sentry.configureScope(scope => { - scope.setUser({ id: 'user123', segment: 'segmentB' }); - scope.setTransactionName('testTransactionDSC'); - }); + const scope = (window as unknown as TestWindow).Sentry.getCurrentScope(); + scope.setUser({ id: 'user123', segment: 'segmentB' }); + scope.setTransactionName('testTransactionDSC'); }); const req0 = await transactionReq; @@ -132,10 +133,9 @@ sentryTest( }); await page.evaluate(() => { - (window as unknown as TestWindow).Sentry.configureScope(scope => { - scope.setUser({ id: 'user123', segment: 'segmentB' }); - scope.setTransactionName('testTransactionDSC'); - }); + const scope = (window as unknown as TestWindow).Sentry.getCurrentScope(); + scope.setUser({ id: 'user123', segment: 'segmentB' }); + scope.setTransactionName('testTransactionDSC'); }); const req0 = await transactionReq; @@ -181,10 +181,9 @@ sentryTest( const transactionReq = waitForTransactionRequest(page); await page.evaluate(async () => { - (window as unknown as TestWindow).Sentry.configureScope(scope => { - scope.setUser({ id: 'user123', segment: 'segmentB' }); - scope.setTransactionName('testTransactionDSC'); - }); + const scope = (window as unknown as TestWindow).Sentry.getCurrentScope(); + scope.setUser({ id: 'user123', segment: 'segmentB' }); + scope.setTransactionName('testTransactionDSC'); }); const req0 = await transactionReq; diff --git a/packages/browser-integration-tests/suites/tracing/envelope-header-transaction-name/init.js b/packages/browser-integration-tests/suites/tracing/envelope-header-transaction-name/init.js index efb7b577f75b..7d000c0ac2cd 100644 --- a/packages/browser-integration-tests/suites/tracing/envelope-header-transaction-name/init.js +++ b/packages/browser-integration-tests/suites/tracing/envelope-header-transaction-name/init.js @@ -11,8 +11,7 @@ Sentry.init({ debug: true, }); -Sentry.configureScope(scope => { - scope.setUser({ id: 'user123', segment: 'segmentB' }); - scope.setTransactionName('testTransactionDSC'); - scope.getTransaction().setMetadata({ source: 'custom' }); -}); +const scope = Sentry.getCurrentScope(); +scope.setUser({ id: 'user123', segment: 'segmentB' }); +scope.setTransactionName('testTransactionDSC'); +scope.getTransaction().setMetadata({ source: 'custom' }); diff --git a/packages/browser-integration-tests/suites/tracing/envelope-header/init.js b/packages/browser-integration-tests/suites/tracing/envelope-header/init.js index fbce5a16116a..f382a49c153d 100644 --- a/packages/browser-integration-tests/suites/tracing/envelope-header/init.js +++ b/packages/browser-integration-tests/suites/tracing/envelope-header/init.js @@ -11,7 +11,6 @@ Sentry.init({ debug: true, }); -Sentry.configureScope(scope => { - scope.setUser({ id: 'user123', segment: 'segmentB' }); - scope.setTransactionName('testTransactionDSC'); -}); +const scope = Sentry.getCurrentScope(); +scope.setUser({ id: 'user123', segment: 'segmentB' }); +scope.setTransactionName('testTransactionDSC'); diff --git a/packages/browser/package.json b/packages/browser/package.json index 7f41376f2db1..f47e4c89b373 100644 --- a/packages/browser/package.json +++ b/packages/browser/package.json @@ -1,6 +1,6 @@ { "name": "@sentry/browser", - "version": "7.86.0", + "version": "7.89.0", "description": "Official Sentry SDK for browsers", "repository": "git://github.com/getsentry/sentry-javascript.git", "homepage": "https://github.com/getsentry/sentry-javascript/tree/master/packages/browser", @@ -23,15 +23,15 @@ "access": "public" }, "dependencies": { - "@sentry-internal/feedback": "7.86.0", - "@sentry-internal/tracing": "7.86.0", - "@sentry/core": "7.86.0", - "@sentry/replay": "7.86.0", - "@sentry/types": "7.86.0", - "@sentry/utils": "7.86.0" + "@sentry-internal/feedback": "7.89.0", + "@sentry-internal/tracing": "7.89.0", + "@sentry/core": "7.89.0", + "@sentry/replay": "7.89.0", + "@sentry/types": "7.89.0", + "@sentry/utils": "7.89.0" }, "devDependencies": { - "@sentry-internal/integration-shims": "7.86.0", + "@sentry-internal/integration-shims": "7.89.0", "@types/md5": "2.1.33", "btoa": "^1.2.1", "chai": "^4.1.2", diff --git a/packages/browser/src/eventbuilder.ts b/packages/browser/src/eventbuilder.ts index e361f1366cf3..6955fbfa26fe 100644 --- a/packages/browser/src/eventbuilder.ts +++ b/packages/browser/src/eventbuilder.ts @@ -1,4 +1,4 @@ -import { getCurrentHub } from '@sentry/core'; +import { getClient } from '@sentry/core'; import type { Event, EventHint, Exception, Severity, SeverityLevel, StackFrame, StackParser } from '@sentry/types'; import { addExceptionMechanism, @@ -48,8 +48,7 @@ export function eventFromPlainObject( syntheticException?: Error, isUnhandledRejection?: boolean, ): Event { - const hub = getCurrentHub(); - const client = hub.getClient(); + const client = getClient(); const normalizeDepth = client && client.getOptions().normalizeDepth; const event: Event = { diff --git a/packages/browser/src/exports.ts b/packages/browser/src/exports.ts index 0804dbe49ac0..cc9712517b2b 100644 --- a/packages/browser/src/exports.ts +++ b/packages/browser/src/exports.ts @@ -30,12 +30,14 @@ export { captureEvent, captureMessage, close, + // eslint-disable-next-line deprecation/deprecation configureScope, createTransport, flush, getHubFromCarrier, getCurrentHub, getClient, + getCurrentScope, Hub, lastEventId, makeMain, @@ -56,6 +58,7 @@ export { withScope, FunctionToString, InboundFilters, + metrics, } from '@sentry/core'; export { WINDOW } from './helpers'; diff --git a/packages/browser/src/integrations/breadcrumbs.ts b/packages/browser/src/integrations/breadcrumbs.ts index e36641c48ed1..d46846c4d3f2 100644 --- a/packages/browser/src/integrations/breadcrumbs.ts +++ b/packages/browser/src/integrations/breadcrumbs.ts @@ -1,5 +1,5 @@ /* eslint-disable max-lines */ -import { getClient, getCurrentHub } from '@sentry/core'; +import { addBreadcrumb, getClient } from '@sentry/core'; import type { Event as SentryEvent, HandlerDataConsole, @@ -125,7 +125,7 @@ export class Breadcrumbs implements Integration { * Adds a breadcrumb for Sentry events or transactions if this option is enabled. */ function addSentryBreadcrumb(event: SentryEvent): void { - getCurrentHub().addBreadcrumb( + addBreadcrumb( { category: `sentry.${event.type === 'transaction' ? 'transaction' : 'event'}`, event_id: event.event_id, @@ -187,7 +187,7 @@ function _domBreadcrumb(dom: BreadcrumbsOptions['dom']): (handlerData: HandlerDa breadcrumb.data = { componentName }; } - getCurrentHub().addBreadcrumb(breadcrumb, { + addBreadcrumb(breadcrumb, { event: handlerData.event, name: handlerData.name, global: handlerData.global, @@ -221,7 +221,7 @@ function _consoleBreadcrumb(handlerData: HandlerDataConsole): void { } } - getCurrentHub().addBreadcrumb(breadcrumb, { + addBreadcrumb(breadcrumb, { input: handlerData.args, level: handlerData.level, }); @@ -255,7 +255,7 @@ function _xhrBreadcrumb(handlerData: HandlerDataXhr): void { endTimestamp, }; - getCurrentHub().addBreadcrumb( + addBreadcrumb( { category: 'xhr', data, @@ -290,7 +290,7 @@ function _fetchBreadcrumb(handlerData: HandlerDataFetch): void { endTimestamp, }; - getCurrentHub().addBreadcrumb( + addBreadcrumb( { category: 'fetch', data, @@ -311,7 +311,7 @@ function _fetchBreadcrumb(handlerData: HandlerDataFetch): void { startTimestamp, endTimestamp, }; - getCurrentHub().addBreadcrumb( + addBreadcrumb( { category: 'fetch', data, @@ -346,7 +346,7 @@ function _historyBreadcrumb(handlerData: HandlerDataHistory): void { from = parsedFrom.relative; } - getCurrentHub().addBreadcrumb({ + addBreadcrumb({ category: 'navigation', data: { from, diff --git a/packages/browser/src/integrations/globalhandlers.ts b/packages/browser/src/integrations/globalhandlers.ts index 0c3f3be60e2d..079ef6083212 100644 --- a/packages/browser/src/integrations/globalhandlers.ts +++ b/packages/browser/src/integrations/globalhandlers.ts @@ -1,6 +1,6 @@ /* eslint-disable @typescript-eslint/no-unsafe-member-access */ -import { getCurrentHub } from '@sentry/core'; -import type { Event, Hub, Integration, Primitive, StackParser } from '@sentry/types'; +import { captureEvent, getClient } from '@sentry/core'; +import type { Client, Event, Integration, Primitive, StackParser } from '@sentry/types'; import { addGlobalErrorInstrumentationHandler, addGlobalUnhandledRejectionInstrumentationHandler, @@ -36,12 +36,6 @@ export class GlobalHandlers implements Integration { /** JSDoc */ private readonly _options: GlobalHandlersIntegrations; - /** - * Stores references functions to installing handlers. Will set to undefined - * after they have been run so that they are not used twice. - */ - private _installFunc: Record void) | undefined>; - /** JSDoc */ public constructor(options?: GlobalHandlersIntegrations) { this.name = GlobalHandlers.id; @@ -50,43 +44,36 @@ export class GlobalHandlers implements Integration { onunhandledrejection: true, ...options, }; - - this._installFunc = { - onerror: _installGlobalOnErrorHandler, - onunhandledrejection: _installGlobalOnUnhandledRejectionHandler, - }; } /** * @inheritDoc */ public setupOnce(): void { Error.stackTraceLimit = 50; - const options = this._options; - - // We can disable guard-for-in as we construct the options object above + do checks against - // `this._installFunc` for the property. - // eslint-disable-next-line guard-for-in - for (const key in options) { - const installFunc = this._installFunc[key as GlobalHandlersIntegrationsOptionKeys]; - if (installFunc && options[key as GlobalHandlersIntegrationsOptionKeys]) { - globalHandlerLog(key); - installFunc(); - this._installFunc[key as GlobalHandlersIntegrationsOptionKeys] = undefined; - } + } + + /** @inheritdoc */ + public setup(client: Client): void { + if (this._options.onerror) { + _installGlobalOnErrorHandler(client); + globalHandlerLog('onerror'); + } + if (this._options.onunhandledrejection) { + _installGlobalOnUnhandledRejectionHandler(client); + globalHandlerLog('onunhandledrejection'); } } } -function _installGlobalOnErrorHandler(): void { +function _installGlobalOnErrorHandler(client: Client): void { addGlobalErrorInstrumentationHandler(data => { - const [hub, stackParser, attachStacktrace] = getHubAndOptions(); - if (!hub.getIntegration(GlobalHandlers)) { + const { stackParser, attachStacktrace } = getOptions(); + + if (getClient() !== client || shouldIgnoreOnError()) { return; } + const { msg, url, line, column, error } = data; - if (shouldIgnoreOnError()) { - return; - } const event = error === undefined && isString(msg) @@ -100,7 +87,7 @@ function _installGlobalOnErrorHandler(): void { event.level = 'error'; - hub.captureEvent(event, { + captureEvent(event, { originalException: error, mechanism: { handled: false, @@ -110,15 +97,12 @@ function _installGlobalOnErrorHandler(): void { }); } -function _installGlobalOnUnhandledRejectionHandler(): void { +function _installGlobalOnUnhandledRejectionHandler(client: Client): void { addGlobalUnhandledRejectionInstrumentationHandler(e => { - const [hub, stackParser, attachStacktrace] = getHubAndOptions(); - if (!hub.getIntegration(GlobalHandlers)) { - return; - } + const { stackParser, attachStacktrace } = getOptions(); - if (shouldIgnoreOnError()) { - return true; + if (getClient() !== client || shouldIgnoreOnError()) { + return; } const error = _getUnhandledRejectionError(e as unknown); @@ -129,15 +113,13 @@ function _installGlobalOnUnhandledRejectionHandler(): void { event.level = 'error'; - hub.captureEvent(event, { + captureEvent(event, { originalException: error, mechanism: { handled: false, type: 'onunhandledrejection', }, }); - - return; }); } @@ -258,12 +240,11 @@ function globalHandlerLog(type: string): void { DEBUG_BUILD && logger.log(`Global Handler attached: ${type}`); } -function getHubAndOptions(): [Hub, StackParser, boolean | undefined] { - const hub = getCurrentHub(); - const client = hub.getClient(); +function getOptions(): { stackParser: StackParser; attachStacktrace?: boolean } { + const client = getClient(); const options = (client && client.getOptions()) || { stackParser: () => [], attachStacktrace: false, }; - return [hub, options.stackParser, options.attachStacktrace]; + return options; } diff --git a/packages/browser/src/profiling/integration.ts b/packages/browser/src/profiling/integration.ts index 3f5251c4583f..5173705feaa6 100644 --- a/packages/browser/src/profiling/integration.ts +++ b/packages/browser/src/profiling/integration.ts @@ -1,4 +1,5 @@ -import type { EventProcessor, Hub, Integration, Transaction } from '@sentry/types'; +import { getCurrentScope } from '@sentry/core'; +import type { Client, EventEnvelope, EventProcessor, Hub, Integration, Transaction } from '@sentry/types'; import type { Profile } from '@sentry/types/src/profiling'; import { logger } from '@sentry/utils'; @@ -29,6 +30,7 @@ export class BrowserProfilingIntegration implements Integration { public readonly name: string; + /** @deprecated This is never set. */ public getCurrentHub?: () => Hub; public constructor() { @@ -38,12 +40,13 @@ export class BrowserProfilingIntegration implements Integration { /** * @inheritDoc */ - public setupOnce(_addGlobalEventProcessor: (callback: EventProcessor) => void, getCurrentHub: () => Hub): void { - this.getCurrentHub = getCurrentHub; + public setupOnce(_addGlobalEventProcessor: (callback: EventProcessor) => void, _getCurrentHub: () => Hub): void { + // noop + } - const hub = this.getCurrentHub(); - const client = hub.getClient(); - const scope = hub.getScope(); + /** @inheritdoc */ + public setup(client: Client): void { + const scope = getCurrentScope(); const transaction = scope.getTransaction(); @@ -53,67 +56,68 @@ export class BrowserProfilingIntegration implements Integration { } } - if (client && typeof client.on === 'function') { - client.on('startTransaction', (transaction: Transaction) => { - if (shouldProfileTransaction(transaction)) { - startProfileForTransaction(transaction); + if (typeof client.on !== 'function') { + logger.warn('[Profiling] Client does not support hooks, profiling will be disabled'); + return; + } + + client.on('startTransaction', (transaction: Transaction) => { + if (shouldProfileTransaction(transaction)) { + startProfileForTransaction(transaction); + } + }); + + client.on('beforeEnvelope', (envelope): void => { + // if not profiles are in queue, there is nothing to add to the envelope. + if (!getActiveProfilesCount()) { + return; + } + + const profiledTransactionEvents = findProfiledTransactionsFromEnvelope(envelope); + if (!profiledTransactionEvents.length) { + return; + } + + const profilesToAddToEnvelope: Profile[] = []; + + for (const profiledTransaction of profiledTransactionEvents) { + const context = profiledTransaction && profiledTransaction.contexts; + const profile_id = context && context['profile'] && context['profile']['profile_id']; + const start_timestamp = context && context['profile'] && context['profile']['start_timestamp']; + + if (typeof profile_id !== 'string') { + DEBUG_BUILD && logger.log('[Profiling] cannot find profile for a transaction without a profile context'); + continue; } - }); - client.on('beforeEnvelope', (envelope): void => { - // if not profiles are in queue, there is nothing to add to the envelope. - if (!getActiveProfilesCount()) { - return; + if (!profile_id) { + DEBUG_BUILD && logger.log('[Profiling] cannot find profile for a transaction without a profile context'); + continue; } - const profiledTransactionEvents = findProfiledTransactionsFromEnvelope(envelope); - if (!profiledTransactionEvents.length) { - return; + // Remove the profile from the transaction context before sending, relay will take care of the rest. + if (context && context['profile']) { + delete context.profile; } - const profilesToAddToEnvelope: Profile[] = []; - - for (const profiledTransaction of profiledTransactionEvents) { - const context = profiledTransaction && profiledTransaction.contexts; - const profile_id = context && context['profile'] && context['profile']['profile_id']; - const start_timestamp = context && context['profile'] && context['profile']['start_timestamp']; - - if (typeof profile_id !== 'string') { - DEBUG_BUILD && logger.log('[Profiling] cannot find profile for a transaction without a profile context'); - continue; - } - - if (!profile_id) { - DEBUG_BUILD && logger.log('[Profiling] cannot find profile for a transaction without a profile context'); - continue; - } - - // Remove the profile from the transaction context before sending, relay will take care of the rest. - if (context && context['profile']) { - delete context.profile; - } - - const profile = takeProfileFromGlobalCache(profile_id); - if (!profile) { - DEBUG_BUILD && logger.log(`[Profiling] Could not retrieve profile for transaction: ${profile_id}`); - continue; - } - - const profileEvent = createProfilingEvent( - profile_id, - start_timestamp as number | undefined, - profile, - profiledTransaction as ProfiledEvent, - ); - if (profileEvent) { - profilesToAddToEnvelope.push(profileEvent); - } + const profile = takeProfileFromGlobalCache(profile_id); + if (!profile) { + DEBUG_BUILD && logger.log(`[Profiling] Could not retrieve profile for transaction: ${profile_id}`); + continue; } - addProfilesToEnvelope(envelope, profilesToAddToEnvelope); - }); - } else { - logger.warn('[Profiling] Client does not support hooks, profiling will be disabled'); - } + const profileEvent = createProfilingEvent( + profile_id, + start_timestamp as number | undefined, + profile, + profiledTransaction as ProfiledEvent, + ); + if (profileEvent) { + profilesToAddToEnvelope.push(profileEvent); + } + } + + addProfilesToEnvelope(envelope as EventEnvelope, profilesToAddToEnvelope); + }); } } diff --git a/packages/browser/src/profiling/utils.ts b/packages/browser/src/profiling/utils.ts index 1aac3d397ca7..f2fdc5e4c10d 100644 --- a/packages/browser/src/profiling/utils.ts +++ b/packages/browser/src/profiling/utils.ts @@ -1,7 +1,7 @@ /* eslint-disable max-lines */ -import { DEFAULT_ENVIRONMENT, getClient, getCurrentHub } from '@sentry/core'; -import type { DebugImage, Envelope, Event, StackFrame, StackParser, Transaction } from '@sentry/types'; +import { DEFAULT_ENVIRONMENT, getClient } from '@sentry/core'; +import type { DebugImage, Envelope, Event, EventEnvelope, StackFrame, StackParser, Transaction } from '@sentry/types'; import type { Profile, ThreadCpuProfile } from '@sentry/types/src/profiling'; import { GLOBAL_OBJ, browserPerformanceTimeOrigin, forEachEnvelopeItem, logger, uuid4 } from '@sentry/utils'; @@ -300,13 +300,12 @@ export function convertJSSelfProfileToSampledFormat(input: JSSelfProfile): Profi * Adds items to envelope if they are not already present - mutates the envelope. * @param envelope */ -export function addProfilesToEnvelope(envelope: Envelope, profiles: Profile[]): Envelope { +export function addProfilesToEnvelope(envelope: EventEnvelope, profiles: Profile[]): Envelope { if (!profiles.length) { return envelope; } for (const profile of profiles) { - // @ts-expect-error untyped envelope envelope[1].push([{ type: 'profile' }, profile]); } return envelope; @@ -348,19 +347,10 @@ export function applyDebugMetadata(resource_paths: ReadonlyArray): Debug return []; } - const hub = getCurrentHub(); - if (!hub) { - return []; - } - const client = hub.getClient(); - if (!client) { - return []; - } - const options = client.getOptions(); - if (!options) { - return []; - } - const stackParser = options.stackParser; + const client = getClient(); + const options = client && client.getOptions(); + const stackParser = options && options.stackParser; + if (!stackParser) { return []; } diff --git a/packages/browser/test/unit/index.test.ts b/packages/browser/test/unit/index.test.ts index bc0058ba7d16..5968349adc1a 100644 --- a/packages/browser/test/unit/index.test.ts +++ b/packages/browser/test/unit/index.test.ts @@ -12,10 +12,10 @@ import { captureEvent, captureException, captureMessage, - configureScope, flush, getClient, getCurrentHub, + getCurrentScope, init, showReportDialog, wrap, @@ -37,9 +37,10 @@ jest.mock('@sentry/core', () => { }); describe('SentryBrowser', () => { - const beforeSend = jest.fn(); + const beforeSend = jest.fn(event => event); - beforeAll(() => { + beforeEach(() => { + WINDOW.__SENTRY__ = { hub: undefined, logger: undefined, globalEventProcessors: [] }; init({ beforeSend, dsn, @@ -47,39 +48,28 @@ describe('SentryBrowser', () => { }); }); - beforeEach(() => { - getCurrentHub().pushScope(); - }); - afterEach(() => { - getCurrentHub().popScope(); - beforeSend.mockReset(); + beforeSend.mockClear(); }); describe('getContext() / setContext()', () => { it('should store/load extra', () => { - configureScope((scope: Scope) => { - scope.setExtra('abc', { def: [1] }); - }); - expect(global.__SENTRY__.hub._stack[1].scope._extra).toEqual({ + getCurrentScope().setExtra('abc', { def: [1] }); + expect(global.__SENTRY__.hub._stack[0].scope._extra).toEqual({ abc: { def: [1] }, }); }); it('should store/load tags', () => { - configureScope((scope: Scope) => { - scope.setTag('abc', 'def'); - }); - expect(global.__SENTRY__.hub._stack[1].scope._tags).toEqual({ + getCurrentScope().setTag('abc', 'def'); + expect(global.__SENTRY__.hub._stack[0].scope._tags).toEqual({ abc: 'def', }); }); it('should store/load user', () => { - configureScope((scope: Scope) => { - scope.setUser({ id: 'def' }); - }); - expect(global.__SENTRY__.hub._stack[1].scope._user).toEqual({ + getCurrentScope().setUser({ id: 'def' }); + expect(global.__SENTRY__.hub._stack[0].scope._user).toEqual({ id: 'def', }); }); @@ -95,9 +85,7 @@ describe('SentryBrowser', () => { const options = getDefaultBrowserClientOptions({ dsn }); const client = new BrowserClient(options); it('uses the user on the scope', () => { - configureScope(scope => { - scope.setUser(EX_USER); - }); + getCurrentScope().setUser(EX_USER); getCurrentHub().bindClient(client); showReportDialog(); @@ -110,9 +98,7 @@ describe('SentryBrowser', () => { }); it('prioritizes options user over scope user', () => { - configureScope(scope => { - scope.setUser(EX_USER); - }); + getCurrentScope().setUser(EX_USER); getCurrentHub().bindClient(client); const DIALOG_OPTION_USER = { email: 'option@example.com' }; diff --git a/packages/browser/test/unit/integrations/breadcrumbs.test.ts b/packages/browser/test/unit/integrations/breadcrumbs.test.ts index d81107a69c38..e87454737482 100644 --- a/packages/browser/test/unit/integrations/breadcrumbs.test.ts +++ b/packages/browser/test/unit/integrations/breadcrumbs.test.ts @@ -1,4 +1,4 @@ -import { getCurrentHub } from '@sentry/core'; +import * as SentryCore from '@sentry/core'; import type { Client } from '@sentry/types'; import { Breadcrumbs, BrowserClient, Hub, flush } from '../../../src'; @@ -18,21 +18,20 @@ jest.mock('@sentry/core', () => { describe('Breadcrumbs', () => { it('Should add sentry breadcrumb', async () => { - const addBreadcrumb = jest.fn(); - hub.addBreadcrumb = addBreadcrumb; - client = new BrowserClient({ ...getDefaultBrowserClientOptions(), dsn: 'https://username@domain/123', integrations: [new Breadcrumbs()], }); - getCurrentHub().bindClient(client); + SentryCore.getCurrentHub().bindClient(client); + + const addBreadcrumbSpy = jest.spyOn(SentryCore, 'addBreadcrumb').mockImplementation(() => {}); client.captureMessage('test'); await flush(2000); - expect(addBreadcrumb.mock.calls[0][0].category).toEqual('sentry.event'); - expect(addBreadcrumb.mock.calls[0][0].message).toEqual('test'); + expect(addBreadcrumbSpy.mock.calls[0][0].category).toEqual('sentry.event'); + expect(addBreadcrumbSpy.mock.calls[0][0].message).toEqual('test'); }); }); diff --git a/packages/bun/package.json b/packages/bun/package.json index 3ba1c0b9461d..0d7bb7b19edb 100644 --- a/packages/bun/package.json +++ b/packages/bun/package.json @@ -1,6 +1,6 @@ { "name": "@sentry/bun", - "version": "7.86.0", + "version": "7.89.0", "description": "Official Sentry SDK for bun", "repository": "git://github.com/getsentry/sentry-javascript.git", "homepage": "https://github.com/getsentry/sentry-javascript/tree/master/packages/bun", @@ -23,10 +23,10 @@ "access": "public" }, "dependencies": { - "@sentry/core": "7.86.0", - "@sentry/node": "7.86.0", - "@sentry/types": "7.86.0", - "@sentry/utils": "7.86.0" + "@sentry/core": "7.89.0", + "@sentry/node": "7.89.0", + "@sentry/types": "7.89.0", + "@sentry/utils": "7.89.0" }, "devDependencies": { "bun-types": "latest" diff --git a/packages/bun/src/index.ts b/packages/bun/src/index.ts index 302d36fb0b62..499e969f3843 100644 --- a/packages/bun/src/index.ts +++ b/packages/bun/src/index.ts @@ -33,6 +33,7 @@ export { captureEvent, captureMessage, close, + // eslint-disable-next-line deprecation/deprecation configureScope, createTransport, // eslint-disable-next-line deprecation/deprecation @@ -42,6 +43,7 @@ export { getHubFromCarrier, getCurrentHub, getClient, + getCurrentScope, Hub, lastEventId, makeMain, diff --git a/packages/core/package.json b/packages/core/package.json index f508338d95f6..45d214a9933a 100644 --- a/packages/core/package.json +++ b/packages/core/package.json @@ -1,6 +1,6 @@ { "name": "@sentry/core", - "version": "7.86.0", + "version": "7.89.0", "description": "Base implementation for all Sentry JavaScript SDKs", "repository": "git://github.com/getsentry/sentry-javascript.git", "homepage": "https://github.com/getsentry/sentry-javascript/tree/master/packages/core", @@ -23,8 +23,8 @@ "access": "public" }, "dependencies": { - "@sentry/types": "7.86.0", - "@sentry/utils": "7.86.0" + "@sentry/types": "7.89.0", + "@sentry/utils": "7.89.0" }, "scripts": { "build": "run-p build:transpile build:types", diff --git a/packages/core/src/baseclient.ts b/packages/core/src/baseclient.ts index 0ea80e229c58..3fbdd13250f8 100644 --- a/packages/core/src/baseclient.ts +++ b/packages/core/src/baseclient.ts @@ -16,6 +16,8 @@ import type { FeedbackEvent, Integration, IntegrationClass, + MetricBucketItem, + MetricsAggregator, Outcome, PropagationContext, SdkMetadata, @@ -46,9 +48,10 @@ import { import { getEnvelopeEndpointWithUrlEncodedAuth } from './api'; import { DEBUG_BUILD } from './debug-build'; import { createEventEnvelope, createSessionEnvelope } from './envelope'; -import { getCurrentHub } from './hub'; +import { getClient } from './exports'; import type { IntegrationIndex } from './integration'; import { setupIntegration, setupIntegrations } from './integration'; +import { createMetricEnvelope } from './metrics/envelope'; import type { Scope } from './scope'; import { updateSession } from './session'; import { getDynamicSamplingContextFromClient } from './tracing/dynamicSamplingContext'; @@ -88,6 +91,13 @@ const ALREADY_SEEN_ERROR = "Not capturing exception because it's already been ca * } */ export abstract class BaseClient implements Client { + /** + * A reference to a metrics aggregator + * + * @experimental Note this is alpha API. It may experience breaking changes in the future. + */ + public metricsAggregator?: MetricsAggregator; + /** Options passed to the SDK. */ protected readonly _options: O; @@ -105,14 +115,14 @@ export abstract class BaseClient implements Client { /** Number of calls being processed */ protected _numProcessing: number; + protected _eventProcessors: EventProcessor[]; + /** Holds flushable */ private _outcomes: { [key: string]: number }; // eslint-disable-next-line @typescript-eslint/ban-types private _hooks: Record; - private _eventProcessors: EventProcessor[]; - /** * Initializes this client instance. * @@ -264,6 +274,9 @@ export abstract class BaseClient implements Client { public flush(timeout?: number): PromiseLike { const transport = this._transport; if (transport) { + if (this.metricsAggregator) { + this.metricsAggregator.flush(); + } return this._isClientDoneProcessing(timeout).then(clientFinished => { return transport.flush(timeout).then(transportFlushed => clientFinished && transportFlushed); }); @@ -278,6 +291,9 @@ export abstract class BaseClient implements Client { public close(timeout?: number): PromiseLike { return this.flush(timeout).then(result => { this.getOptions().enabled = false; + if (this.metricsAggregator) { + this.metricsAggregator.close(); + } return result; }); } @@ -383,6 +399,19 @@ export abstract class BaseClient implements Client { } } + /** + * @inheritDoc + */ + public captureAggregateMetrics(metricBucketItems: Array): void { + const metricsEnvelope = createMetricEnvelope( + metricBucketItems, + this._dsn, + this._options._metadata, + this._options.tunnel, + ); + void this._sendEnvelope(metricsEnvelope); + } + // Keep on() & emit() signatures in sync with types' client.ts interface /* eslint-disable @typescript-eslint/unified-signatures */ @@ -841,7 +870,7 @@ function isTransactionEvent(event: Event): event is TransactionEvent { * This event processor will run for all events processed by this client. */ export function addEventProcessor(callback: EventProcessor): void { - const client = getCurrentHub().getClient(); + const client = getClient(); if (!client || !client.addEventProcessor) { return; diff --git a/packages/core/src/exports.ts b/packages/core/src/exports.ts index 6d1e80600a75..95c1e4b63de3 100644 --- a/packages/core/src/exports.ts +++ b/packages/core/src/exports.ts @@ -1,5 +1,6 @@ import type { Breadcrumb, + BreadcrumbHint, CaptureContext, CheckIn, Client, @@ -77,8 +78,11 @@ export function captureEvent(event: Event, hint?: EventHint): ReturnType void): ReturnType { + // eslint-disable-next-line deprecation/deprecation getCurrentHub().configureScope(callback); } @@ -90,8 +94,8 @@ export function configureScope(callback: (scope: Scope) => void): ReturnType { - getCurrentHub().addBreadcrumb(breadcrumb); +export function addBreadcrumb(breadcrumb: Breadcrumb, hint?: BreadcrumbHint): ReturnType { + getCurrentHub().addBreadcrumb(breadcrumb, hint); } /** @@ -163,8 +167,8 @@ export function setUser(user: User | null): ReturnType { * * @param callback that will be enclosed into push/popScope. */ -export function withScope(callback: (scope: Scope) => void): ReturnType { - getCurrentHub().withScope(callback); +export function withScope(callback: (scope: Scope) => T): T { + return getCurrentHub().withScope(callback); } /** @@ -202,9 +206,8 @@ export function startTransaction( * to create a monitor automatically when sending a check in. */ export function captureCheckIn(checkIn: CheckIn, upsertMonitorConfig?: MonitorConfig): string { - const hub = getCurrentHub(); - const scope = hub.getScope(); - const client = hub.getClient(); + const scope = getCurrentScope(); + const client = getClient(); if (!client) { DEBUG_BUILD && logger.warn('Cannot capture check-in. No client defined.'); } else if (!client.captureCheckIn) { @@ -308,3 +311,10 @@ export function lastEventId(): string | undefined { export function getClient(): C | undefined { return getCurrentHub().getClient(); } + +/** + * Get the currently active scope. + */ +export function getCurrentScope(): Scope { + return getCurrentHub().getScope(); +} diff --git a/packages/core/src/hub.ts b/packages/core/src/hub.ts index 8306d033cd75..75960550081a 100644 --- a/packages/core/src/hub.ts +++ b/packages/core/src/hub.ts @@ -139,10 +139,12 @@ export class Hub implements HubInterface { /** * @inheritDoc + * + * @deprecated Use `withScope` instead. */ public pushScope(): Scope { // We want to clone the content of prev scope - const scope = Scope.clone(this.getScope()); + const scope = this.getScope().clone(); this.getStack().push({ client: this.getClient(), scope, @@ -152,6 +154,8 @@ export class Hub implements HubInterface { /** * @inheritDoc + * + * @deprecated Use `withScope` instead. */ public popScope(): boolean { if (this.getStack().length <= 1) return false; @@ -161,11 +165,13 @@ export class Hub implements HubInterface { /** * @inheritDoc */ - public withScope(callback: (scope: Scope) => void): void { + public withScope(callback: (scope: Scope) => T): T { + // eslint-disable-next-line deprecation/deprecation const scope = this.pushScope(); try { - callback(scope); + return callback(scope); } finally { + // eslint-disable-next-line deprecation/deprecation this.popScope(); } } @@ -335,6 +341,8 @@ export class Hub implements HubInterface { /** * @inheritDoc + * + * @deprecated Use `getScope()` directly. */ public configureScope(callback: (scope: Scope) => void): void { const { scope, client } = this.getStackTop(); @@ -578,7 +586,7 @@ export function ensureHubOnCarrier(carrier: Carrier, parent: Hub = getGlobalHub( // If there's no hub on current domain, or it's an old API, assign a new one if (!hasHubOnCarrier(carrier) || getHubFromCarrier(carrier).isOlderThan(API_VERSION)) { const globalHubTopStack = parent.getStackTop(); - setHubOnCarrier(carrier, new Hub(globalHubTopStack.client, Scope.clone(globalHubTopStack.scope))); + setHubOnCarrier(carrier, new Hub(globalHubTopStack.client, globalHubTopStack.scope.clone())); } } diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts index 07871633f16c..08f18f38ade6 100644 --- a/packages/core/src/index.ts +++ b/packages/core/src/index.ts @@ -5,7 +5,7 @@ export type { ServerRuntimeClientOptions } from './server-runtime-client'; export type { RequestDataIntegrationOptions } from './integrations/requestdata'; export * from './tracing'; -export { createEventEnvelope } from './envelope'; +export { createEventEnvelope, createSessionEnvelope } from './envelope'; export { addBreadcrumb, captureCheckIn, @@ -14,6 +14,7 @@ export { captureEvent, captureMessage, close, + // eslint-disable-next-line deprecation/deprecation configureScope, flush, lastEventId, @@ -26,6 +27,7 @@ export { setUser, withScope, getClient, + getCurrentScope, } from './exports'; export { getCurrentHub, @@ -42,6 +44,7 @@ export { makeSession, closeSession, updateSession } from './session'; export { SessionFlusher } from './sessionflusher'; export { Scope } from './scope'; export { + notifyEventProcessors, // eslint-disable-next-line deprecation/deprecation addGlobalEventProcessor, } from './eventProcessors'; @@ -53,8 +56,14 @@ export { createTransport } from './transports/base'; export { makeOfflineTransport } from './transports/offline'; export { makeMultiplexedTransport } from './transports/multiplexed'; export { SDK_VERSION } from './version'; -export { getIntegrationsToSetup, addIntegration } from './integration'; +export { + getIntegrationsToSetup, + addIntegration, + // eslint-disable-next-line deprecation/deprecation + convertIntegrationFnToClass, +} from './integration'; export { FunctionToString, InboundFilters, LinkedErrors } from './integrations'; +export { applyScopeDataToEvent } from './utils/applyScopeDataToEvent'; export { prepareEvent } from './utils/prepareEvent'; export { createCheckInEnvelope } from './checkin'; export { hasTracingEnabled } from './utils/hasTracingEnabled'; @@ -63,5 +72,6 @@ export { DEFAULT_ENVIRONMENT } from './constants'; export { ModuleMetadata } from './integrations/metadata'; export { RequestData } from './integrations/requestdata'; import * as Integrations from './integrations'; +export { metrics } from './metrics/exports'; export { Integrations }; diff --git a/packages/core/src/integration.ts b/packages/core/src/integration.ts index 7be22a316e53..b7782fcfa65c 100644 --- a/packages/core/src/integration.ts +++ b/packages/core/src/integration.ts @@ -1,4 +1,4 @@ -import type { Client, Event, EventHint, Integration, Options } from '@sentry/types'; +import type { Client, Event, EventHint, Integration, IntegrationClass, IntegrationFn, Options } from '@sentry/types'; import { arrayify, logger } from '@sentry/utils'; import { DEBUG_BUILD } from './debug-build'; @@ -46,7 +46,7 @@ function filterDuplicates(integrations: Integration[]): Integration[] { } /** Gets integrations to install */ -export function getIntegrationsToSetup(options: Options): Integration[] { +export function getIntegrationsToSetup(options: Pick): Integration[] { const defaultIntegrations = options.defaultIntegrations || []; const userIntegrations = options.integrations; @@ -155,3 +155,26 @@ function findIndex(arr: T[], callback: (item: T) => boolean): number { return -1; } + +/** + * Convert a new integration function to the legacy class syntax. + * In v8, we can remove this and instead export the integration functions directly. + * + * @deprecated This will be removed in v8! + */ +export function convertIntegrationFnToClass( + name: string, + fn: Fn, +): IntegrationClass { + return Object.assign( + // eslint-disable-next-line @typescript-eslint/no-explicit-any + function ConvertedIntegration(...rest: any[]) { + return { + // eslint-disable-next-line @typescript-eslint/no-empty-function + setupOnce: () => {}, + ...fn(...rest), + }; + }, + { id: name }, + ) as unknown as IntegrationClass; +} diff --git a/packages/core/src/integrations/inboundfilters.ts b/packages/core/src/integrations/inboundfilters.ts index 9d348a4b4d23..57c0387b25e4 100644 --- a/packages/core/src/integrations/inboundfilters.ts +++ b/packages/core/src/integrations/inboundfilters.ts @@ -1,7 +1,8 @@ -import type { Client, Event, EventHint, Integration, StackFrame } from '@sentry/types'; +import type { Event, IntegrationFn, StackFrame } from '@sentry/types'; import { getEventDescription, logger, stringMatchesSomePattern } from '@sentry/utils'; import { DEBUG_BUILD } from '../debug-build'; +import { convertIntegrationFnToClass } from '../integration'; // "Script error." is hard coded into browsers for errors that it can't read. // this is the result of a script being pulled in from an external domain and CORS. @@ -28,42 +29,23 @@ export interface InboundFiltersOptions { disableTransactionDefaults: boolean; } -/** Inbound filters configurable by the user */ -export class InboundFilters implements Integration { - /** - * @inheritDoc - */ - public static id: string = 'InboundFilters'; - - /** - * @inheritDoc - */ - public name: string; - - private readonly _options: Partial; - - public constructor(options: Partial = {}) { - this.name = InboundFilters.id; - this._options = options; - } - - /** - * @inheritDoc - */ - public setupOnce(_addGlobalEventProcessor: unknown, _getCurrentHub: unknown): void { - // noop - } +const INTEGRATION_NAME = 'InboundFilters'; +const inboundFiltersIntegration: IntegrationFn = (options: Partial) => { + return { + name: INTEGRATION_NAME, + processEvent(event, _hint, client) { + const clientOptions = client.getOptions(); + const mergedOptions = _mergeOptions(options, clientOptions); + return _shouldDropEvent(event, mergedOptions) ? null : event; + }, + }; +}; - /** @inheritDoc */ - public processEvent(event: Event, _eventHint: EventHint, client: Client): Event | null { - const clientOptions = client.getOptions(); - const options = _mergeOptions(this._options, clientOptions); - return _shouldDropEvent(event, options) ? null : event; - } -} +/** Inbound filters configurable by the user */ +// eslint-disable-next-line deprecation/deprecation +export const InboundFilters = convertIntegrationFnToClass(INTEGRATION_NAME, inboundFiltersIntegration); -/** JSDoc */ -export function _mergeOptions( +function _mergeOptions( internalOptions: Partial = {}, clientOptions: Partial = {}, ): Partial { @@ -84,8 +66,7 @@ export function _mergeOptions( }; } -/** JSDoc */ -export function _shouldDropEvent(event: Event, options: Partial): boolean { +function _shouldDropEvent(event: Event, options: Partial): boolean { if (options.ignoreInternal && _isSentryError(event)) { DEBUG_BUILD && logger.warn(`Event dropped due to being internal Sentry Error.\nEvent: ${getEventDescription(event)}`); diff --git a/packages/core/src/integrations/metadata.ts b/packages/core/src/integrations/metadata.ts index caa9ad972e7d..1803640ea4dd 100644 --- a/packages/core/src/integrations/metadata.ts +++ b/packages/core/src/integrations/metadata.ts @@ -1,4 +1,4 @@ -import type { EventItem, EventProcessor, Hub, Integration } from '@sentry/types'; +import type { Client, Event, EventItem, EventProcessor, Hub, Integration } from '@sentry/types'; import { forEachEnvelopeItem } from '@sentry/utils'; import { addMetadataToStackFrames, stripMetadataFromStackFrames } from '../metadata'; @@ -30,10 +30,13 @@ export class ModuleMetadata implements Integration { /** * @inheritDoc */ - public setupOnce(addGlobalEventProcessor: (processor: EventProcessor) => void, getCurrentHub: () => Hub): void { - const client = getCurrentHub().getClient(); + public setupOnce(_addGlobalEventProcessor: (processor: EventProcessor) => void, _getCurrentHub: () => Hub): void { + // noop + } - if (!client || typeof client.on !== 'function') { + /** @inheritDoc */ + public setup(client: Client): void { + if (typeof client.on !== 'function') { return; } @@ -50,12 +53,12 @@ export class ModuleMetadata implements Integration { } }); }); + } + /** @inheritDoc */ + public processEvent(event: Event, _hint: unknown, client: Client): Event { const stackParser = client.getOptions().stackParser; - - addGlobalEventProcessor(event => { - addMetadataToStackFrames(stackParser, event); - return event; - }); + addMetadataToStackFrames(stackParser, event); + return event; } } diff --git a/packages/core/src/integrations/requestdata.ts b/packages/core/src/integrations/requestdata.ts index 4481501d8b8c..6aded915d854 100644 --- a/packages/core/src/integrations/requestdata.ts +++ b/packages/core/src/integrations/requestdata.ts @@ -1,4 +1,4 @@ -import type { Event, EventProcessor, Hub, Integration, PolymorphicRequest, Transaction } from '@sentry/types'; +import type { Client, Event, EventProcessor, Hub, Integration, PolymorphicRequest, Transaction } from '@sentry/types'; import type { AddRequestDataToEventOptions, TransactionNamingScheme } from '@sentry/utils'; import { addRequestDataToEvent, extractPathForTransaction } from '@sentry/utils'; @@ -95,65 +95,66 @@ export class RequestData implements Integration { /** * @inheritDoc */ - public setupOnce(addGlobalEventProcessor: (eventProcessor: EventProcessor) => void, getCurrentHub: () => Hub): void { + public setupOnce( + _addGlobalEventProcessor: (eventProcessor: EventProcessor) => void, + _getCurrentHub: () => Hub, + ): void { + // noop + } + + /** @inheritdoc */ + public processEvent(event: Event, _hint: unknown, client: Client): Event { // Note: In the long run, most of the logic here should probably move into the request data utility functions. For // the moment it lives here, though, until https://github.com/getsentry/sentry-javascript/issues/5718 is addressed. // (TL;DR: Those functions touch many parts of the repo in many different ways, and need to be clened up. Once // that's happened, it will be easier to add this logic in without worrying about unexpected side effects.) const { transactionNamingScheme } = this._options; - addGlobalEventProcessor(event => { - const hub = getCurrentHub(); - const self = hub.getIntegration(RequestData); - - const { sdkProcessingMetadata = {} } = event; - const req = sdkProcessingMetadata.request; + const { sdkProcessingMetadata = {} } = event; + const req = sdkProcessingMetadata.request; - // If the globally installed instance of this integration isn't associated with the current hub, `self` will be - // undefined - if (!self || !req) { - return event; - } + if (!req) { + return event; + } - // The Express request handler takes a similar `include` option to that which can be passed to this integration. - // If passed there, we store it in `sdkProcessingMetadata`. TODO(v8): Force express and GCP people to use this - // integration, so that all of this passing and conversion isn't necessary - const addRequestDataOptions = - sdkProcessingMetadata.requestDataOptionsFromExpressHandler || - sdkProcessingMetadata.requestDataOptionsFromGCPWrapper || - convertReqDataIntegrationOptsToAddReqDataOpts(this._options); + // The Express request handler takes a similar `include` option to that which can be passed to this integration. + // If passed there, we store it in `sdkProcessingMetadata`. TODO(v8): Force express and GCP people to use this + // integration, so that all of this passing and conversion isn't necessary + const addRequestDataOptions = + sdkProcessingMetadata.requestDataOptionsFromExpressHandler || + sdkProcessingMetadata.requestDataOptionsFromGCPWrapper || + convertReqDataIntegrationOptsToAddReqDataOpts(this._options); - const processedEvent = this._addRequestData(event, req, addRequestDataOptions); + const processedEvent = this._addRequestData(event, req, addRequestDataOptions); - // Transaction events already have the right `transaction` value - if (event.type === 'transaction' || transactionNamingScheme === 'handler') { - return processedEvent; - } + // Transaction events already have the right `transaction` value + if (event.type === 'transaction' || transactionNamingScheme === 'handler') { + return processedEvent; + } - // In all other cases, use the request's associated transaction (if any) to overwrite the event's `transaction` - // value with a high-quality one - const reqWithTransaction = req as { _sentryTransaction?: Transaction }; - const transaction = reqWithTransaction._sentryTransaction; - if (transaction) { - // TODO (v8): Remove the nextjs check and just base it on `transactionNamingScheme` for all SDKs. (We have to - // keep it the way it is for the moment, because changing the names of transactions in Sentry has the potential - // to break things like alert rules.) - const shouldIncludeMethodInTransactionName = - getSDKName(hub) === 'sentry.javascript.nextjs' - ? transaction.name.startsWith('/api') - : transactionNamingScheme !== 'path'; - - const [transactionValue] = extractPathForTransaction(req, { - path: true, - method: shouldIncludeMethodInTransactionName, - customRoute: transaction.name, - }); - - processedEvent.transaction = transactionValue; - } + // In all other cases, use the request's associated transaction (if any) to overwrite the event's `transaction` + // value with a high-quality one + const reqWithTransaction = req as { _sentryTransaction?: Transaction }; + const transaction = reqWithTransaction._sentryTransaction; + if (transaction) { + // TODO (v8): Remove the nextjs check and just base it on `transactionNamingScheme` for all SDKs. (We have to + // keep it the way it is for the moment, because changing the names of transactions in Sentry has the potential + // to break things like alert rules.) + const shouldIncludeMethodInTransactionName = + getSDKName(client) === 'sentry.javascript.nextjs' + ? transaction.name.startsWith('/api') + : transactionNamingScheme !== 'path'; + + const [transactionValue] = extractPathForTransaction(req, { + path: true, + method: shouldIncludeMethodInTransactionName, + customRoute: transaction.name, + }); + + processedEvent.transaction = transactionValue; + } - return processedEvent; - }); + return processedEvent; } } @@ -199,12 +200,12 @@ function convertReqDataIntegrationOptsToAddReqDataOpts( }; } -function getSDKName(hub: Hub): string | undefined { +function getSDKName(client: Client): string | undefined { try { // For a long chain like this, it's fewer bytes to combine a try-catch with assuming everything is there than to // write out a long chain of `a && a.b && a.b.c && ...` // eslint-disable-next-line @typescript-eslint/no-non-null-assertion - return hub.getClient()!.getOptions()!._metadata!.sdk!.name; + return client.getOptions()._metadata!.sdk!.name; } catch (err) { // In theory we should never get here return undefined; diff --git a/packages/core/src/metrics/constants.ts b/packages/core/src/metrics/constants.ts new file mode 100644 index 000000000000..f29ac323c2ee --- /dev/null +++ b/packages/core/src/metrics/constants.ts @@ -0,0 +1,30 @@ +export const COUNTER_METRIC_TYPE = 'c' as const; +export const GAUGE_METRIC_TYPE = 'g' as const; +export const SET_METRIC_TYPE = 's' as const; +export const DISTRIBUTION_METRIC_TYPE = 'd' as const; + +/** + * Normalization regex for metric names and metric tag names. + * + * This enforces that names and tag keys only contain alphanumeric characters, + * underscores, forward slashes, periods, and dashes. + * + * See: https://develop.sentry.dev/sdk/metrics/#normalization + */ +export const NAME_AND_TAG_KEY_NORMALIZATION_REGEX = /[^a-zA-Z0-9_/.-]+/g; + +/** + * Normalization regex for metric tag values. + * + * This enforces that values only contain words, digits, or the following + * special characters: _:/@.{}[\]$- + * + * See: https://develop.sentry.dev/sdk/metrics/#normalization + */ +export const TAG_VALUE_NORMALIZATION_REGEX = /[^\w\d_:/@.{}[\]$-]+/g; + +/** + * This does not match spec in https://develop.sentry.dev/sdk/metrics + * but was chosen to optimize for the most common case in browser environments. + */ +export const DEFAULT_FLUSH_INTERVAL = 5000; diff --git a/packages/core/src/metrics/envelope.ts b/packages/core/src/metrics/envelope.ts new file mode 100644 index 000000000000..c7c65674b736 --- /dev/null +++ b/packages/core/src/metrics/envelope.ts @@ -0,0 +1,40 @@ +import type { DsnComponents, MetricBucketItem, SdkMetadata, StatsdEnvelope, StatsdItem } from '@sentry/types'; +import { createEnvelope, dsnToString } from '@sentry/utils'; +import { serializeMetricBuckets } from './utils'; + +/** + * Create envelope from a metric aggregate. + */ +export function createMetricEnvelope( + metricBucketItems: Array, + dsn?: DsnComponents, + metadata?: SdkMetadata, + tunnel?: string, +): StatsdEnvelope { + const headers: StatsdEnvelope[0] = { + sent_at: new Date().toISOString(), + }; + + if (metadata && metadata.sdk) { + headers.sdk = { + name: metadata.sdk.name, + version: metadata.sdk.version, + }; + } + + if (!!tunnel && dsn) { + headers.dsn = dsnToString(dsn); + } + + const item = createMetricEnvelopeItem(metricBucketItems); + return createEnvelope(headers, [item]); +} + +function createMetricEnvelopeItem(metricBucketItems: Array): StatsdItem { + const payload = serializeMetricBuckets(metricBucketItems); + const metricHeaders: StatsdItem[0] = { + type: 'statsd', + length: payload.length, + }; + return [metricHeaders, payload]; +} diff --git a/packages/core/src/metrics/exports.ts b/packages/core/src/metrics/exports.ts new file mode 100644 index 000000000000..22a5e83ffb3d --- /dev/null +++ b/packages/core/src/metrics/exports.ts @@ -0,0 +1,91 @@ +import type { ClientOptions, MeasurementUnit, Primitive } from '@sentry/types'; +import { logger } from '@sentry/utils'; +import type { BaseClient } from '../baseclient'; +import { DEBUG_BUILD } from '../debug-build'; +import { getClient, getCurrentScope } from '../exports'; +import { COUNTER_METRIC_TYPE, DISTRIBUTION_METRIC_TYPE, GAUGE_METRIC_TYPE, SET_METRIC_TYPE } from './constants'; +import { MetricsAggregator } from './integration'; +import type { MetricType } from './types'; + +interface MetricData { + unit?: MeasurementUnit; + tags?: Record; + timestamp?: number; +} + +function addToMetricsAggregator( + metricType: MetricType, + name: string, + value: number | string, + data: MetricData = {}, +): void { + const client = getClient>(); + const scope = getCurrentScope(); + if (client) { + if (!client.metricsAggregator) { + DEBUG_BUILD && + logger.warn('No metrics aggregator enabled. Please add the MetricsAggregator integration to use metrics APIs'); + return; + } + const { unit, tags, timestamp } = data; + const { release, environment } = client.getOptions(); + const transaction = scope.getTransaction(); + const metricTags: Record = {}; + if (release) { + metricTags.release = release; + } + if (environment) { + metricTags.environment = environment; + } + if (transaction) { + metricTags.transaction = transaction.name; + } + + DEBUG_BUILD && logger.log(`Adding value of ${value} to ${metricType} metric ${name}`); + client.metricsAggregator.add(metricType, name, value, unit, { ...metricTags, ...tags }, timestamp); + } +} + +/** + * Adds a value to a counter metric + * + * @experimental This API is experimental and might having breaking changes in the future. + */ +export function increment(name: string, value: number = 1, data?: MetricData): void { + addToMetricsAggregator(COUNTER_METRIC_TYPE, name, value, data); +} + +/** + * Adds a value to a distribution metric + * + * @experimental This API is experimental and might having breaking changes in the future. + */ +export function distribution(name: string, value: number, data?: MetricData): void { + addToMetricsAggregator(DISTRIBUTION_METRIC_TYPE, name, value, data); +} + +/** + * Adds a value to a set metric. Value must be a string or integer. + * + * @experimental This API is experimental and might having breaking changes in the future. + */ +export function set(name: string, value: number | string, data?: MetricData): void { + addToMetricsAggregator(SET_METRIC_TYPE, name, value, data); +} + +/** + * Adds a value to a gauge metric + * + * @experimental This API is experimental and might having breaking changes in the future. + */ +export function gauge(name: string, value: number, data?: MetricData): void { + addToMetricsAggregator(GAUGE_METRIC_TYPE, name, value, data); +} + +export const metrics = { + increment, + distribution, + set, + gauge, + MetricsAggregator, +}; diff --git a/packages/core/src/metrics/index.ts b/packages/core/src/metrics/index.ts deleted file mode 100644 index 3cfeae37e03f..000000000000 --- a/packages/core/src/metrics/index.ts +++ /dev/null @@ -1,43 +0,0 @@ -import type { DsnComponents, DynamicSamplingContext, SdkMetadata, StatsdEnvelope, StatsdItem } from '@sentry/types'; -import { createEnvelope, dropUndefinedKeys, dsnToString } from '@sentry/utils'; - -/** - * Create envelope from a metric aggregate. - */ -export function createMetricEnvelope( - // TODO(abhi): Add type for this - metricAggregate: string, - dynamicSamplingContext?: Partial, - metadata?: SdkMetadata, - tunnel?: string, - dsn?: DsnComponents, -): StatsdEnvelope { - const headers: StatsdEnvelope[0] = { - sent_at: new Date().toISOString(), - }; - - if (metadata && metadata.sdk) { - headers.sdk = { - name: metadata.sdk.name, - version: metadata.sdk.version, - }; - } - - if (!!tunnel && !!dsn) { - headers.dsn = dsnToString(dsn); - } - - if (dynamicSamplingContext) { - headers.trace = dropUndefinedKeys(dynamicSamplingContext) as DynamicSamplingContext; - } - - const item = createMetricEnvelopeItem(metricAggregate); - return createEnvelope(headers, [item]); -} - -function createMetricEnvelopeItem(metricAggregate: string): StatsdItem { - const metricHeaders: StatsdItem[0] = { - type: 'statsd', - }; - return [metricHeaders, metricAggregate]; -} diff --git a/packages/core/src/metrics/instance.ts b/packages/core/src/metrics/instance.ts new file mode 100644 index 000000000000..f071006c96ca --- /dev/null +++ b/packages/core/src/metrics/instance.ts @@ -0,0 +1,110 @@ +import type { MetricInstance } from '@sentry/types'; +import { COUNTER_METRIC_TYPE, DISTRIBUTION_METRIC_TYPE, GAUGE_METRIC_TYPE, SET_METRIC_TYPE } from './constants'; +import { simpleHash } from './utils'; + +/** + * A metric instance representing a counter. + */ +export class CounterMetric implements MetricInstance { + public constructor(private _value: number) {} + + /** @inheritdoc */ + public add(value: number): void { + this._value += value; + } + + /** @inheritdoc */ + public toString(): string { + return `${this._value}`; + } +} + +/** + * A metric instance representing a gauge. + */ +export class GaugeMetric implements MetricInstance { + private _last: number; + private _min: number; + private _max: number; + private _sum: number; + private _count: number; + + public constructor(value: number) { + this._last = value; + this._min = value; + this._max = value; + this._sum = value; + this._count = 1; + } + + /** @inheritdoc */ + public add(value: number): void { + this._last = value; + if (value < this._min) { + this._min = value; + } + if (value > this._max) { + this._max = value; + } + this._sum += value; + this._count++; + } + + /** @inheritdoc */ + public toString(): string { + return `${this._last}:${this._min}:${this._max}:${this._sum}:${this._count}`; + } +} + +/** + * A metric instance representing a distribution. + */ +export class DistributionMetric implements MetricInstance { + private _value: number[]; + + public constructor(first: number) { + this._value = [first]; + } + + /** @inheritdoc */ + public add(value: number): void { + this._value.push(value); + } + + /** @inheritdoc */ + public toString(): string { + return this._value.join(':'); + } +} + +/** + * A metric instance representing a set. + */ +export class SetMetric implements MetricInstance { + private _value: Set; + + public constructor(public first: number | string) { + this._value = new Set([first]); + } + + /** @inheritdoc */ + public add(value: number | string): void { + this._value.add(value); + } + + /** @inheritdoc */ + public toString(): string { + return `${Array.from(this._value) + .map(val => (typeof val === 'string' ? simpleHash(val) : val)) + .join(':')}`; + } +} + +export type Metric = CounterMetric | GaugeMetric | DistributionMetric | SetMetric; + +export const METRIC_MAP = { + [COUNTER_METRIC_TYPE]: CounterMetric, + [GAUGE_METRIC_TYPE]: GaugeMetric, + [DISTRIBUTION_METRIC_TYPE]: DistributionMetric, + [SET_METRIC_TYPE]: SetMetric, +}; diff --git a/packages/core/src/metrics/integration.ts b/packages/core/src/metrics/integration.ts new file mode 100644 index 000000000000..9ce7f836ca8c --- /dev/null +++ b/packages/core/src/metrics/integration.ts @@ -0,0 +1,38 @@ +import type { ClientOptions, Integration } from '@sentry/types'; +import type { BaseClient } from '../baseclient'; +import { SimpleMetricsAggregator } from './simpleaggregator'; + +/** + * Enables Sentry metrics monitoring. + * + * @experimental This API is experimental and might having breaking changes in the future. + */ +export class MetricsAggregator implements Integration { + /** + * @inheritDoc + */ + public static id: string = 'MetricsAggregator'; + + /** + * @inheritDoc + */ + public name: string; + + public constructor() { + this.name = MetricsAggregator.id; + } + + /** + * @inheritDoc + */ + public setupOnce(): void { + // Do nothing + } + + /** + * @inheritDoc + */ + public setup(client: BaseClient): void { + client.metricsAggregator = new SimpleMetricsAggregator(client); + } +} diff --git a/packages/core/src/metrics/simpleaggregator.ts b/packages/core/src/metrics/simpleaggregator.ts new file mode 100644 index 000000000000..a628a3b5a406 --- /dev/null +++ b/packages/core/src/metrics/simpleaggregator.ts @@ -0,0 +1,91 @@ +import type { Client, ClientOptions, MeasurementUnit, MetricsAggregator, Primitive } from '@sentry/types'; +import { timestampInSeconds } from '@sentry/utils'; +import { + DEFAULT_FLUSH_INTERVAL, + NAME_AND_TAG_KEY_NORMALIZATION_REGEX, + TAG_VALUE_NORMALIZATION_REGEX, +} from './constants'; +import { METRIC_MAP } from './instance'; +import type { MetricType, SimpleMetricBucket } from './types'; +import { getBucketKey } from './utils'; + +/** + * A simple metrics aggregator that aggregates metrics in memory and flushes them periodically. + * Default flush interval is 5 seconds. + * + * @experimental This API is experimental and might change in the future. + */ +export class SimpleMetricsAggregator implements MetricsAggregator { + private _buckets: SimpleMetricBucket; + private readonly _interval: ReturnType; + + public constructor(private readonly _client: Client) { + this._buckets = new Map(); + this._interval = setInterval(() => this.flush(), DEFAULT_FLUSH_INTERVAL); + } + + /** + * @inheritDoc + */ + public add( + metricType: MetricType, + unsanitizedName: string, + value: number | string, + unit: MeasurementUnit = 'none', + unsanitizedTags: Record = {}, + maybeFloatTimestamp = timestampInSeconds(), + ): void { + const timestamp = Math.floor(maybeFloatTimestamp); + const name = unsanitizedName.replace(NAME_AND_TAG_KEY_NORMALIZATION_REGEX, '_'); + const tags = sanitizeTags(unsanitizedTags); + + const bucketKey = getBucketKey(metricType, name, unit, tags); + const bucketItem = this._buckets.get(bucketKey); + if (bucketItem) { + const [bucketMetric, bucketTimestamp] = bucketItem; + bucketMetric.add(value); + // TODO(abhi): Do we need this check? + if (bucketTimestamp < timestamp) { + bucketItem[1] = timestamp; + } + } else { + // @ts-expect-error we don't need to narrow down the type of value here, saves bundle size. + const newMetric = new METRIC_MAP[metricType](value); + this._buckets.set(bucketKey, [newMetric, timestamp, metricType, name, unit, tags]); + } + } + + /** + * @inheritDoc + */ + public flush(): void { + // short circuit if buckets are empty. + if (this._buckets.size === 0) { + return; + } + if (this._client.captureAggregateMetrics) { + const metricBuckets = Array.from(this._buckets).map(([, bucketItem]) => bucketItem); + this._client.captureAggregateMetrics(metricBuckets); + } + this._buckets.clear(); + } + + /** + * @inheritDoc + */ + public close(): void { + clearInterval(this._interval); + this.flush(); + } +} + +function sanitizeTags(unsanitizedTags: Record): Record { + const tags: Record = {}; + for (const key in unsanitizedTags) { + if (Object.prototype.hasOwnProperty.call(unsanitizedTags, key)) { + const sanitizedKey = key.replace(NAME_AND_TAG_KEY_NORMALIZATION_REGEX, '_'); + tags[sanitizedKey] = String(unsanitizedTags[key]).replace(TAG_VALUE_NORMALIZATION_REGEX, '_'); + } + } + return tags; +} diff --git a/packages/core/src/metrics/types.ts b/packages/core/src/metrics/types.ts new file mode 100644 index 000000000000..de6032f811b8 --- /dev/null +++ b/packages/core/src/metrics/types.ts @@ -0,0 +1,10 @@ +import type { MetricBucketItem } from '@sentry/types'; +import type { COUNTER_METRIC_TYPE, DISTRIBUTION_METRIC_TYPE, GAUGE_METRIC_TYPE, SET_METRIC_TYPE } from './constants'; + +export type MetricType = + | typeof COUNTER_METRIC_TYPE + | typeof GAUGE_METRIC_TYPE + | typeof SET_METRIC_TYPE + | typeof DISTRIBUTION_METRIC_TYPE; + +export type SimpleMetricBucket = Map; diff --git a/packages/core/src/metrics/utils.ts b/packages/core/src/metrics/utils.ts new file mode 100644 index 000000000000..27c49d144523 --- /dev/null +++ b/packages/core/src/metrics/utils.ts @@ -0,0 +1,57 @@ +import type { MeasurementUnit, MetricBucketItem } from '@sentry/types'; +import { dropUndefinedKeys } from '@sentry/utils'; +import type { MetricType, SimpleMetricBucket } from './types'; + +/** + * Generate bucket key from metric properties. + */ +export function getBucketKey( + metricType: MetricType, + name: string, + unit: MeasurementUnit, + tags: Record, +): string { + const stringifiedTags = Object.entries(dropUndefinedKeys(tags)).sort((a, b) => a[0].localeCompare(b[0])); + return `${metricType}${name}${unit}${stringifiedTags}`; +} + +/* eslint-disable no-bitwise */ +/** + * Simple hash function for strings. + */ +export function simpleHash(s: string): number { + let rv = 0; + for (let i = 0; i < s.length; i++) { + const c = s.charCodeAt(i); + rv = (rv << 5) - rv + c; + rv &= rv; + } + return rv >>> 0; +} +/* eslint-enable no-bitwise */ + +/** + * Serialize metrics buckets into a string based on statsd format. + * + * Example of format: + * metric.name@second:1:1.2|d|#a:value,b:anothervalue|T12345677 + * Segments: + * name: metric.name + * unit: second + * value: [1, 1.2] + * type of metric: d (distribution) + * tags: { a: value, b: anothervalue } + * timestamp: 12345677 + */ +export function serializeMetricBuckets(metricBucketItems: Array): string { + let out = ''; + for (const [metric, timestamp, metricType, name, unit, tags] of metricBucketItems) { + const maybeTags = Object.keys(tags).length + ? `|#${Object.entries(tags) + .map(([key, value]) => `${key}:${String(value)}`) + .join(',')}` + : ''; + out += `${name}@${unit}:${metric}|${metricType}${maybeTags}|T${timestamp}\n`; + } + return out; +} diff --git a/packages/core/src/scope.ts b/packages/core/src/scope.ts index 266087dd6090..599b5c0f8d57 100644 --- a/packages/core/src/scope.ts +++ b/packages/core/src/scope.ts @@ -15,6 +15,7 @@ import type { RequestSession, Scope as ScopeInterface, ScopeContext, + ScopeData, Session, Severity, SeverityLevel, @@ -26,6 +27,7 @@ import { arrayify, dateTimestampInSeconds, isPlainObject, uuid4 } from '@sentry/ import { getGlobalEventProcessors, notifyEventProcessors } from './eventProcessors'; import { updateSession } from './session'; +import { applyScopeDataToEvent } from './utils/applyScopeDataToEvent'; /** * Default value for maximum number of breadcrumbs added to an event. @@ -110,27 +112,33 @@ export class Scope implements ScopeInterface { /** * Inherit values from the parent scope. - * @param scope to clone. + * @deprecated Use `scope.clone()` and `new Scope()` instead. */ public static clone(scope?: Scope): Scope { + return scope ? scope.clone() : new Scope(); + } + + /** + * Clone this scope instance. + */ + public clone(): Scope { const newScope = new Scope(); - if (scope) { - newScope._breadcrumbs = [...scope._breadcrumbs]; - newScope._tags = { ...scope._tags }; - newScope._extra = { ...scope._extra }; - newScope._contexts = { ...scope._contexts }; - newScope._user = scope._user; - newScope._level = scope._level; - newScope._span = scope._span; - newScope._session = scope._session; - newScope._transactionName = scope._transactionName; - newScope._fingerprint = scope._fingerprint; - newScope._eventProcessors = [...scope._eventProcessors]; - newScope._requestSession = scope._requestSession; - newScope._attachments = [...scope._attachments]; - newScope._sdkProcessingMetadata = { ...scope._sdkProcessingMetadata }; - newScope._propagationContext = { ...scope._propagationContext }; - } + newScope._breadcrumbs = [...this._breadcrumbs]; + newScope._tags = { ...this._tags }; + newScope._extra = { ...this._extra }; + newScope._contexts = { ...this._contexts }; + newScope._user = this._user; + newScope._level = this._level; + newScope._span = this._span; + newScope._session = this._session; + newScope._transactionName = this._transactionName; + newScope._fingerprint = this._fingerprint; + newScope._eventProcessors = [...this._eventProcessors]; + newScope._requestSession = this._requestSession; + newScope._attachments = [...this._attachments]; + newScope._sdkProcessingMetadata = { ...this._sdkProcessingMetadata }; + newScope._propagationContext = { ...this._propagationContext }; + return newScope; } @@ -460,78 +468,65 @@ export class Scope implements ScopeInterface { return this; } + /** @inheritDoc */ + public getScopeData(): ScopeData { + const { + _breadcrumbs, + _attachments, + _contexts, + _tags, + _extra, + _user, + _level, + _fingerprint, + _eventProcessors, + _propagationContext, + _sdkProcessingMetadata, + _transactionName, + _span, + } = this; + + return { + breadcrumbs: _breadcrumbs, + attachments: _attachments, + contexts: _contexts, + tags: _tags, + extra: _extra, + user: _user, + level: _level, + fingerprint: _fingerprint || [], + eventProcessors: _eventProcessors, + propagationContext: _propagationContext, + sdkProcessingMetadata: _sdkProcessingMetadata, + transactionName: _transactionName, + span: _span, + }; + } + /** * Applies data from the scope to the event and runs all event processors on it. * * @param event Event * @param hint Object containing additional information about the original exception, for use by the event processors. * @hidden + * @deprecated Use `applyScopeDataToEvent()` directly */ public applyToEvent( event: Event, hint: EventHint = {}, - additionalEventProcessors?: EventProcessor[], + additionalEventProcessors: EventProcessor[] = [], ): PromiseLike { - if (this._extra && Object.keys(this._extra).length) { - event.extra = { ...this._extra, ...event.extra }; - } - if (this._tags && Object.keys(this._tags).length) { - event.tags = { ...this._tags, ...event.tags }; - } - if (this._user && Object.keys(this._user).length) { - event.user = { ...this._user, ...event.user }; - } - if (this._contexts && Object.keys(this._contexts).length) { - event.contexts = { ...this._contexts, ...event.contexts }; - } - if (this._level) { - event.level = this._level; - } - if (this._transactionName) { - event.transaction = this._transactionName; - } - - // We want to set the trace context for normal events only if there isn't already - // a trace context on the event. There is a product feature in place where we link - // errors with transaction and it relies on that. - if (this._span) { - event.contexts = { trace: this._span.getTraceContext(), ...event.contexts }; - const transaction = this._span.transaction; - if (transaction) { - event.sdkProcessingMetadata = { - dynamicSamplingContext: transaction.getDynamicSamplingContext(), - ...event.sdkProcessingMetadata, - }; - const transactionName = transaction.name; - if (transactionName) { - event.tags = { transaction: transactionName, ...event.tags }; - } - } - } - - this._applyFingerprint(event); - - const scopeBreadcrumbs = this._getBreadcrumbs(); - const breadcrumbs = [...(event.breadcrumbs || []), ...scopeBreadcrumbs]; - event.breadcrumbs = breadcrumbs.length > 0 ? breadcrumbs : undefined; - - event.sdkProcessingMetadata = { - ...event.sdkProcessingMetadata, - ...this._sdkProcessingMetadata, - propagationContext: this._propagationContext, - }; + applyScopeDataToEvent(event, this.getScopeData()); // TODO (v8): Update this order to be: Global > Client > Scope - return notifyEventProcessors( - [ - ...(additionalEventProcessors || []), - // eslint-disable-next-line deprecation/deprecation - ...getGlobalEventProcessors(), - ...this._eventProcessors, - ], - event, - hint, - ); + const eventProcessors: EventProcessor[] = [ + ...additionalEventProcessors, + // eslint-disable-next-line deprecation/deprecation + ...getGlobalEventProcessors(), + ...this._eventProcessors, + ]; + + return notifyEventProcessors(eventProcessors, event, hint); } /** @@ -558,13 +553,6 @@ export class Scope implements ScopeInterface { return this._propagationContext; } - /** - * Get the breadcrumbs for this scope. - */ - protected _getBreadcrumbs(): Breadcrumb[] { - return this._breadcrumbs; - } - /** * This will be called on every set call. */ @@ -580,25 +568,6 @@ export class Scope implements ScopeInterface { this._notifyingListeners = false; } } - - /** - * Applies fingerprint from the scope to the event if there's one, - * uses message if there's one instead or get rid of empty fingerprint - */ - private _applyFingerprint(event: Event): void { - // Make sure it's an array first and we actually have something in place - event.fingerprint = event.fingerprint ? arrayify(event.fingerprint) : []; - - // If we have something on the scope, then merge it with event - if (this._fingerprint) { - event.fingerprint = event.fingerprint.concat(this._fingerprint); - } - - // If we have no data at all, remove empty array default - if (event.fingerprint && !event.fingerprint.length) { - delete event.fingerprint; - } - } } function generatePropagationContext(): PropagationContext { diff --git a/packages/core/src/server-runtime-client.ts b/packages/core/src/server-runtime-client.ts index 4165aec8fc46..719e2b81f086 100644 --- a/packages/core/src/server-runtime-client.ts +++ b/packages/core/src/server-runtime-client.ts @@ -16,7 +16,7 @@ import { eventFromMessage, eventFromUnknownInput, logger, resolvedSyncPromise, u import { BaseClient } from './baseclient'; import { createCheckInEnvelope } from './checkin'; import { DEBUG_BUILD } from './debug-build'; -import { getCurrentHub } from './hub'; +import { getClient } from './exports'; import type { Scope } from './scope'; import { SessionFlusher } from './sessionflusher'; import { addTracingExtensions, getDynamicSamplingContextFromClient } from './tracing'; @@ -50,7 +50,7 @@ export class ServerRuntimeClient< * @inheritDoc */ public eventFromException(exception: unknown, hint?: EventHint): PromiseLike { - return resolvedSyncPromise(eventFromUnknownInput(getCurrentHub, this._options.stackParser, exception, hint)); + return resolvedSyncPromise(eventFromUnknownInput(getClient(), this._options.stackParser, exception, hint)); } /** diff --git a/packages/core/src/sessionflusher.ts b/packages/core/src/sessionflusher.ts index 0b0bc8455480..dac81b82336d 100644 --- a/packages/core/src/sessionflusher.ts +++ b/packages/core/src/sessionflusher.ts @@ -6,8 +6,7 @@ import type { SessionFlusherLike, } from '@sentry/types'; import { dropUndefinedKeys } from '@sentry/utils'; - -import { getCurrentHub } from './hub'; +import { getCurrentScope } from './exports'; type ReleaseHealthAttributes = { environment?: string; @@ -75,7 +74,7 @@ export class SessionFlusher implements SessionFlusherLike { if (!this._isEnabled) { return; } - const scope = getCurrentHub().getScope(); + const scope = getCurrentScope(); const requestSession = scope.getRequestSession(); if (requestSession && requestSession.status) { diff --git a/packages/core/src/tracing/idletransaction.ts b/packages/core/src/tracing/idletransaction.ts index b49b1d15e9b1..75630de373f1 100644 --- a/packages/core/src/tracing/idletransaction.ts +++ b/packages/core/src/tracing/idletransaction.ts @@ -121,7 +121,7 @@ export class IdleTransaction extends Transaction { // We set the transaction here on the scope so error events pick up the trace // context and attach it to the error. DEBUG_BUILD && logger.log(`Setting idle transaction on scope. Span ID: ${this.spanId}`); - _idleHub.configureScope(scope => scope.setSpan(this)); + _idleHub.getScope().setSpan(this); } this._restartIdleTimeout(); diff --git a/packages/core/src/tracing/trace.ts b/packages/core/src/tracing/trace.ts index 667bedaaef6c..cc73fe009e3d 100644 --- a/packages/core/src/tracing/trace.ts +++ b/packages/core/src/tracing/trace.ts @@ -2,6 +2,7 @@ import type { TransactionContext } from '@sentry/types'; import { dropUndefinedKeys, isThenable, logger, tracingContextFromHeaders } from '@sentry/utils'; import { DEBUG_BUILD } from '../debug-build'; +import { getCurrentScope } from '../exports'; import type { Hub } from '../hub'; import { getCurrentHub } from '../hub'; import { hasTracingEnabled } from '../utils/hasTracingEnabled'; @@ -23,12 +24,14 @@ export function trace( context: TransactionContext, callback: (span?: Span) => T, // eslint-disable-next-line @typescript-eslint/no-empty-function - onError: (error: unknown) => void = () => {}, + onError: (error: unknown, span?: Span) => void = () => {}, + // eslint-disable-next-line @typescript-eslint/no-empty-function + afterFinish: () => void = () => {}, ): T { const ctx = normalizeContext(context); const hub = getCurrentHub(); - const scope = hub.getScope(); + const scope = getCurrentScope(); const parentSpan = scope.getSpan(); const activeSpan = createChildSpanOrTransaction(hub, parentSpan, ctx); @@ -37,7 +40,7 @@ export function trace( function finishAndSetSpan(): void { activeSpan && activeSpan.finish(); - hub.getScope().setSpan(parentSpan); + scope.setSpan(parentSpan); } let maybePromiseResult: T; @@ -45,8 +48,9 @@ export function trace( maybePromiseResult = callback(activeSpan); } catch (e) { activeSpan && activeSpan.setStatus('internal_error'); - onError(e); + onError(e, activeSpan); finishAndSetSpan(); + afterFinish(); throw e; } @@ -54,15 +58,18 @@ export function trace( Promise.resolve(maybePromiseResult).then( () => { finishAndSetSpan(); + afterFinish(); }, e => { activeSpan && activeSpan.setStatus('internal_error'); - onError(e); + onError(e, activeSpan); finishAndSetSpan(); + afterFinish(); }, ); } else { finishAndSetSpan(); + afterFinish(); } return maybePromiseResult; @@ -83,7 +90,7 @@ export function startSpan(context: TransactionContext, callback: (span: Span const ctx = normalizeContext(context); const hub = getCurrentHub(); - const scope = hub.getScope(); + const scope = getCurrentScope(); const parentSpan = scope.getSpan(); const activeSpan = createChildSpanOrTransaction(hub, parentSpan, ctx); @@ -91,7 +98,7 @@ export function startSpan(context: TransactionContext, callback: (span: Span function finishAndSetSpan(): void { activeSpan && activeSpan.finish(); - hub.getScope().setSpan(parentSpan); + scope.setSpan(parentSpan); } let maybePromiseResult: T; @@ -143,7 +150,7 @@ export function startSpanManual( const ctx = normalizeContext(context); const hub = getCurrentHub(); - const scope = hub.getScope(); + const scope = getCurrentScope(); const parentSpan = scope.getSpan(); const activeSpan = createChildSpanOrTransaction(hub, parentSpan, ctx); @@ -151,7 +158,7 @@ export function startSpanManual( function finishAndSetSpan(): void { activeSpan && activeSpan.finish(); - hub.getScope().setSpan(parentSpan); + scope.setSpan(parentSpan); } let maybePromiseResult: T; @@ -201,7 +208,7 @@ export function startInactiveSpan(context: TransactionContext): Span | undefined * Returns the currently active span. */ export function getActiveSpan(): Span | undefined { - return getCurrentHub().getScope().getSpan(); + return getCurrentScope().getSpan(); } export function continueTrace({ @@ -238,8 +245,7 @@ export function continueTrace( }, callback?: (transactionContext: Partial) => V, ): V | Partial { - const hub = getCurrentHub(); - const currentScope = hub.getScope(); + const currentScope = getCurrentScope(); const { traceparentData, dynamicSamplingContext, propagationContext } = tracingContextFromHeaders( sentryTrace, diff --git a/packages/core/src/utils/applyScopeDataToEvent.ts b/packages/core/src/utils/applyScopeDataToEvent.ts new file mode 100644 index 000000000000..cc63e7c26cb6 --- /dev/null +++ b/packages/core/src/utils/applyScopeDataToEvent.ts @@ -0,0 +1,97 @@ +import type { Breadcrumb, Event, PropagationContext, ScopeData, Span } from '@sentry/types'; +import { arrayify } from '@sentry/utils'; + +/** + * Applies data from the scope to the event and runs all event processors on it. + */ +export function applyScopeDataToEvent(event: Event, data: ScopeData): void { + const { fingerprint, span, breadcrumbs, sdkProcessingMetadata, propagationContext } = data; + + // Apply general data + applyDataToEvent(event, data); + + // We want to set the trace context for normal events only if there isn't already + // a trace context on the event. There is a product feature in place where we link + // errors with transaction and it relies on that. + if (span) { + applySpanToEvent(event, span); + } + + applyFingerprintToEvent(event, fingerprint); + applyBreadcrumbsToEvent(event, breadcrumbs); + applySdkMetadataToEvent(event, sdkProcessingMetadata, propagationContext); +} + +function applyDataToEvent(event: Event, data: ScopeData): void { + const { extra, tags, user, contexts, level, transactionName } = data; + + if (extra && Object.keys(extra).length) { + event.extra = { ...extra, ...event.extra }; + } + if (tags && Object.keys(tags).length) { + event.tags = { ...tags, ...event.tags }; + } + if (user && Object.keys(user).length) { + event.user = { ...user, ...event.user }; + } + if (contexts && Object.keys(contexts).length) { + event.contexts = { ...contexts, ...event.contexts }; + } + if (level) { + event.level = level; + } + if (transactionName) { + event.transaction = transactionName; + } +} + +function applyBreadcrumbsToEvent(event: Event, breadcrumbs: Breadcrumb[]): void { + const mergedBreadcrumbs = [...(event.breadcrumbs || []), ...breadcrumbs]; + event.breadcrumbs = mergedBreadcrumbs.length ? mergedBreadcrumbs : undefined; +} + +function applySdkMetadataToEvent( + event: Event, + sdkProcessingMetadata: ScopeData['sdkProcessingMetadata'], + propagationContext: PropagationContext, +): void { + event.sdkProcessingMetadata = { + ...event.sdkProcessingMetadata, + ...sdkProcessingMetadata, + propagationContext: propagationContext, + }; +} + +function applySpanToEvent(event: Event, span: Span): void { + event.contexts = { trace: span.getTraceContext(), ...event.contexts }; + const transaction = span.transaction; + if (transaction) { + event.sdkProcessingMetadata = { + dynamicSamplingContext: transaction.getDynamicSamplingContext(), + ...event.sdkProcessingMetadata, + }; + const transactionName = transaction.name; + if (transactionName) { + event.tags = { transaction: transactionName, ...event.tags }; + } + } +} + +/** + * Applies fingerprint from the scope to the event if there's one, + * uses message if there's one instead or get rid of empty fingerprint + */ +function applyFingerprintToEvent(event: Event, fingerprint: ScopeData['fingerprint'] | undefined): void { + // Make sure it's an array first and we actually have something in place + event.fingerprint = event.fingerprint ? arrayify(event.fingerprint) : []; + + // If we have something on the scope, then merge it with event + if (fingerprint) { + event.fingerprint = event.fingerprint.concat(fingerprint); + } + + // If we have no data at all, remove empty array default + if (event.fingerprint && !event.fingerprint.length) { + delete event.fingerprint; + } +} diff --git a/packages/core/src/utils/isSentryRequestUrl.ts b/packages/core/src/utils/isSentryRequestUrl.ts index 0256e3cf7835..3a31f63cf46c 100644 --- a/packages/core/src/utils/isSentryRequestUrl.ts +++ b/packages/core/src/utils/isSentryRequestUrl.ts @@ -1,11 +1,13 @@ -import type { DsnComponents, Hub } from '@sentry/types'; +import type { Client, DsnComponents, Hub } from '@sentry/types'; /** * Checks whether given url points to Sentry server * @param url url to verify + * + * TODO(v8): Remove Hub fallback type */ -export function isSentryRequestUrl(url: string, hub: Hub): boolean { - const client = hub.getClient(); +export function isSentryRequestUrl(url: string, hubOrClient: Hub | Client | undefined): boolean { + const client = hubOrClient && isHub(hubOrClient) ? hubOrClient.getClient() : hubOrClient; const dsn = client && client.getDsn(); const tunnel = client && client.getOptions().tunnel; @@ -27,3 +29,7 @@ function checkDsn(url: string, dsn: DsnComponents | undefined): boolean { function removeTrailingSlash(str: string): string { return str[str.length - 1] === '/' ? str.slice(0, -1) : str; } + +function isHub(hubOrClient: Hub | Client | undefined): hubOrClient is Hub { + return (hubOrClient as Hub).getClient !== undefined; +} diff --git a/packages/core/src/utils/prepareEvent.ts b/packages/core/src/utils/prepareEvent.ts index 6e25350202b4..76307b4f45e6 100644 --- a/packages/core/src/utils/prepareEvent.ts +++ b/packages/core/src/utils/prepareEvent.ts @@ -9,19 +9,12 @@ import type { StackFrame, StackParser, } from '@sentry/types'; -import { - GLOBAL_OBJ, - addExceptionMechanism, - dateTimestampInSeconds, - normalize, - resolvedSyncPromise, - truncate, - uuid4, -} from '@sentry/utils'; +import { GLOBAL_OBJ, addExceptionMechanism, dateTimestampInSeconds, normalize, truncate, uuid4 } from '@sentry/utils'; import { DEFAULT_ENVIRONMENT } from '../constants'; import { getGlobalEventProcessors, notifyEventProcessors } from '../eventProcessors'; import { Scope } from '../scope'; +import { applyScopeDataToEvent } from './applyScopeDataToEvent'; /** * This type makes sure that we get either a CaptureContext, OR an EventHint. @@ -74,19 +67,19 @@ export function prepareEvent( // If we have scope given to us, use it as the base for further modifications. // This allows us to prevent unnecessary copying of data if `captureContext` is not provided. - let finalScope = scope; - if (hint.captureContext) { - finalScope = Scope.clone(finalScope).update(hint.captureContext); - } + const finalScope = getFinalScope(scope, hint.captureContext); if (hint.mechanism) { addExceptionMechanism(prepared, hint.mechanism); } - // We prepare the result here with a resolved Event. - let result = resolvedSyncPromise(prepared); - const clientEventProcessors = client && client.getEventProcessors ? client.getEventProcessors() : []; + // TODO (v8): Update this order to be: Global > Client > Scope + const eventProcessors = [ + ...clientEventProcessors, + // eslint-disable-next-line deprecation/deprecation + ...getGlobalEventProcessors(), + ]; // This should be the last thing called, since we want that // {@link Hub.addEventProcessor} gets the finished prepared event. @@ -105,22 +98,15 @@ export function prepareEvent( } } - // In case we have a hub we reassign it. - result = finalScope.applyToEvent(prepared, hint, clientEventProcessors); - } else { - // Apply client & global event processors even if there is no scope - // TODO (v8): Update the order to be Global > Client - result = notifyEventProcessors( - [ - ...clientEventProcessors, - // eslint-disable-next-line deprecation/deprecation - ...getGlobalEventProcessors(), - ], - prepared, - hint, - ); + const scopeData = finalScope.getScopeData(); + applyScopeDataToEvent(prepared, scopeData); + + // Run scope event processors _after_ all other processors + eventProcessors.push(...scopeData.eventProcessors); } + const result = notifyEventProcessors(eventProcessors, prepared, hint); + return result.then(evt => { if (evt) { // We apply the debug_meta field only after all event processors have ran, so that if any event processors modified @@ -349,6 +335,16 @@ function normalizeEvent(event: Event | null, depth: number, maxBreadth: number): return normalized; } +function getFinalScope(scope: Scope | undefined, captureContext: CaptureContext | undefined): Scope | undefined { + if (!captureContext) { + return scope; + } + + const finalScope = scope ? scope.clone() : new Scope(); + finalScope.update(captureContext); + return finalScope; +} + /** * Parse either an `EventHint` directly, or convert a `CaptureContext` to an `EventHint`. * This is used to allow to update method signatures that used to accept a `CaptureContext` but should now accept an `EventHint`. diff --git a/packages/core/src/version.ts b/packages/core/src/version.ts index 372a29702858..457365f65aa9 100644 --- a/packages/core/src/version.ts +++ b/packages/core/src/version.ts @@ -1 +1 @@ -export const SDK_VERSION = '7.86.0'; +export const SDK_VERSION = '7.89.0'; diff --git a/packages/core/test/lib/exports.test.ts b/packages/core/test/lib/exports.test.ts new file mode 100644 index 000000000000..89b4fd9105d5 --- /dev/null +++ b/packages/core/test/lib/exports.test.ts @@ -0,0 +1,53 @@ +import { Hub, Scope, getCurrentScope, makeMain, withScope } from '../../src'; +import { TestClient, getDefaultTestClientOptions } from '../mocks/client'; + +function getTestClient(): TestClient { + return new TestClient( + getDefaultTestClientOptions({ + dsn: 'https://username@domain/123', + }), + ); +} + +describe('withScope', () => { + beforeEach(() => { + const client = getTestClient(); + const hub = new Hub(client); + makeMain(hub); + }); + + it('works without a return value', () => { + const scope1 = getCurrentScope(); + expect(scope1).toBeInstanceOf(Scope); + + scope1.setTag('foo', 'bar'); + + const res = withScope(scope => { + expect(scope).toBeInstanceOf(Scope); + expect(scope).not.toBe(scope1); + expect(scope['_tags']).toEqual({ foo: 'bar' }); + + expect(getCurrentScope()).toBe(scope); + }); + + expect(getCurrentScope()).toBe(scope1); + expect(res).toBe(undefined); + }); + + it('works with a return value', () => { + const res = withScope(scope => { + return 'foo'; + }); + + expect(res).toBe('foo'); + }); + + it('works with an async function', async () => { + const res = withScope(async scope => { + return 'foo'; + }); + + expect(res).toBeInstanceOf(Promise); + expect(await res).toBe('foo'); + }); +}); diff --git a/packages/core/test/lib/hint.test.ts b/packages/core/test/lib/hint.test.ts index cdcfa9368cbe..5fb69ce39fff 100644 --- a/packages/core/test/lib/hint.test.ts +++ b/packages/core/test/lib/hint.test.ts @@ -1,4 +1,4 @@ -import { captureEvent, configureScope } from '@sentry/core'; +import { captureEvent, getCurrentScope } from '@sentry/core'; import { GLOBAL_OBJ } from '@sentry/utils'; import { initAndBind } from '../../src/sdk'; @@ -109,7 +109,7 @@ describe('Hint', () => { const options = getDefaultTestClientOptions({ dsn: PUBLIC_DSN }); initAndBind(TestClient, options); - configureScope(scope => scope.addAttachment({ filename: 'scope.file', data: 'great content!' })); + getCurrentScope().addAttachment({ filename: 'scope.file', data: 'great content!' }); captureEvent({}, { attachments: [{ filename: 'some-file.txt', data: 'Hello' }] }); diff --git a/packages/core/test/lib/integration.test.ts b/packages/core/test/lib/integration.test.ts index 54bd426abb5c..65bf30483d86 100644 --- a/packages/core/test/lib/integration.test.ts +++ b/packages/core/test/lib/integration.test.ts @@ -2,7 +2,13 @@ import type { Integration, Options } from '@sentry/types'; import { logger } from '@sentry/utils'; import { Hub, makeMain } from '../../src/hub'; -import { addIntegration, getIntegrationsToSetup, installedIntegrations, setupIntegration } from '../../src/integration'; +import { + addIntegration, + convertIntegrationFnToClass, + getIntegrationsToSetup, + installedIntegrations, + setupIntegration, +} from '../../src/integration'; import { TestClient, getDefaultTestClientOptions } from '../mocks/client'; function getTestClient(): TestClient { @@ -647,3 +653,51 @@ describe('addIntegration', () => { expect(warnings).toHaveBeenCalledWith('Cannot add integration "test" because no SDK Client is available.'); }); }); + +describe('convertIntegrationFnToClass', () => { + /* eslint-disable deprecation/deprecation */ + it('works with a minimal integration', () => { + const integrationFn = () => ({ name: 'testName' }); + + const IntegrationClass = convertIntegrationFnToClass('testName', integrationFn); + + expect(IntegrationClass.id).toBe('testName'); + + const integration = new IntegrationClass(); + expect(integration).toEqual({ + name: 'testName', + setupOnce: expect.any(Function), + }); + }); + + it('works with integration hooks', () => { + const setup = jest.fn(); + const setupOnce = jest.fn(); + const processEvent = jest.fn(); + const preprocessEvent = jest.fn(); + + const integrationFn = () => { + return { + name: 'testName', + setup, + setupOnce, + processEvent, + preprocessEvent, + }; + }; + + const IntegrationClass = convertIntegrationFnToClass('testName', integrationFn); + + expect(IntegrationClass.id).toBe('testName'); + + const integration = new IntegrationClass(); + expect(integration).toEqual({ + name: 'testName', + setupOnce, + setup, + processEvent, + preprocessEvent, + }); + }); + /* eslint-enable deprecation/deprecation */ +}); diff --git a/packages/core/test/lib/integrations/requestdata.test.ts b/packages/core/test/lib/integrations/requestdata.test.ts index 982d5f57566d..fe80c2ffd623 100644 --- a/packages/core/test/lib/integrations/requestdata.test.ts +++ b/packages/core/test/lib/integrations/requestdata.test.ts @@ -1,13 +1,12 @@ import type { IncomingMessage } from 'http'; import type { RequestDataIntegrationOptions } from '@sentry/core'; -import { Hub, RequestData, getCurrentHub, makeMain } from '@sentry/core'; +import { RequestData, getCurrentHub } from '@sentry/core'; import type { Event, EventProcessor } from '@sentry/types'; import * as sentryUtils from '@sentry/utils'; import { TestClient, getDefaultTestClientOptions } from '../../mocks/client'; const addRequestDataToEventSpy = jest.spyOn(sentryUtils, 'addRequestDataToEvent'); -const requestDataEventProcessor = jest.fn(); const headers = { ears: 'furry', nose: 'wet', tongue: 'spotted', cookie: 'favorite=zukes' }; const method = 'wagging'; @@ -16,10 +15,7 @@ const hostname = 'the.dog.park'; const path = '/by/the/trees/'; const queryString = 'chase=me&please=thankyou'; -function initWithRequestDataIntegrationOptions(integrationOptions: RequestDataIntegrationOptions): void { - const setMockEventProcessor = (eventProcessor: EventProcessor) => - requestDataEventProcessor.mockImplementationOnce(eventProcessor); - +function initWithRequestDataIntegrationOptions(integrationOptions: RequestDataIntegrationOptions): EventProcessor { const requestDataIntegration = new RequestData({ ...integrationOptions, }); @@ -30,12 +26,15 @@ function initWithRequestDataIntegrationOptions(integrationOptions: RequestDataIn integrations: [requestDataIntegration], }), ); - client.setupIntegrations = () => requestDataIntegration.setupOnce(setMockEventProcessor, getCurrentHub); - client.getIntegration = () => requestDataIntegration as any; - const hub = new Hub(client); + getCurrentHub().bindClient(client); + + const eventProcessors = client['_eventProcessors'] as EventProcessor[]; + const eventProcessor = eventProcessors.find(processor => processor.id === 'RequestData'); + + expect(eventProcessor).toBeDefined(); - makeMain(hub); + return eventProcessor!; } describe('`RequestData` integration', () => { @@ -58,9 +57,9 @@ describe('`RequestData` integration', () => { describe('option conversion', () => { it('leaves `ip` and `user` at top level of `include`', () => { - initWithRequestDataIntegrationOptions({ include: { ip: false, user: true } }); + const requestDataEventProcessor = initWithRequestDataIntegrationOptions({ include: { ip: false, user: true } }); - requestDataEventProcessor(event); + void requestDataEventProcessor(event, {}); const passedOptions = addRequestDataToEventSpy.mock.calls[0][2]; @@ -68,9 +67,9 @@ describe('`RequestData` integration', () => { }); it('moves `transactionNamingScheme` to `transaction` include', () => { - initWithRequestDataIntegrationOptions({ transactionNamingScheme: 'path' }); + const requestDataEventProcessor = initWithRequestDataIntegrationOptions({ transactionNamingScheme: 'path' }); - requestDataEventProcessor(event); + void requestDataEventProcessor(event, {}); const passedOptions = addRequestDataToEventSpy.mock.calls[0][2]; @@ -78,9 +77,11 @@ describe('`RequestData` integration', () => { }); it('moves `true` request keys into `request` include, but omits `false` ones', async () => { - initWithRequestDataIntegrationOptions({ include: { data: true, cookies: false } }); + const requestDataEventProcessor = initWithRequestDataIntegrationOptions({ + include: { data: true, cookies: false }, + }); - requestDataEventProcessor(event); + void requestDataEventProcessor(event, {}); const passedOptions = addRequestDataToEventSpy.mock.calls[0][2]; @@ -89,9 +90,11 @@ describe('`RequestData` integration', () => { }); it('moves `true` user keys into `user` include, but omits `false` ones', async () => { - initWithRequestDataIntegrationOptions({ include: { user: { id: true, email: false } } }); + const requestDataEventProcessor = initWithRequestDataIntegrationOptions({ + include: { user: { id: true, email: false } }, + }); - requestDataEventProcessor(event); + void requestDataEventProcessor(event, {}); const passedOptions = addRequestDataToEventSpy.mock.calls[0][2]; diff --git a/packages/core/test/lib/metrics/simpleaggregator.test.ts b/packages/core/test/lib/metrics/simpleaggregator.test.ts new file mode 100644 index 000000000000..cafc78d1e018 --- /dev/null +++ b/packages/core/test/lib/metrics/simpleaggregator.test.ts @@ -0,0 +1,61 @@ +import { CounterMetric } from '../../../src/metrics/instance'; +import { SimpleMetricsAggregator } from '../../../src/metrics/simpleaggregator'; +import { serializeMetricBuckets } from '../../../src/metrics/utils'; +import { TestClient, getDefaultTestClientOptions } from '../../mocks/client'; + +describe('SimpleMetricsAggregator', () => { + const options = getDefaultTestClientOptions({ tracesSampleRate: 0.0 }); + const testClient = new TestClient(options); + + it('adds items to buckets', () => { + const aggregator = new SimpleMetricsAggregator(testClient); + aggregator.add('c', 'requests', 1); + expect(aggregator['_buckets'].size).toEqual(1); + + const firstValue = aggregator['_buckets'].values().next().value; + expect(firstValue).toEqual([expect.any(CounterMetric), expect.any(Number), 'c', 'requests', 'none', {}]); + }); + + it('groups same items together', () => { + const aggregator = new SimpleMetricsAggregator(testClient); + aggregator.add('c', 'requests', 1); + expect(aggregator['_buckets'].size).toEqual(1); + aggregator.add('c', 'requests', 1); + expect(aggregator['_buckets'].size).toEqual(1); + + const firstValue = aggregator['_buckets'].values().next().value; + expect(firstValue).toEqual([expect.any(CounterMetric), expect.any(Number), 'c', 'requests', 'none', {}]); + + expect(firstValue[0]._value).toEqual(2); + }); + + it('differentiates based on tag value', () => { + const aggregator = new SimpleMetricsAggregator(testClient); + aggregator.add('g', 'cpu', 50); + expect(aggregator['_buckets'].size).toEqual(1); + aggregator.add('g', 'cpu', 55, undefined, { a: 'value' }); + expect(aggregator['_buckets'].size).toEqual(2); + }); + + describe('serializeBuckets', () => { + it('serializes ', () => { + const aggregator = new SimpleMetricsAggregator(testClient); + aggregator.add('c', 'requests', 8); + aggregator.add('g', 'cpu', 50); + aggregator.add('g', 'cpu', 55); + aggregator.add('g', 'cpu', 52); + aggregator.add('d', 'lcp', 1, 'second', { a: 'value', b: 'anothervalue' }); + aggregator.add('d', 'lcp', 1.2, 'second', { a: 'value', b: 'anothervalue' }); + aggregator.add('s', 'important_people', 'a', 'none', { numericKey: 2 }); + aggregator.add('s', 'important_people', 'b', 'none', { numericKey: 2 }); + + const metricBuckets = Array.from(aggregator['_buckets']).map(([, bucketItem]) => bucketItem); + const serializedBuckets = serializeMetricBuckets(metricBuckets); + + expect(serializedBuckets).toContain('requests@none:8|c|T'); + expect(serializedBuckets).toContain('cpu@none:52:50:55:157:3|g|T'); + expect(serializedBuckets).toContain('lcp@second:1:1.2|d|#a:value,b:anothervalue|T'); + expect(serializedBuckets).toContain('important_people@none:97:98|s|#numericKey:2|T'); + }); + }); +}); diff --git a/packages/core/test/lib/metrics/utils.test.ts b/packages/core/test/lib/metrics/utils.test.ts new file mode 100644 index 000000000000..fe96404b72ea --- /dev/null +++ b/packages/core/test/lib/metrics/utils.test.ts @@ -0,0 +1,21 @@ +import { + COUNTER_METRIC_TYPE, + DISTRIBUTION_METRIC_TYPE, + GAUGE_METRIC_TYPE, + SET_METRIC_TYPE, +} from '../../../src/metrics/constants'; +import { getBucketKey } from '../../../src/metrics/utils'; + +describe('getBucketKey', () => { + it.each([ + [COUNTER_METRIC_TYPE, 'requests', 'none', {}, 'crequestsnone'], + [GAUGE_METRIC_TYPE, 'cpu', 'none', {}, 'gcpunone'], + [DISTRIBUTION_METRIC_TYPE, 'lcp', 'second', { a: 'value', b: 'anothervalue' }, 'dlcpseconda,value,b,anothervalue'], + [DISTRIBUTION_METRIC_TYPE, 'lcp', 'second', { b: 'anothervalue', a: 'value' }, 'dlcpseconda,value,b,anothervalue'], + [DISTRIBUTION_METRIC_TYPE, 'lcp', 'second', { a: '1', b: '2', c: '3' }, 'dlcpseconda,1,b,2,c,3'], + [DISTRIBUTION_METRIC_TYPE, 'lcp', 'second', { numericKey: '2' }, 'dlcpsecondnumericKey,2'], + [SET_METRIC_TYPE, 'important_org_ids', 'none', { numericKey: '2' }, 'simportant_org_idsnonenumericKey,2'], + ])('should return', (metricType, name, unit, tags, expected) => { + expect(getBucketKey(metricType, name, unit, tags)).toEqual(expected); + }); +}); diff --git a/packages/core/test/lib/tracing/errors.test.ts b/packages/core/test/lib/tracing/errors.test.ts index f4de76234ca2..20db043865a9 100644 --- a/packages/core/test/lib/tracing/errors.test.ts +++ b/packages/core/test/lib/tracing/errors.test.ts @@ -40,7 +40,7 @@ describe('registerErrorHandlers()', () => { }); afterEach(() => { - hub.configureScope(scope => scope.setSpan(undefined)); + hub.getScope().setSpan(undefined); }); it('registers error instrumentation', () => { @@ -67,7 +67,7 @@ describe('registerErrorHandlers()', () => { it('sets status for transaction on scope on error', () => { registerErrorInstrumentation(); const transaction = hub.startTransaction({ name: 'test' }); - hub.configureScope(scope => scope.setSpan(transaction)); + hub.getScope().setSpan(transaction); mockErrorCallback({} as HandlerDataError); expect(transaction.status).toBe('internal_error'); @@ -78,7 +78,7 @@ describe('registerErrorHandlers()', () => { it('sets status for transaction on scope on unhandledrejection', () => { registerErrorInstrumentation(); const transaction = hub.startTransaction({ name: 'test' }); - hub.configureScope(scope => scope.setSpan(transaction)); + hub.getScope().setSpan(transaction); mockUnhandledRejectionCallback({}); expect(transaction.status).toBe('internal_error'); diff --git a/packages/core/test/lib/utils/isSentryRequestUrl.test.ts b/packages/core/test/lib/utils/isSentryRequestUrl.test.ts index b1671b9410e8..98fd7e54207b 100644 --- a/packages/core/test/lib/utils/isSentryRequestUrl.test.ts +++ b/packages/core/test/lib/utils/isSentryRequestUrl.test.ts @@ -1,4 +1,4 @@ -import type { Hub } from '@sentry/types'; +import type { Client, Hub } from '@sentry/types'; import { isSentryRequestUrl } from '../../../src'; @@ -12,15 +12,21 @@ describe('isSentryRequestUrl', () => { ['http://tunnel:4200/', 'sentry-dsn.com', 'http://tunnel:4200', true], ['http://tunnel:4200/a', 'sentry-dsn.com', 'http://tunnel:4200', false], ])('works with url=%s, dsn=%s, tunnel=%s', (url: string, dsn: string, tunnel: string, expected: boolean) => { + const client = { + getOptions: () => ({ tunnel }), + getDsn: () => ({ host: dsn }), + } as unknown as Client; + const hub = { getClient: () => { - return { - getOptions: () => ({ tunnel }), - getDsn: () => ({ host: dsn }), - }; + return client; }, } as unknown as Hub; + // Works with hub passed expect(isSentryRequestUrl(url, hub)).toBe(expected); + + // Works with client passed + expect(isSentryRequestUrl(url, client)).toBe(expected); }); }); diff --git a/packages/core/test/mocks/integration.ts b/packages/core/test/mocks/integration.ts index ce95d04520a7..4c229ce27294 100644 --- a/packages/core/test/mocks/integration.ts +++ b/packages/core/test/mocks/integration.ts @@ -1,6 +1,6 @@ import type { Event, EventProcessor, Integration } from '@sentry/types'; -import { configureScope, getCurrentHub } from '../../src'; +import { getCurrentHub, getCurrentScope } from '../../src'; export class TestIntegration implements Integration { public static id: string = 'TestIntegration'; @@ -18,9 +18,7 @@ export class TestIntegration implements Integration { eventProcessor.id = this.name; - configureScope(scope => { - scope.addEventProcessor(eventProcessor); - }); + getCurrentScope().addEventProcessor(eventProcessor); } } diff --git a/packages/deno/lib.deno.d.ts b/packages/deno/lib.deno.d.ts new file mode 100644 index 000000000000..62eec898407c --- /dev/null +++ b/packages/deno/lib.deno.d.ts @@ -0,0 +1,14136 @@ +// Copyright 2018-2023 the Deno authors. All rights reserved. MIT license. + +/// +/// +/// + +/** Deno provides extra properties on `import.meta`. These are included here + * to ensure that these are still available when using the Deno namespace in + * conjunction with other type libs, like `dom`. + * + * @category ES Modules + */ +declare interface ImportMeta { + /** A string representation of the fully qualified module URL. When the + * module is loaded locally, the value will be a file URL (e.g. + * `file:///path/module.ts`). + * + * You can also parse the string as a URL to determine more information about + * how the current module was loaded. For example to determine if a module was + * local or not: + * + * ```ts + * const url = new URL(import.meta.url); + * if (url.protocol === "file:") { + * console.log("this module was loaded locally"); + * } + * ``` + */ + url: string; + + /** A flag that indicates if the current module is the main module that was + * called when starting the program under Deno. + * + * ```ts + * if (import.meta.main) { + * // this was loaded as the main module, maybe do some bootstrapping + * } + * ``` + */ + main: boolean; + + /** A function that returns resolved specifier as if it would be imported + * using `import(specifier)`. + * + * ```ts + * console.log(import.meta.resolve("./foo.js")); + * // file:///dev/foo.js + * ``` + */ + resolve(specifier: string): string; +} + +/** Deno supports [User Timing Level 3](https://w3c.github.io/user-timing) + * which is not widely supported yet in other runtimes. + * + * Check out the + * [Performance API](https://developer.mozilla.org/en-US/docs/Web/API/Performance) + * documentation on MDN for further information about how to use the API. + * + * @category Performance + */ +declare interface Performance { + /** Stores a timestamp with the associated name (a "mark"). */ + mark(markName: string, options?: PerformanceMarkOptions): PerformanceMark; + + /** Stores the `DOMHighResTimeStamp` duration between two marks along with the + * associated name (a "measure"). */ + measure( + measureName: string, + options?: PerformanceMeasureOptions, + ): PerformanceMeasure; +} + +/** + * Options which are used in conjunction with `performance.mark`. Check out the + * MDN + * [`performance.mark()`](https://developer.mozilla.org/en-US/docs/Web/API/Performance/mark#markoptions) + * documentation for more details. + * + * @category Performance + */ +declare interface PerformanceMarkOptions { + /** Metadata to be included in the mark. */ + // deno-lint-ignore no-explicit-any + detail?: any; + + /** Timestamp to be used as the mark time. */ + startTime?: number; +} + +/** + * Options which are used in conjunction with `performance.measure`. Check out the + * MDN + * [`performance.mark()`](https://developer.mozilla.org/en-US/docs/Web/API/Performance/measure#measureoptions) + * documentation for more details. + * + * @category Performance + */ +declare interface PerformanceMeasureOptions { + /** Metadata to be included in the measure. */ + // deno-lint-ignore no-explicit-any + detail?: any; + + /** Timestamp to be used as the start time or string to be used as start + * mark. */ + start?: string | number; + + /** Duration between the start and end times. */ + duration?: number; + + /** Timestamp to be used as the end time or string to be used as end mark. */ + end?: string | number; +} + +/** The global namespace where Deno specific, non-standard APIs are located. */ +declare namespace Deno { + /** A set of error constructors that are raised by Deno APIs. + * + * Can be used to provide more specific handling of failures within code + * which is using Deno APIs. For example, handling attempting to open a file + * which does not exist: + * + * ```ts + * try { + * const file = await Deno.open("./some/file.txt"); + * } catch (error) { + * if (error instanceof Deno.errors.NotFound) { + * console.error("the file was not found"); + * } else { + * // otherwise re-throw + * throw error; + * } + * } + * ``` + * + * @category Errors + */ + export namespace errors { + /** + * Raised when the underlying operating system indicates that the file + * was not found. + * + * @category Errors */ + export class NotFound extends Error {} + /** + * Raised when the underlying operating system indicates the current user + * which the Deno process is running under does not have the appropriate + * permissions to a file or resource, or the user _did not_ provide required + * `--allow-*` flag. + * + * @category Errors */ + export class PermissionDenied extends Error {} + /** + * Raised when the underlying operating system reports that a connection to + * a resource is refused. + * + * @category Errors */ + export class ConnectionRefused extends Error {} + /** + * Raised when the underlying operating system reports that a connection has + * been reset. With network servers, it can be a _normal_ occurrence where a + * client will abort a connection instead of properly shutting it down. + * + * @category Errors */ + export class ConnectionReset extends Error {} + /** + * Raised when the underlying operating system reports an `ECONNABORTED` + * error. + * + * @category Errors */ + export class ConnectionAborted extends Error {} + /** + * Raised when the underlying operating system reports an `ENOTCONN` error. + * + * @category Errors */ + export class NotConnected extends Error {} + /** + * Raised when attempting to open a server listener on an address and port + * that already has a listener. + * + * @category Errors */ + export class AddrInUse extends Error {} + /** + * Raised when the underlying operating system reports an `EADDRNOTAVAIL` + * error. + * + * @category Errors */ + export class AddrNotAvailable extends Error {} + /** + * Raised when trying to write to a resource and a broken pipe error occurs. + * This can happen when trying to write directly to `stdout` or `stderr` + * and the operating system is unable to pipe the output for a reason + * external to the Deno runtime. + * + * @category Errors */ + export class BrokenPipe extends Error {} + /** + * Raised when trying to create a resource, like a file, that already + * exits. + * + * @category Errors */ + export class AlreadyExists extends Error {} + /** + * Raised when an operation to returns data that is invalid for the + * operation being performed. + * + * @category Errors */ + export class InvalidData extends Error {} + /** + * Raised when the underlying operating system reports that an I/O operation + * has timed out (`ETIMEDOUT`). + * + * @category Errors */ + export class TimedOut extends Error {} + /** + * Raised when the underlying operating system reports an `EINTR` error. In + * many cases, this underlying IO error will be handled internally within + * Deno, or result in an @{link BadResource} error instead. + * + * @category Errors */ + export class Interrupted extends Error {} + /** + * Raised when the underlying operating system would need to block to + * complete but an asynchronous (non-blocking) API is used. + * + * @category Errors */ + export class WouldBlock extends Error {} + /** + * Raised when expecting to write to a IO buffer resulted in zero bytes + * being written. + * + * @category Errors */ + export class WriteZero extends Error {} + /** + * Raised when attempting to read bytes from a resource, but the EOF was + * unexpectedly encountered. + * + * @category Errors */ + export class UnexpectedEof extends Error {} + /** + * The underlying IO resource is invalid or closed, and so the operation + * could not be performed. + * + * @category Errors */ + export class BadResource extends Error {} + /** + * Raised in situations where when attempting to load a dynamic import, + * too many redirects were encountered. + * + * @category Errors */ + export class Http extends Error {} + /** + * Raised when the underlying IO resource is not available because it is + * being awaited on in another block of code. + * + * @category Errors */ + export class Busy extends Error {} + /** + * Raised when the underlying Deno API is asked to perform a function that + * is not currently supported. + * + * @category Errors */ + export class NotSupported extends Error {} + /** + * Raised when too many symbolic links were encountered when resolving the + * filename. + * + * @category Errors */ + export class FilesystemLoop extends Error {} + /** + * Raised when trying to open, create or write to a directory. + * + * @category Errors */ + export class IsADirectory extends Error {} + /** + * Raised when performing a socket operation but the remote host is + * not reachable. + * + * @category Errors */ + export class NetworkUnreachable extends Error {} + /** + * Raised when trying to perform an operation on a path that is not a + * directory, when directory is required. + * + * @category Errors */ + export class NotADirectory extends Error {} + } + + /** The current process ID of this instance of the Deno CLI. + * + * ```ts + * console.log(Deno.pid); + * ``` + * + * @category Runtime Environment + */ + export const pid: number; + + /** + * The process ID of parent process of this instance of the Deno CLI. + * + * ```ts + * console.log(Deno.ppid); + * ``` + * + * @category Runtime Environment + */ + export const ppid: number; + + /** @category Runtime Environment */ + export interface MemoryUsage { + /** The number of bytes of the current Deno's process resident set size, + * which is the amount of memory occupied in main memory (RAM). */ + rss: number; + /** The total size of the heap for V8, in bytes. */ + heapTotal: number; + /** The amount of the heap used for V8, in bytes. */ + heapUsed: number; + /** Memory, in bytes, associated with JavaScript objects outside of the + * JavaScript isolate. */ + external: number; + } + + /** + * Returns an object describing the memory usage of the Deno process and the + * V8 subsystem measured in bytes. + * + * @category Runtime Environment + */ + export function memoryUsage(): MemoryUsage; + + /** + * Get the `hostname` of the machine the Deno process is running on. + * + * ```ts + * console.log(Deno.hostname()); + * ``` + * + * Requires `allow-sys` permission. + * + * @tags allow-sys + * @category Runtime Environment + */ + export function hostname(): string; + + /** + * Returns an array containing the 1, 5, and 15 minute load averages. The + * load average is a measure of CPU and IO utilization of the last one, five, + * and 15 minute periods expressed as a fractional number. Zero means there + * is no load. On Windows, the three values are always the same and represent + * the current load, not the 1, 5 and 15 minute load averages. + * + * ```ts + * console.log(Deno.loadavg()); // e.g. [ 0.71, 0.44, 0.44 ] + * ``` + * + * Requires `allow-sys` permission. + * + * On Windows there is no API available to retrieve this information and this method returns `[ 0, 0, 0 ]`. + * + * @tags allow-sys + * @category Observability + */ + export function loadavg(): number[]; + + /** + * The information for a network interface returned from a call to + * {@linkcode Deno.networkInterfaces}. + * + * @category Network + */ + export interface NetworkInterfaceInfo { + /** The network interface name. */ + name: string; + /** The IP protocol version. */ + family: "IPv4" | "IPv6"; + /** The IP address bound to the interface. */ + address: string; + /** The netmask applied to the interface. */ + netmask: string; + /** The IPv6 scope id or `null`. */ + scopeid: number | null; + /** The CIDR range. */ + cidr: string; + /** The MAC address. */ + mac: string; + } + + /** + * Returns an array of the network interface information. + * + * ```ts + * console.log(Deno.networkInterfaces()); + * ``` + * + * Requires `allow-sys` permission. + * + * @tags allow-sys + * @category Network + */ + export function networkInterfaces(): NetworkInterfaceInfo[]; + + /** + * Displays the total amount of free and used physical and swap memory in the + * system, as well as the buffers and caches used by the kernel. + * + * This is similar to the `free` command in Linux + * + * ```ts + * console.log(Deno.systemMemoryInfo()); + * ``` + * + * Requires `allow-sys` permission. + * + * @tags allow-sys + * @category Runtime Environment + */ + export function systemMemoryInfo(): SystemMemoryInfo; + + /** + * Information returned from a call to {@linkcode Deno.systemMemoryInfo}. + * + * @category Runtime Environment + */ + export interface SystemMemoryInfo { + /** Total installed memory in bytes. */ + total: number; + /** Unused memory in bytes. */ + free: number; + /** Estimation of how much memory, in bytes, is available for starting new + * applications, without swapping. Unlike the data provided by the cache or + * free fields, this field takes into account page cache and also that not + * all reclaimable memory will be reclaimed due to items being in use. + */ + available: number; + /** Memory used by kernel buffers. */ + buffers: number; + /** Memory used by the page cache and slabs. */ + cached: number; + /** Total swap memory. */ + swapTotal: number; + /** Unused swap memory. */ + swapFree: number; + } + + /** Reflects the `NO_COLOR` environment variable at program start. + * + * When the value is `true`, the Deno CLI will attempt to not send color codes + * to `stderr` or `stdout` and other command line programs should also attempt + * to respect this value. + * + * See: https://no-color.org/ + * + * @category Runtime Environment + */ + export const noColor: boolean; + + /** + * Returns the release version of the Operating System. + * + * ```ts + * console.log(Deno.osRelease()); + * ``` + * + * Requires `allow-sys` permission. + * Under consideration to possibly move to Deno.build or Deno.versions and if + * it should depend sys-info, which may not be desirable. + * + * @tags allow-sys + * @category Runtime Environment + */ + export function osRelease(): string; + + /** + * Returns the Operating System uptime in number of seconds. + * + * ```ts + * console.log(Deno.osUptime()); + * ``` + * + * Requires `allow-sys` permission. + * + * @tags allow-sys + * @category Runtime Environment + */ + export function osUptime(): number; + + /** + * Options which define the permissions within a test or worker context. + * + * `"inherit"` ensures that all permissions of the parent process will be + * applied to the test context. `"none"` ensures the test context has no + * permissions. A `PermissionOptionsObject` provides a more specific + * set of permissions to the test context. + * + * @category Permissions */ + export type PermissionOptions = + | "inherit" + | "none" + | PermissionOptionsObject; + + /** + * A set of options which can define the permissions within a test or worker + * context at a highly specific level. + * + * @category Permissions */ + export interface PermissionOptionsObject { + /** Specifies if the `env` permission should be requested or revoked. + * If set to `"inherit"`, the current `env` permission will be inherited. + * If set to `true`, the global `env` permission will be requested. + * If set to `false`, the global `env` permission will be revoked. + * + * @default {false} + */ + env?: "inherit" | boolean | string[]; + + /** Specifies if the `sys` permission should be requested or revoked. + * If set to `"inherit"`, the current `sys` permission will be inherited. + * If set to `true`, the global `sys` permission will be requested. + * If set to `false`, the global `sys` permission will be revoked. + * + * @default {false} + */ + sys?: "inherit" | boolean | string[]; + + /** Specifies if the `hrtime` permission should be requested or revoked. + * If set to `"inherit"`, the current `hrtime` permission will be inherited. + * If set to `true`, the global `hrtime` permission will be requested. + * If set to `false`, the global `hrtime` permission will be revoked. + * + * @default {false} + */ + hrtime?: "inherit" | boolean; + + /** Specifies if the `net` permission should be requested or revoked. + * if set to `"inherit"`, the current `net` permission will be inherited. + * if set to `true`, the global `net` permission will be requested. + * if set to `false`, the global `net` permission will be revoked. + * if set to `string[]`, the `net` permission will be requested with the + * specified host strings with the format `"[:]`. + * + * @default {false} + * + * Examples: + * + * ```ts + * import { assertEquals } from "https://deno.land/std/assert/mod.ts"; + * + * Deno.test({ + * name: "inherit", + * permissions: { + * net: "inherit", + * }, + * async fn() { + * const status = await Deno.permissions.query({ name: "net" }) + * assertEquals(status.state, "granted"); + * }, + * }); + * ``` + * + * ```ts + * import { assertEquals } from "https://deno.land/std/assert/mod.ts"; + * + * Deno.test({ + * name: "true", + * permissions: { + * net: true, + * }, + * async fn() { + * const status = await Deno.permissions.query({ name: "net" }); + * assertEquals(status.state, "granted"); + * }, + * }); + * ``` + * + * ```ts + * import { assertEquals } from "https://deno.land/std/assert/mod.ts"; + * + * Deno.test({ + * name: "false", + * permissions: { + * net: false, + * }, + * async fn() { + * const status = await Deno.permissions.query({ name: "net" }); + * assertEquals(status.state, "denied"); + * }, + * }); + * ``` + * + * ```ts + * import { assertEquals } from "https://deno.land/std/assert/mod.ts"; + * + * Deno.test({ + * name: "localhost:8080", + * permissions: { + * net: ["localhost:8080"], + * }, + * async fn() { + * const status = await Deno.permissions.query({ name: "net", host: "localhost:8080" }); + * assertEquals(status.state, "granted"); + * }, + * }); + * ``` + */ + net?: "inherit" | boolean | string[]; + + /** Specifies if the `ffi` permission should be requested or revoked. + * If set to `"inherit"`, the current `ffi` permission will be inherited. + * If set to `true`, the global `ffi` permission will be requested. + * If set to `false`, the global `ffi` permission will be revoked. + * + * @default {false} + */ + ffi?: "inherit" | boolean | Array; + + /** Specifies if the `read` permission should be requested or revoked. + * If set to `"inherit"`, the current `read` permission will be inherited. + * If set to `true`, the global `read` permission will be requested. + * If set to `false`, the global `read` permission will be revoked. + * If set to `Array`, the `read` permission will be requested with the + * specified file paths. + * + * @default {false} + */ + read?: "inherit" | boolean | Array; + + /** Specifies if the `run` permission should be requested or revoked. + * If set to `"inherit"`, the current `run` permission will be inherited. + * If set to `true`, the global `run` permission will be requested. + * If set to `false`, the global `run` permission will be revoked. + * + * @default {false} + */ + run?: "inherit" | boolean | Array; + + /** Specifies if the `write` permission should be requested or revoked. + * If set to `"inherit"`, the current `write` permission will be inherited. + * If set to `true`, the global `write` permission will be requested. + * If set to `false`, the global `write` permission will be revoked. + * If set to `Array`, the `write` permission will be requested with the + * specified file paths. + * + * @default {false} + */ + write?: "inherit" | boolean | Array; + } + + /** + * Context that is passed to a testing function, which can be used to either + * gain information about the current test, or register additional test + * steps within the current test. + * + * @category Testing */ + export interface TestContext { + /** The current test name. */ + name: string; + /** The string URL of the current test. */ + origin: string; + /** If the current test is a step of another test, the parent test context + * will be set here. */ + parent?: TestContext; + + /** Run a sub step of the parent test or step. Returns a promise + * that resolves to a boolean signifying if the step completed successfully. + * + * The returned promise never rejects unless the arguments are invalid. + * + * If the test was ignored the promise returns `false`. + * + * ```ts + * Deno.test({ + * name: "a parent test", + * async fn(t) { + * console.log("before the step"); + * await t.step({ + * name: "step 1", + * fn(t) { + * console.log("current step:", t.name); + * } + * }); + * console.log("after the step"); + * } + * }); + * ``` + */ + step(definition: TestStepDefinition): Promise; + + /** Run a sub step of the parent test or step. Returns a promise + * that resolves to a boolean signifying if the step completed successfully. + * + * The returned promise never rejects unless the arguments are invalid. + * + * If the test was ignored the promise returns `false`. + * + * ```ts + * Deno.test( + * "a parent test", + * async (t) => { + * console.log("before the step"); + * await t.step( + * "step 1", + * (t) => { + * console.log("current step:", t.name); + * } + * ); + * console.log("after the step"); + * } + * ); + * ``` + */ + step( + name: string, + fn: (t: TestContext) => void | Promise, + ): Promise; + + /** Run a sub step of the parent test or step. Returns a promise + * that resolves to a boolean signifying if the step completed successfully. + * + * The returned promise never rejects unless the arguments are invalid. + * + * If the test was ignored the promise returns `false`. + * + * ```ts + * Deno.test(async function aParentTest(t) { + * console.log("before the step"); + * await t.step(function step1(t) { + * console.log("current step:", t.name); + * }); + * console.log("after the step"); + * }); + * ``` + */ + step(fn: (t: TestContext) => void | Promise): Promise; + } + + /** @category Testing */ + export interface TestStepDefinition { + /** The test function that will be tested when this step is executed. The + * function can take an argument which will provide information about the + * current step's context. */ + fn: (t: TestContext) => void | Promise; + /** The name of the step. */ + name: string; + /** If truthy the current test step will be ignored. + * + * This is a quick way to skip over a step, but also can be used for + * conditional logic, like determining if an environment feature is present. + */ + ignore?: boolean; + /** Check that the number of async completed operations after the test step + * is the same as number of dispatched operations. This ensures that the + * code tested does not start async operations which it then does + * not await. This helps in preventing logic errors and memory leaks + * in the application code. + * + * Defaults to the parent test or step's value. */ + sanitizeOps?: boolean; + /** Ensure the test step does not "leak" resources - like open files or + * network connections - by ensuring the open resources at the start of the + * step match the open resources at the end of the step. + * + * Defaults to the parent test or step's value. */ + sanitizeResources?: boolean; + /** Ensure the test step does not prematurely cause the process to exit, + * for example via a call to {@linkcode Deno.exit}. + * + * Defaults to the parent test or step's value. */ + sanitizeExit?: boolean; + } + + /** @category Testing */ + export interface TestDefinition { + fn: (t: TestContext) => void | Promise; + /** The name of the test. */ + name: string; + /** If truthy the current test step will be ignored. + * + * It is a quick way to skip over a step, but also can be used for + * conditional logic, like determining if an environment feature is present. + */ + ignore?: boolean; + /** If at least one test has `only` set to `true`, only run tests that have + * `only` set to `true` and fail the test suite. */ + only?: boolean; + /** Check that the number of async completed operations after the test step + * is the same as number of dispatched operations. This ensures that the + * code tested does not start async operations which it then does + * not await. This helps in preventing logic errors and memory leaks + * in the application code. + * + * @default {true} */ + sanitizeOps?: boolean; + /** Ensure the test step does not "leak" resources - like open files or + * network connections - by ensuring the open resources at the start of the + * test match the open resources at the end of the test. + * + * @default {true} */ + sanitizeResources?: boolean; + /** Ensure the test case does not prematurely cause the process to exit, + * for example via a call to {@linkcode Deno.exit}. + * + * @default {true} */ + sanitizeExit?: boolean; + /** Specifies the permissions that should be used to run the test. + * + * Set this to "inherit" to keep the calling runtime permissions, set this + * to "none" to revoke all permissions, or set a more specific set of + * permissions using a {@linkcode PermissionOptionsObject}. + * + * @default {"inherit"} */ + permissions?: PermissionOptions; + } + + /** Register a test which will be run when `deno test` is used on the command + * line and the containing module looks like a test module. + * + * `fn` can be async if required. + * + * ```ts + * import { assertEquals } from "https://deno.land/std/assert/mod.ts"; + * + * Deno.test({ + * name: "example test", + * fn() { + * assertEquals("world", "world"); + * }, + * }); + * + * Deno.test({ + * name: "example ignored test", + * ignore: Deno.build.os === "windows", + * fn() { + * // This test is ignored only on Windows machines + * }, + * }); + * + * Deno.test({ + * name: "example async test", + * async fn() { + * const decoder = new TextDecoder("utf-8"); + * const data = await Deno.readFile("hello_world.txt"); + * assertEquals(decoder.decode(data), "Hello world"); + * } + * }); + * ``` + * + * @category Testing + */ + export const test: DenoTest; + + /** + * @category Testing + */ + interface DenoTest { + /** Register a test which will be run when `deno test` is used on the command + * line and the containing module looks like a test module. + * + * `fn` can be async if required. + * + * ```ts + * import { assertEquals } from "https://deno.land/std/assert/mod.ts"; + * + * Deno.test({ + * name: "example test", + * fn() { + * assertEquals("world", "world"); + * }, + * }); + * + * Deno.test({ + * name: "example ignored test", + * ignore: Deno.build.os === "windows", + * fn() { + * // This test is ignored only on Windows machines + * }, + * }); + * + * Deno.test({ + * name: "example async test", + * async fn() { + * const decoder = new TextDecoder("utf-8"); + * const data = await Deno.readFile("hello_world.txt"); + * assertEquals(decoder.decode(data), "Hello world"); + * } + * }); + * ``` + * + * @category Testing + */ + (t: TestDefinition): void; + + /** Register a test which will be run when `deno test` is used on the command + * line and the containing module looks like a test module. + * + * `fn` can be async if required. + * + * ```ts + * import { assertEquals } from "https://deno.land/std/assert/mod.ts"; + * + * Deno.test("My test description", () => { + * assertEquals("hello", "hello"); + * }); + * + * Deno.test("My async test description", async () => { + * const decoder = new TextDecoder("utf-8"); + * const data = await Deno.readFile("hello_world.txt"); + * assertEquals(decoder.decode(data), "Hello world"); + * }); + * ``` + * + * @category Testing + */ + ( + name: string, + fn: (t: TestContext) => void | Promise, + ): void; + + /** Register a test which will be run when `deno test` is used on the command + * line and the containing module looks like a test module. + * + * `fn` can be async if required. Declared function must have a name. + * + * ```ts + * import { assertEquals } from "https://deno.land/std/assert/mod.ts"; + * + * Deno.test(function myTestName() { + * assertEquals("hello", "hello"); + * }); + * + * Deno.test(async function myOtherTestName() { + * const decoder = new TextDecoder("utf-8"); + * const data = await Deno.readFile("hello_world.txt"); + * assertEquals(decoder.decode(data), "Hello world"); + * }); + * ``` + * + * @category Testing + */ + (fn: (t: TestContext) => void | Promise): void; + + /** Register a test which will be run when `deno test` is used on the command + * line and the containing module looks like a test module. + * + * `fn` can be async if required. + * + * ```ts + * import {assert, fail, assertEquals} from "https://deno.land/std/assert/mod.ts"; + * + * Deno.test("My test description", { permissions: { read: true } }, (): void => { + * assertEquals("hello", "hello"); + * }); + * + * Deno.test("My async test description", { permissions: { read: false } }, async (): Promise => { + * const decoder = new TextDecoder("utf-8"); + * const data = await Deno.readFile("hello_world.txt"); + * assertEquals(decoder.decode(data), "Hello world"); + * }); + * ``` + * + * @category Testing + */ + ( + name: string, + options: Omit, + fn: (t: TestContext) => void | Promise, + ): void; + + /** Register a test which will be run when `deno test` is used on the command + * line and the containing module looks like a test module. + * + * `fn` can be async if required. + * + * ```ts + * import { assertEquals } from "https://deno.land/std/assert/mod.ts"; + * + * Deno.test( + * { + * name: "My test description", + * permissions: { read: true }, + * }, + * () => { + * assertEquals("hello", "hello"); + * }, + * ); + * + * Deno.test( + * { + * name: "My async test description", + * permissions: { read: false }, + * }, + * async () => { + * const decoder = new TextDecoder("utf-8"); + * const data = await Deno.readFile("hello_world.txt"); + * assertEquals(decoder.decode(data), "Hello world"); + * }, + * ); + * ``` + * + * @category Testing + */ + ( + options: Omit, + fn: (t: TestContext) => void | Promise, + ): void; + + /** Register a test which will be run when `deno test` is used on the command + * line and the containing module looks like a test module. + * + * `fn` can be async if required. Declared function must have a name. + * + * ```ts + * import { assertEquals } from "https://deno.land/std/assert/mod.ts"; + * + * Deno.test( + * { permissions: { read: true } }, + * function myTestName() { + * assertEquals("hello", "hello"); + * }, + * ); + * + * Deno.test( + * { permissions: { read: false } }, + * async function myOtherTestName() { + * const decoder = new TextDecoder("utf-8"); + * const data = await Deno.readFile("hello_world.txt"); + * assertEquals(decoder.decode(data), "Hello world"); + * }, + * ); + * ``` + * + * @category Testing + */ + ( + options: Omit, + fn: (t: TestContext) => void | Promise, + ): void; + + /** Shorthand property for ignoring a particular test case. + * + * @category Testing + */ + ignore(t: Omit): void; + + /** Shorthand property for ignoring a particular test case. + * + * @category Testing + */ + ignore( + name: string, + fn: (t: TestContext) => void | Promise, + ): void; + + /** Shorthand property for ignoring a particular test case. + * + * @category Testing + */ + ignore(fn: (t: TestContext) => void | Promise): void; + + /** Shorthand property for ignoring a particular test case. + * + * @category Testing + */ + ignore( + name: string, + options: Omit, + fn: (t: TestContext) => void | Promise, + ): void; + + /** Shorthand property for ignoring a particular test case. + * + * @category Testing + */ + ignore( + options: Omit, + fn: (t: TestContext) => void | Promise, + ): void; + + /** Shorthand property for ignoring a particular test case. + * + * @category Testing + */ + ignore( + options: Omit, + fn: (t: TestContext) => void | Promise, + ): void; + + /** Shorthand property for focusing a particular test case. + * + * @category Testing + */ + only(t: Omit): void; + + /** Shorthand property for focusing a particular test case. + * + * @category Testing + */ + only( + name: string, + fn: (t: TestContext) => void | Promise, + ): void; + + /** Shorthand property for focusing a particular test case. + * + * @category Testing + */ + only(fn: (t: TestContext) => void | Promise): void; + + /** Shorthand property for focusing a particular test case. + * + * @category Testing + */ + only( + name: string, + options: Omit, + fn: (t: TestContext) => void | Promise, + ): void; + + /** Shorthand property for focusing a particular test case. + * + * @category Testing + */ + only( + options: Omit, + fn: (t: TestContext) => void | Promise, + ): void; + + /** Shorthand property for focusing a particular test case. + * + * @category Testing + */ + only( + options: Omit, + fn: (t: TestContext) => void | Promise, + ): void; + } + + /** + * Context that is passed to a benchmarked function. The instance is shared + * between iterations of the benchmark. Its methods can be used for example + * to override of the measured portion of the function. + * + * @category Testing + */ + export interface BenchContext { + /** The current benchmark name. */ + name: string; + /** The string URL of the current benchmark. */ + origin: string; + + /** Restarts the timer for the bench measurement. This should be called + * after doing setup work which should not be measured. + * + * Warning: This method should not be used for benchmarks averaging less + * than 10μs per iteration. In such cases it will be disabled but the call + * will still have noticeable overhead, resulting in a warning. + * + * ```ts + * Deno.bench("foo", async (t) => { + * const data = await Deno.readFile("data.txt"); + * t.start(); + * // some operation on `data`... + * }); + * ``` + */ + start(): void; + + /** End the timer early for the bench measurement. This should be called + * before doing teardown work which should not be measured. + * + * Warning: This method should not be used for benchmarks averaging less + * than 10μs per iteration. In such cases it will be disabled but the call + * will still have noticeable overhead, resulting in a warning. + * + * ```ts + * Deno.bench("foo", async (t) => { + * const file = await Deno.open("data.txt"); + * t.start(); + * // some operation on `file`... + * t.end(); + * file.close(); + * }); + * ``` + */ + end(): void; + } + + /** + * The interface for defining a benchmark test using {@linkcode Deno.bench}. + * + * @category Testing + */ + export interface BenchDefinition { + /** The test function which will be benchmarked. */ + fn: (b: BenchContext) => void | Promise; + /** The name of the test, which will be used in displaying the results. */ + name: string; + /** If truthy, the benchmark test will be ignored/skipped. */ + ignore?: boolean; + /** Group name for the benchmark. + * + * Grouped benchmarks produce a group time summary, where the difference + * in performance between each test of the group is compared. */ + group?: string; + /** Benchmark should be used as the baseline for other benchmarks. + * + * If there are multiple baselines in a group, the first one is used as the + * baseline. */ + baseline?: boolean; + /** If at least one bench has `only` set to true, only run benches that have + * `only` set to `true` and fail the bench suite. */ + only?: boolean; + /** Ensure the bench case does not prematurely cause the process to exit, + * for example via a call to {@linkcode Deno.exit}. + * + * @default {true} */ + sanitizeExit?: boolean; + /** Specifies the permissions that should be used to run the bench. + * + * Set this to `"inherit"` to keep the calling thread's permissions. + * + * Set this to `"none"` to revoke all permissions. + * + * @default {"inherit"} + */ + permissions?: PermissionOptions; + } + + /** + * Register a benchmark test which will be run when `deno bench` is used on + * the command line and the containing module looks like a bench module. + * + * If the test function (`fn`) returns a promise or is async, the test runner + * will await resolution to consider the test complete. + * + * ```ts + * import { assertEquals } from "https://deno.land/std/assert/mod.ts"; + * + * Deno.bench({ + * name: "example test", + * fn() { + * assertEquals("world", "world"); + * }, + * }); + * + * Deno.bench({ + * name: "example ignored test", + * ignore: Deno.build.os === "windows", + * fn() { + * // This test is ignored only on Windows machines + * }, + * }); + * + * Deno.bench({ + * name: "example async test", + * async fn() { + * const decoder = new TextDecoder("utf-8"); + * const data = await Deno.readFile("hello_world.txt"); + * assertEquals(decoder.decode(data), "Hello world"); + * } + * }); + * ``` + * + * @category Testing + */ + export function bench(b: BenchDefinition): void; + + /** + * Register a benchmark test which will be run when `deno bench` is used on + * the command line and the containing module looks like a bench module. + * + * If the test function (`fn`) returns a promise or is async, the test runner + * will await resolution to consider the test complete. + * + * ```ts + * import { assertEquals } from "https://deno.land/std/assert/mod.ts"; + * + * Deno.bench("My test description", () => { + * assertEquals("hello", "hello"); + * }); + * + * Deno.bench("My async test description", async () => { + * const decoder = new TextDecoder("utf-8"); + * const data = await Deno.readFile("hello_world.txt"); + * assertEquals(decoder.decode(data), "Hello world"); + * }); + * ``` + * + * @category Testing + */ + export function bench( + name: string, + fn: (b: BenchContext) => void | Promise, + ): void; + + /** + * Register a benchmark test which will be run when `deno bench` is used on + * the command line and the containing module looks like a bench module. + * + * If the test function (`fn`) returns a promise or is async, the test runner + * will await resolution to consider the test complete. + * + * ```ts + * import { assertEquals } from "https://deno.land/std/assert/mod.ts"; + * + * Deno.bench(function myTestName() { + * assertEquals("hello", "hello"); + * }); + * + * Deno.bench(async function myOtherTestName() { + * const decoder = new TextDecoder("utf-8"); + * const data = await Deno.readFile("hello_world.txt"); + * assertEquals(decoder.decode(data), "Hello world"); + * }); + * ``` + * + * @category Testing + */ + export function bench(fn: (b: BenchContext) => void | Promise): void; + + /** + * Register a benchmark test which will be run when `deno bench` is used on + * the command line and the containing module looks like a bench module. + * + * If the test function (`fn`) returns a promise or is async, the test runner + * will await resolution to consider the test complete. + * + * ```ts + * import { assertEquals } from "https://deno.land/std/assert/mod.ts"; + * + * Deno.bench( + * "My test description", + * { permissions: { read: true } }, + * () => { + * assertEquals("hello", "hello"); + * } + * ); + * + * Deno.bench( + * "My async test description", + * { permissions: { read: false } }, + * async () => { + * const decoder = new TextDecoder("utf-8"); + * const data = await Deno.readFile("hello_world.txt"); + * assertEquals(decoder.decode(data), "Hello world"); + * } + * ); + * ``` + * + * @category Testing + */ + export function bench( + name: string, + options: Omit, + fn: (b: BenchContext) => void | Promise, + ): void; + + /** + * Register a benchmark test which will be run when `deno bench` is used on + * the command line and the containing module looks like a bench module. + * + * If the test function (`fn`) returns a promise or is async, the test runner + * will await resolution to consider the test complete. + * + * ```ts + * import { assertEquals } from "https://deno.land/std/assert/mod.ts"; + * + * Deno.bench( + * { name: "My test description", permissions: { read: true } }, + * () => { + * assertEquals("hello", "hello"); + * } + * ); + * + * Deno.bench( + * { name: "My async test description", permissions: { read: false } }, + * async () => { + * const decoder = new TextDecoder("utf-8"); + * const data = await Deno.readFile("hello_world.txt"); + * assertEquals(decoder.decode(data), "Hello world"); + * } + * ); + * ``` + * + * @category Testing + */ + export function bench( + options: Omit, + fn: (b: BenchContext) => void | Promise, + ): void; + + /** + * Register a benchmark test which will be run when `deno bench` is used on + * the command line and the containing module looks like a bench module. + * + * If the test function (`fn`) returns a promise or is async, the test runner + * will await resolution to consider the test complete. + * + * ```ts + * import { assertEquals } from "https://deno.land/std/assert/mod.ts"; + * + * Deno.bench( + * { permissions: { read: true } }, + * function myTestName() { + * assertEquals("hello", "hello"); + * } + * ); + * + * Deno.bench( + * { permissions: { read: false } }, + * async function myOtherTestName() { + * const decoder = new TextDecoder("utf-8"); + * const data = await Deno.readFile("hello_world.txt"); + * assertEquals(decoder.decode(data), "Hello world"); + * } + * ); + * ``` + * + * @category Testing + */ + export function bench( + options: Omit, + fn: (b: BenchContext) => void | Promise, + ): void; + + /** Exit the Deno process with optional exit code. + * + * If no exit code is supplied then Deno will exit with return code of `0`. + * + * In worker contexts this is an alias to `self.close();`. + * + * ```ts + * Deno.exit(5); + * ``` + * + * @category Runtime Environment + */ + export function exit(code?: number): never; + + /** An interface containing methods to interact with the process environment + * variables. + * + * @tags allow-env + * @category Runtime Environment + */ + export interface Env { + /** Retrieve the value of an environment variable. + * + * Returns `undefined` if the supplied environment variable is not defined. + * + * ```ts + * console.log(Deno.env.get("HOME")); // e.g. outputs "/home/alice" + * console.log(Deno.env.get("MADE_UP_VAR")); // outputs "undefined" + * ``` + * + * Requires `allow-env` permission. + * + * @tags allow-env + */ + get(key: string): string | undefined; + + /** Set the value of an environment variable. + * + * ```ts + * Deno.env.set("SOME_VAR", "Value"); + * Deno.env.get("SOME_VAR"); // outputs "Value" + * ``` + * + * Requires `allow-env` permission. + * + * @tags allow-env + */ + set(key: string, value: string): void; + + /** Delete the value of an environment variable. + * + * ```ts + * Deno.env.set("SOME_VAR", "Value"); + * Deno.env.delete("SOME_VAR"); // outputs "undefined" + * ``` + * + * Requires `allow-env` permission. + * + * @tags allow-env + */ + delete(key: string): void; + + /** Check whether an environment variable is present or not. + * + * ```ts + * Deno.env.set("SOME_VAR", "Value"); + * Deno.env.has("SOME_VAR"); // outputs true + * ``` + * + * Requires `allow-env` permission. + * + * @tags allow-env + */ + has(key: string): boolean; + + /** Returns a snapshot of the environment variables at invocation as a + * simple object of keys and values. + * + * ```ts + * Deno.env.set("TEST_VAR", "A"); + * const myEnv = Deno.env.toObject(); + * console.log(myEnv.SHELL); + * Deno.env.set("TEST_VAR", "B"); + * console.log(myEnv.TEST_VAR); // outputs "A" + * ``` + * + * Requires `allow-env` permission. + * + * @tags allow-env + */ + toObject(): { [index: string]: string }; + } + + /** An interface containing methods to interact with the process environment + * variables. + * + * @tags allow-env + * @category Runtime Environment + */ + export const env: Env; + + /** + * Returns the path to the current deno executable. + * + * ```ts + * console.log(Deno.execPath()); // e.g. "/home/alice/.local/bin/deno" + * ``` + * + * Requires `allow-read` permission. + * + * @tags allow-read + * @category Runtime Environment + */ + export function execPath(): string; + + /** + * Change the current working directory to the specified path. + * + * ```ts + * Deno.chdir("/home/userA"); + * Deno.chdir("../userB"); + * Deno.chdir("C:\\Program Files (x86)\\Java"); + * ``` + * + * Throws {@linkcode Deno.errors.NotFound} if directory not found. + * + * Throws {@linkcode Deno.errors.PermissionDenied} if the user does not have + * operating system file access rights. + * + * Requires `allow-read` permission. + * + * @tags allow-read + * @category Runtime Environment + */ + export function chdir(directory: string | URL): void; + + /** + * Return a string representing the current working directory. + * + * If the current directory can be reached via multiple paths (due to symbolic + * links), `cwd()` may return any one of them. + * + * ```ts + * const currentWorkingDirectory = Deno.cwd(); + * ``` + * + * Throws {@linkcode Deno.errors.NotFound} if directory not available. + * + * Requires `allow-read` permission. + * + * @tags allow-read + * @category Runtime Environment + */ + export function cwd(): string; + + /** + * Creates `newpath` as a hard link to `oldpath`. + * + * ```ts + * await Deno.link("old/name", "new/name"); + * ``` + * + * Requires `allow-read` and `allow-write` permissions. + * + * @tags allow-read, allow-write + * @category File System + */ + export function link(oldpath: string, newpath: string): Promise; + + /** + * Synchronously creates `newpath` as a hard link to `oldpath`. + * + * ```ts + * Deno.linkSync("old/name", "new/name"); + * ``` + * + * Requires `allow-read` and `allow-write` permissions. + * + * @tags allow-read, allow-write + * @category File System + */ + export function linkSync(oldpath: string, newpath: string): void; + + /** + * A enum which defines the seek mode for IO related APIs that support + * seeking. + * + * @category I/O */ + export enum SeekMode { + /* Seek from the start of the file/resource. */ + Start = 0, + /* Seek from the current position within the file/resource. */ + Current = 1, + /* Seek from the end of the current file/resource. */ + End = 2, + } + + /** + * An abstract interface which when implemented provides an interface to read + * bytes into an array buffer asynchronously. + * + * @deprecated Use {@linkcode ReadableStream} instead. {@linkcode Reader} + * will be removed in v2.0.0. + * + * @category I/O */ + export interface Reader { + /** Reads up to `p.byteLength` bytes into `p`. It resolves to the number of + * bytes read (`0` < `n` <= `p.byteLength`) and rejects if any error + * encountered. Even if `read()` resolves to `n` < `p.byteLength`, it may + * use all of `p` as scratch space during the call. If some data is + * available but not `p.byteLength` bytes, `read()` conventionally resolves + * to what is available instead of waiting for more. + * + * When `read()` encounters end-of-file condition, it resolves to EOF + * (`null`). + * + * When `read()` encounters an error, it rejects with an error. + * + * Callers should always process the `n` > `0` bytes returned before + * considering the EOF (`null`). Doing so correctly handles I/O errors that + * happen after reading some bytes and also both of the allowed EOF + * behaviors. + * + * Implementations should not retain a reference to `p`. + * + * Use + * [`itereateReader`](https://deno.land/std/streams/iterate_reader.ts?s=iterateReader) + * from + * [`std/streams/iterate_reader.ts`](https://deno.land/std/streams/iterate_reader.ts) + * to turn a `Reader` into an {@linkcode AsyncIterator}. + */ + read(p: Uint8Array): Promise; + } + + /** + * An abstract interface which when implemented provides an interface to read + * bytes into an array buffer synchronously. + * + * @deprecated Use {@linkcode ReadableStream} instead. {@linkcode ReaderSync} + * will be removed in v2.0.0. + * + * @category I/O */ + export interface ReaderSync { + /** Reads up to `p.byteLength` bytes into `p`. It resolves to the number + * of bytes read (`0` < `n` <= `p.byteLength`) and rejects if any error + * encountered. Even if `readSync()` returns `n` < `p.byteLength`, it may use + * all of `p` as scratch space during the call. If some data is available + * but not `p.byteLength` bytes, `readSync()` conventionally returns what is + * available instead of waiting for more. + * + * When `readSync()` encounters end-of-file condition, it returns EOF + * (`null`). + * + * When `readSync()` encounters an error, it throws with an error. + * + * Callers should always process the `n` > `0` bytes returned before + * considering the EOF (`null`). Doing so correctly handles I/O errors that + * happen after reading some bytes and also both of the allowed EOF + * behaviors. + * + * Implementations should not retain a reference to `p`. + * + * Use + * [`itereateReaderSync`](https://deno.land/std/streams/iterate_reader.ts?s=iterateReaderSync) + * from from + * [`std/streams/iterate_reader.ts`](https://deno.land/std/streams/iterate_reader.ts) + * to turn a `ReaderSync` into an {@linkcode Iterator}. + */ + readSync(p: Uint8Array): number | null; + } + + /** + * An abstract interface which when implemented provides an interface to write + * bytes from an array buffer to a file/resource asynchronously. + * + * @deprecated Use {@linkcode WritableStream} instead. {@linkcode Writer} + * will be removed in v2.0.0. + * + * @category I/O */ + export interface Writer { + /** Writes `p.byteLength` bytes from `p` to the underlying data stream. It + * resolves to the number of bytes written from `p` (`0` <= `n` <= + * `p.byteLength`) or reject with the error encountered that caused the + * write to stop early. `write()` must reject with a non-null error if + * would resolve to `n` < `p.byteLength`. `write()` must not modify the + * slice data, even temporarily. + * + * This function is one of the lowest + * level APIs and most users should not work with this directly, but rather use + * [`writeAll()`](https://deno.land/std/streams/write_all.ts?s=writeAll) from + * [`std/streams/write_all.ts`](https://deno.land/std/streams/write_all.ts) + * instead. + * + * Implementations should not retain a reference to `p`. + */ + write(p: Uint8Array): Promise; + } + + /** + * An abstract interface which when implemented provides an interface to write + * bytes from an array buffer to a file/resource synchronously. + * + * @deprecated Use {@linkcode WritableStream} instead. {@linkcode WriterSync} + * will be removed in v2.0.0. + * + * @category I/O */ + export interface WriterSync { + /** Writes `p.byteLength` bytes from `p` to the underlying data + * stream. It returns the number of bytes written from `p` (`0` <= `n` + * <= `p.byteLength`) and any error encountered that caused the write to + * stop early. `writeSync()` must throw a non-null error if it returns `n` < + * `p.byteLength`. `writeSync()` must not modify the slice data, even + * temporarily. + * + * Implementations should not retain a reference to `p`. + */ + writeSync(p: Uint8Array): number; + } + + /** + * An abstract interface which when implemented provides an interface to close + * files/resources that were previously opened. + * + * @deprecated Use {@linkcode ReadableStream} and {@linkcode WritableStream} + * instead. {@linkcode Closer} will be removed in v2.0.0. + * + * @category I/O */ + export interface Closer { + /** Closes the resource, "freeing" the backing file/resource. */ + close(): void; + } + + /** + * An abstract interface which when implemented provides an interface to seek + * within an open file/resource asynchronously. + * + * @category I/O */ + export interface Seeker { + /** Seek sets the offset for the next `read()` or `write()` to offset, + * interpreted according to `whence`: `Start` means relative to the + * start of the file, `Current` means relative to the current offset, + * and `End` means relative to the end. Seek resolves to the new offset + * relative to the start of the file. + * + * Seeking to an offset before the start of the file is an error. Seeking to + * any positive offset is legal, but the behavior of subsequent I/O + * operations on the underlying object is implementation-dependent. + * + * It resolves with the updated offset. + */ + seek(offset: number | bigint, whence: SeekMode): Promise; + } + + /** + * An abstract interface which when implemented provides an interface to seek + * within an open file/resource synchronously. + * + * @category I/O */ + export interface SeekerSync { + /** Seek sets the offset for the next `readSync()` or `writeSync()` to + * offset, interpreted according to `whence`: `Start` means relative + * to the start of the file, `Current` means relative to the current + * offset, and `End` means relative to the end. + * + * Seeking to an offset before the start of the file is an error. Seeking to + * any positive offset is legal, but the behavior of subsequent I/O + * operations on the underlying object is implementation-dependent. + * + * It returns the updated offset. + */ + seekSync(offset: number | bigint, whence: SeekMode): number; + } + + /** + * Copies from `src` to `dst` until either EOF (`null`) is read from `src` or + * an error occurs. It resolves to the number of bytes copied or rejects with + * the first error encountered while copying. + * + * @deprecated Use {@linkcode ReadableStream.pipeTo} instead. + * {@linkcode Deno.copy} will be removed in the future. + * + * @category I/O + * + * @param src The source to copy from + * @param dst The destination to copy to + * @param options Can be used to tune size of the buffer. Default size is 32kB + */ + export function copy( + src: Reader, + dst: Writer, + options?: { bufSize?: number }, + ): Promise; + + /** + * Turns a Reader, `r`, into an async iterator. + * + * @deprecated Use {@linkcode ReadableStream} instead. {@linkcode Deno.iter} + * will be removed in the future. + * + * @category I/O + */ + export function iter( + r: Reader, + options?: { bufSize?: number }, + ): AsyncIterableIterator; + + /** + * Turns a ReaderSync, `r`, into an iterator. + * + * @deprecated Use {@linkcode ReadableStream} instead. + * {@linkcode Deno.iterSync} will be removed in the future. + * + * @category I/O + */ + export function iterSync( + r: ReaderSync, + options?: { + bufSize?: number; + }, + ): IterableIterator; + + /** Open a file and resolve to an instance of {@linkcode Deno.FsFile}. The + * file does not need to previously exist if using the `create` or `createNew` + * open options. It is the caller's responsibility to close the file when + * finished with it. + * + * ```ts + * const file = await Deno.open("/foo/bar.txt", { read: true, write: true }); + * // Do work with file + * file.close(); + * ``` + * + * Requires `allow-read` and/or `allow-write` permissions depending on + * options. + * + * @tags allow-read, allow-write + * @category File System + */ + export function open( + path: string | URL, + options?: OpenOptions, + ): Promise; + + /** Synchronously open a file and return an instance of + * {@linkcode Deno.FsFile}. The file does not need to previously exist if + * using the `create` or `createNew` open options. It is the caller's + * responsibility to close the file when finished with it. + * + * ```ts + * const file = Deno.openSync("/foo/bar.txt", { read: true, write: true }); + * // Do work with file + * file.close(); + * ``` + * + * Requires `allow-read` and/or `allow-write` permissions depending on + * options. + * + * @tags allow-read, allow-write + * @category File System + */ + export function openSync(path: string | URL, options?: OpenOptions): FsFile; + + /** Creates a file if none exists or truncates an existing file and resolves to + * an instance of {@linkcode Deno.FsFile}. + * + * ```ts + * const file = await Deno.create("/foo/bar.txt"); + * ``` + * + * Requires `allow-read` and `allow-write` permissions. + * + * @tags allow-read, allow-write + * @category File System + */ + export function create(path: string | URL): Promise; + + /** Creates a file if none exists or truncates an existing file and returns + * an instance of {@linkcode Deno.FsFile}. + * + * ```ts + * const file = Deno.createSync("/foo/bar.txt"); + * ``` + * + * Requires `allow-read` and `allow-write` permissions. + * + * @tags allow-read, allow-write + * @category File System + */ + export function createSync(path: string | URL): FsFile; + + /** Read from a resource ID (`rid`) into an array buffer (`buffer`). + * + * Resolves to either the number of bytes read during the operation or EOF + * (`null`) if there was nothing more to read. + * + * It is possible for a read to successfully return with `0` bytes. This does + * not indicate EOF. + * + * This function is one of the lowest level APIs and most users should not + * work with this directly, but rather use {@linkcode ReadableStream} and + * {@linkcode https://deno.land/std/streams/mod.ts?s=toArrayBuffer|toArrayBuffer} + * instead. + * + * **It is not guaranteed that the full buffer will be read in a single call.** + * + * ```ts + * // if "/foo/bar.txt" contains the text "hello world": + * const file = await Deno.open("/foo/bar.txt"); + * const buf = new Uint8Array(100); + * const numberOfBytesRead = await Deno.read(file.rid, buf); // 11 bytes + * const text = new TextDecoder().decode(buf); // "hello world" + * Deno.close(file.rid); + * ``` + * + * @category I/O + */ + export function read(rid: number, buffer: Uint8Array): Promise; + + /** Synchronously read from a resource ID (`rid`) into an array buffer + * (`buffer`). + * + * Returns either the number of bytes read during the operation or EOF + * (`null`) if there was nothing more to read. + * + * It is possible for a read to successfully return with `0` bytes. This does + * not indicate EOF. + * + * This function is one of the lowest level APIs and most users should not + * work with this directly, but rather use {@linkcode ReadableStream} and + * {@linkcode https://deno.land/std/streams/mod.ts?s=toArrayBuffer|toArrayBuffer} + * instead. + * + * **It is not guaranteed that the full buffer will be read in a single + * call.** + * + * ```ts + * // if "/foo/bar.txt" contains the text "hello world": + * const file = Deno.openSync("/foo/bar.txt"); + * const buf = new Uint8Array(100); + * const numberOfBytesRead = Deno.readSync(file.rid, buf); // 11 bytes + * const text = new TextDecoder().decode(buf); // "hello world" + * Deno.close(file.rid); + * ``` + * + * @category I/O + */ + export function readSync(rid: number, buffer: Uint8Array): number | null; + + /** Write to the resource ID (`rid`) the contents of the array buffer (`data`). + * + * Resolves to the number of bytes written. This function is one of the lowest + * level APIs and most users should not work with this directly, but rather + * use {@linkcode WritableStream}, {@linkcode ReadableStream.from} and + * {@linkcode ReadableStream.pipeTo}. + * + * **It is not guaranteed that the full buffer will be written in a single + * call.** + * + * ```ts + * const encoder = new TextEncoder(); + * const data = encoder.encode("Hello world"); + * const file = await Deno.open("/foo/bar.txt", { write: true }); + * const bytesWritten = await Deno.write(file.rid, data); // 11 + * Deno.close(file.rid); + * ``` + * + * @category I/O + */ + export function write(rid: number, data: Uint8Array): Promise; + + /** Synchronously write to the resource ID (`rid`) the contents of the array + * buffer (`data`). + * + * Returns the number of bytes written. This function is one of the lowest + * level APIs and most users should not work with this directly, but rather + * use {@linkcode WritableStream}, {@linkcode ReadableStream.from} and + * {@linkcode ReadableStream.pipeTo}. + * + * **It is not guaranteed that the full buffer will be written in a single + * call.** + * + * ```ts + * const encoder = new TextEncoder(); + * const data = encoder.encode("Hello world"); + * const file = Deno.openSync("/foo/bar.txt", { write: true }); + * const bytesWritten = Deno.writeSync(file.rid, data); // 11 + * Deno.close(file.rid); + * ``` + * + * @category I/O + */ + export function writeSync(rid: number, data: Uint8Array): number; + + /** Seek a resource ID (`rid`) to the given `offset` under mode given by `whence`. + * The call resolves to the new position within the resource (bytes from the start). + * + * ```ts + * // Given file.rid pointing to file with "Hello world", which is 11 bytes long: + * const file = await Deno.open( + * "hello.txt", + * { read: true, write: true, truncate: true, create: true }, + * ); + * await Deno.write(file.rid, new TextEncoder().encode("Hello world")); + * + * // advance cursor 6 bytes + * const cursorPosition = await Deno.seek(file.rid, 6, Deno.SeekMode.Start); + * console.log(cursorPosition); // 6 + * const buf = new Uint8Array(100); + * await file.read(buf); + * console.log(new TextDecoder().decode(buf)); // "world" + * file.close(); + * ``` + * + * The seek modes work as follows: + * + * ```ts + * // Given file.rid pointing to file with "Hello world", which is 11 bytes long: + * const file = await Deno.open( + * "hello.txt", + * { read: true, write: true, truncate: true, create: true }, + * ); + * await Deno.write(file.rid, new TextEncoder().encode("Hello world")); + * + * // Seek 6 bytes from the start of the file + * console.log(await Deno.seek(file.rid, 6, Deno.SeekMode.Start)); // "6" + * // Seek 2 more bytes from the current position + * console.log(await Deno.seek(file.rid, 2, Deno.SeekMode.Current)); // "8" + * // Seek backwards 2 bytes from the end of the file + * console.log(await Deno.seek(file.rid, -2, Deno.SeekMode.End)); // "9" (i.e. 11-2) + * file.close(); + * ``` + * + * @category I/O + */ + export function seek( + rid: number, + offset: number | bigint, + whence: SeekMode, + ): Promise; + + /** Synchronously seek a resource ID (`rid`) to the given `offset` under mode + * given by `whence`. The new position within the resource (bytes from the + * start) is returned. + * + * ```ts + * const file = Deno.openSync( + * "hello.txt", + * { read: true, write: true, truncate: true, create: true }, + * ); + * Deno.writeSync(file.rid, new TextEncoder().encode("Hello world")); + * + * // advance cursor 6 bytes + * const cursorPosition = Deno.seekSync(file.rid, 6, Deno.SeekMode.Start); + * console.log(cursorPosition); // 6 + * const buf = new Uint8Array(100); + * file.readSync(buf); + * console.log(new TextDecoder().decode(buf)); // "world" + * file.close(); + * ``` + * + * The seek modes work as follows: + * + * ```ts + * // Given file.rid pointing to file with "Hello world", which is 11 bytes long: + * const file = Deno.openSync( + * "hello.txt", + * { read: true, write: true, truncate: true, create: true }, + * ); + * Deno.writeSync(file.rid, new TextEncoder().encode("Hello world")); + * + * // Seek 6 bytes from the start of the file + * console.log(Deno.seekSync(file.rid, 6, Deno.SeekMode.Start)); // "6" + * // Seek 2 more bytes from the current position + * console.log(Deno.seekSync(file.rid, 2, Deno.SeekMode.Current)); // "8" + * // Seek backwards 2 bytes from the end of the file + * console.log(Deno.seekSync(file.rid, -2, Deno.SeekMode.End)); // "9" (i.e. 11-2) + * file.close(); + * ``` + * + * @category I/O + */ + export function seekSync( + rid: number, + offset: number | bigint, + whence: SeekMode, + ): number; + + /** + * Flushes any pending data and metadata operations of the given file stream + * to disk. + * + * ```ts + * const file = await Deno.open( + * "my_file.txt", + * { read: true, write: true, create: true }, + * ); + * await Deno.write(file.rid, new TextEncoder().encode("Hello World")); + * await Deno.ftruncate(file.rid, 1); + * await Deno.fsync(file.rid); + * console.log(new TextDecoder().decode(await Deno.readFile("my_file.txt"))); // H + * ``` + * + * @category I/O + */ + export function fsync(rid: number): Promise; + + /** + * Synchronously flushes any pending data and metadata operations of the given + * file stream to disk. + * + * ```ts + * const file = Deno.openSync( + * "my_file.txt", + * { read: true, write: true, create: true }, + * ); + * Deno.writeSync(file.rid, new TextEncoder().encode("Hello World")); + * Deno.ftruncateSync(file.rid, 1); + * Deno.fsyncSync(file.rid); + * console.log(new TextDecoder().decode(Deno.readFileSync("my_file.txt"))); // H + * ``` + * + * @category I/O + */ + export function fsyncSync(rid: number): void; + + /** + * Flushes any pending data operations of the given file stream to disk. + * ```ts + * const file = await Deno.open( + * "my_file.txt", + * { read: true, write: true, create: true }, + * ); + * await Deno.write(file.rid, new TextEncoder().encode("Hello World")); + * await Deno.fdatasync(file.rid); + * console.log(new TextDecoder().decode(await Deno.readFile("my_file.txt"))); // Hello World + * ``` + * + * @category I/O + */ + export function fdatasync(rid: number): Promise; + + /** + * Synchronously flushes any pending data operations of the given file stream + * to disk. + * + * ```ts + * const file = Deno.openSync( + * "my_file.txt", + * { read: true, write: true, create: true }, + * ); + * Deno.writeSync(file.rid, new TextEncoder().encode("Hello World")); + * Deno.fdatasyncSync(file.rid); + * console.log(new TextDecoder().decode(Deno.readFileSync("my_file.txt"))); // Hello World + * ``` + * + * @category I/O + */ + export function fdatasyncSync(rid: number): void; + + /** Close the given resource ID (`rid`) which has been previously opened, such + * as via opening or creating a file. Closing a file when you are finished + * with it is important to avoid leaking resources. + * + * ```ts + * const file = await Deno.open("my_file.txt"); + * // do work with "file" object + * Deno.close(file.rid); + * ``` + * + * @category I/O + */ + export function close(rid: number): void; + + /** The Deno abstraction for reading and writing files. + * + * This is the most straight forward way of handling files within Deno and is + * recommended over using the discreet functions within the `Deno` namespace. + * + * ```ts + * const file = await Deno.open("/foo/bar.txt", { read: true }); + * const fileInfo = await file.stat(); + * if (fileInfo.isFile) { + * const buf = new Uint8Array(100); + * const numberOfBytesRead = await file.read(buf); // 11 bytes + * const text = new TextDecoder().decode(buf); // "hello world" + * } + * file.close(); + * ``` + * + * @category File System + */ + export class FsFile + implements + Reader, + ReaderSync, + Writer, + WriterSync, + Seeker, + SeekerSync, + Closer, + Disposable { + /** The resource ID associated with the file instance. The resource ID + * should be considered an opaque reference to resource. */ + readonly rid: number; + /** A {@linkcode ReadableStream} instance representing to the byte contents + * of the file. This makes it easy to interoperate with other web streams + * based APIs. + * + * ```ts + * const file = await Deno.open("my_file.txt", { read: true }); + * const decoder = new TextDecoder(); + * for await (const chunk of file.readable) { + * console.log(decoder.decode(chunk)); + * } + * ``` + */ + readonly readable: ReadableStream; + /** A {@linkcode WritableStream} instance to write the contents of the + * file. This makes it easy to interoperate with other web streams based + * APIs. + * + * ```ts + * const items = ["hello", "world"]; + * const file = await Deno.open("my_file.txt", { write: true }); + * const encoder = new TextEncoder(); + * const writer = file.writable.getWriter(); + * for (const item of items) { + * await writer.write(encoder.encode(item)); + * } + * file.close(); + * ``` + */ + readonly writable: WritableStream; + /** The constructor which takes a resource ID. Generally `FsFile` should + * not be constructed directly. Instead use {@linkcode Deno.open} or + * {@linkcode Deno.openSync} to create a new instance of `FsFile`. */ + constructor(rid: number); + /** Write the contents of the array buffer (`p`) to the file. + * + * Resolves to the number of bytes written. + * + * **It is not guaranteed that the full buffer will be written in a single + * call.** + * + * ```ts + * const encoder = new TextEncoder(); + * const data = encoder.encode("Hello world"); + * const file = await Deno.open("/foo/bar.txt", { write: true }); + * const bytesWritten = await file.write(data); // 11 + * file.close(); + * ``` + * + * @category I/O + */ + write(p: Uint8Array): Promise; + /** Synchronously write the contents of the array buffer (`p`) to the file. + * + * Returns the number of bytes written. + * + * **It is not guaranteed that the full buffer will be written in a single + * call.** + * + * ```ts + * const encoder = new TextEncoder(); + * const data = encoder.encode("Hello world"); + * const file = Deno.openSync("/foo/bar.txt", { write: true }); + * const bytesWritten = file.writeSync(data); // 11 + * file.close(); + * ``` + */ + writeSync(p: Uint8Array): number; + /** Truncates (or extends) the file to reach the specified `len`. If `len` + * is not specified, then the entire file contents are truncated. + * + * ### Truncate the entire file + * + * ```ts + * const file = await Deno.open("my_file.txt", { write: true }); + * await file.truncate(); + * file.close(); + * ``` + * + * ### Truncate part of the file + * + * ```ts + * // if "my_file.txt" contains the text "hello world": + * const file = await Deno.open("my_file.txt", { write: true }); + * await file.truncate(7); + * const buf = new Uint8Array(100); + * await file.read(buf); + * const text = new TextDecoder().decode(buf); // "hello w" + * file.close(); + * ``` + */ + truncate(len?: number): Promise; + /** Synchronously truncates (or extends) the file to reach the specified + * `len`. If `len` is not specified, then the entire file contents are + * truncated. + * + * ### Truncate the entire file + * + * ```ts + * const file = Deno.openSync("my_file.txt", { write: true }); + * file.truncateSync(); + * file.close(); + * ``` + * + * ### Truncate part of the file + * + * ```ts + * // if "my_file.txt" contains the text "hello world": + * const file = Deno.openSync("my_file.txt", { write: true }); + * file.truncateSync(7); + * const buf = new Uint8Array(100); + * file.readSync(buf); + * const text = new TextDecoder().decode(buf); // "hello w" + * file.close(); + * ``` + */ + truncateSync(len?: number): void; + /** Read the file into an array buffer (`p`). + * + * Resolves to either the number of bytes read during the operation or EOF + * (`null`) if there was nothing more to read. + * + * It is possible for a read to successfully return with `0` bytes. This + * does not indicate EOF. + * + * **It is not guaranteed that the full buffer will be read in a single + * call.** + * + * ```ts + * // if "/foo/bar.txt" contains the text "hello world": + * const file = await Deno.open("/foo/bar.txt"); + * const buf = new Uint8Array(100); + * const numberOfBytesRead = await file.read(buf); // 11 bytes + * const text = new TextDecoder().decode(buf); // "hello world" + * file.close(); + * ``` + */ + read(p: Uint8Array): Promise; + /** Synchronously read from the file into an array buffer (`p`). + * + * Returns either the number of bytes read during the operation or EOF + * (`null`) if there was nothing more to read. + * + * It is possible for a read to successfully return with `0` bytes. This + * does not indicate EOF. + * + * **It is not guaranteed that the full buffer will be read in a single + * call.** + * + * ```ts + * // if "/foo/bar.txt" contains the text "hello world": + * const file = Deno.openSync("/foo/bar.txt"); + * const buf = new Uint8Array(100); + * const numberOfBytesRead = file.readSync(buf); // 11 bytes + * const text = new TextDecoder().decode(buf); // "hello world" + * file.close(); + * ``` + */ + readSync(p: Uint8Array): number | null; + /** Seek to the given `offset` under mode given by `whence`. The call + * resolves to the new position within the resource (bytes from the start). + * + * ```ts + * // Given file pointing to file with "Hello world", which is 11 bytes long: + * const file = await Deno.open( + * "hello.txt", + * { read: true, write: true, truncate: true, create: true }, + * ); + * await file.write(new TextEncoder().encode("Hello world")); + * + * // advance cursor 6 bytes + * const cursorPosition = await file.seek(6, Deno.SeekMode.Start); + * console.log(cursorPosition); // 6 + * const buf = new Uint8Array(100); + * await file.read(buf); + * console.log(new TextDecoder().decode(buf)); // "world" + * file.close(); + * ``` + * + * The seek modes work as follows: + * + * ```ts + * // Given file.rid pointing to file with "Hello world", which is 11 bytes long: + * const file = await Deno.open( + * "hello.txt", + * { read: true, write: true, truncate: true, create: true }, + * ); + * await file.write(new TextEncoder().encode("Hello world")); + * + * // Seek 6 bytes from the start of the file + * console.log(await file.seek(6, Deno.SeekMode.Start)); // "6" + * // Seek 2 more bytes from the current position + * console.log(await file.seek(2, Deno.SeekMode.Current)); // "8" + * // Seek backwards 2 bytes from the end of the file + * console.log(await file.seek(-2, Deno.SeekMode.End)); // "9" (i.e. 11-2) + * ``` + */ + seek(offset: number | bigint, whence: SeekMode): Promise; + /** Synchronously seek to the given `offset` under mode given by `whence`. + * The new position within the resource (bytes from the start) is returned. + * + * ```ts + * const file = Deno.openSync( + * "hello.txt", + * { read: true, write: true, truncate: true, create: true }, + * ); + * file.writeSync(new TextEncoder().encode("Hello world")); + * + * // advance cursor 6 bytes + * const cursorPosition = file.seekSync(6, Deno.SeekMode.Start); + * console.log(cursorPosition); // 6 + * const buf = new Uint8Array(100); + * file.readSync(buf); + * console.log(new TextDecoder().decode(buf)); // "world" + * file.close(); + * ``` + * + * The seek modes work as follows: + * + * ```ts + * // Given file.rid pointing to file with "Hello world", which is 11 bytes long: + * const file = Deno.openSync( + * "hello.txt", + * { read: true, write: true, truncate: true, create: true }, + * ); + * file.writeSync(new TextEncoder().encode("Hello world")); + * + * // Seek 6 bytes from the start of the file + * console.log(file.seekSync(6, Deno.SeekMode.Start)); // "6" + * // Seek 2 more bytes from the current position + * console.log(file.seekSync(2, Deno.SeekMode.Current)); // "8" + * // Seek backwards 2 bytes from the end of the file + * console.log(file.seekSync(-2, Deno.SeekMode.End)); // "9" (i.e. 11-2) + * file.close(); + * ``` + */ + seekSync(offset: number | bigint, whence: SeekMode): number; + /** Resolves to a {@linkcode Deno.FileInfo} for the file. + * + * ```ts + * import { assert } from "https://deno.land/std/assert/mod.ts"; + * + * const file = await Deno.open("hello.txt"); + * const fileInfo = await file.stat(); + * assert(fileInfo.isFile); + * file.close(); + * ``` + */ + stat(): Promise; + /** Synchronously returns a {@linkcode Deno.FileInfo} for the file. + * + * ```ts + * import { assert } from "https://deno.land/std/assert/mod.ts"; + * + * const file = Deno.openSync("hello.txt") + * const fileInfo = file.statSync(); + * assert(fileInfo.isFile); + * file.close(); + * ``` + */ + statSync(): FileInfo; + /** Close the file. Closing a file when you are finished with it is + * important to avoid leaking resources. + * + * ```ts + * const file = await Deno.open("my_file.txt"); + * // do work with "file" object + * file.close(); + * ``` + */ + close(): void; + + [Symbol.dispose](): void; + } + + /** + * The Deno abstraction for reading and writing files. + * + * @deprecated Use {@linkcode Deno.FsFile} instead. {@linkcode Deno.File} + * will be removed in the future. + * + * @category File System + */ + export const File: typeof FsFile; + + /** Gets the size of the console as columns/rows. + * + * ```ts + * const { columns, rows } = Deno.consoleSize(); + * ``` + * + * This returns the size of the console window as reported by the operating + * system. It's not a reflection of how many characters will fit within the + * console window, but can be used as part of that calculation. + * + * @category I/O + */ + export function consoleSize(): { + columns: number; + rows: number; + }; + + /** @category I/O */ + export interface SetRawOptions { + /** + * The `cbreak` option can be used to indicate that characters that + * correspond to a signal should still be generated. When disabling raw + * mode, this option is ignored. This functionality currently only works on + * Linux and Mac OS. + */ + cbreak: boolean; + } + + /** A reference to `stdin` which can be used to read directly from `stdin`. + * It implements the Deno specific {@linkcode Reader}, {@linkcode ReaderSync}, + * and {@linkcode Closer} interfaces as well as provides a + * {@linkcode ReadableStream} interface. + * + * ### Reading chunks from the readable stream + * + * ```ts + * const decoder = new TextDecoder(); + * for await (const chunk of Deno.stdin.readable) { + * const text = decoder.decode(chunk); + * // do something with the text + * } + * ``` + * + * @category I/O + */ + export const stdin: Reader & ReaderSync & Closer & { + /** The resource ID assigned to `stdin`. This can be used with the discreet + * I/O functions in the `Deno` namespace. */ + readonly rid: number; + /** A readable stream interface to `stdin`. */ + readonly readable: ReadableStream; + /** + * Set TTY to be under raw mode or not. In raw mode, characters are read and + * returned as is, without being processed. All special processing of + * characters by the terminal is disabled, including echoing input + * characters. Reading from a TTY device in raw mode is faster than reading + * from a TTY device in canonical mode. + * + * ```ts + * Deno.stdin.setRaw(true, { cbreak: true }); + * ``` + * + * @category I/O + */ + setRaw(mode: boolean, options?: SetRawOptions): void; + }; + /** A reference to `stdout` which can be used to write directly to `stdout`. + * It implements the Deno specific {@linkcode Writer}, {@linkcode WriterSync}, + * and {@linkcode Closer} interfaces as well as provides a + * {@linkcode WritableStream} interface. + * + * These are low level constructs, and the {@linkcode console} interface is a + * more straight forward way to interact with `stdout` and `stderr`. + * + * @category I/O + */ + export const stdout: Writer & WriterSync & Closer & { + /** The resource ID assigned to `stdout`. This can be used with the discreet + * I/O functions in the `Deno` namespace. */ + readonly rid: number; + /** A writable stream interface to `stdout`. */ + readonly writable: WritableStream; + }; + /** A reference to `stderr` which can be used to write directly to `stderr`. + * It implements the Deno specific {@linkcode Writer}, {@linkcode WriterSync}, + * and {@linkcode Closer} interfaces as well as provides a + * {@linkcode WritableStream} interface. + * + * These are low level constructs, and the {@linkcode console} interface is a + * more straight forward way to interact with `stdout` and `stderr`. + * + * @category I/O + */ + export const stderr: Writer & WriterSync & Closer & { + /** The resource ID assigned to `stderr`. This can be used with the discreet + * I/O functions in the `Deno` namespace. */ + readonly rid: number; + /** A writable stream interface to `stderr`. */ + readonly writable: WritableStream; + }; + + /** + * Options which can be set when doing {@linkcode Deno.open} and + * {@linkcode Deno.openSync}. + * + * @category File System */ + export interface OpenOptions { + /** Sets the option for read access. This option, when `true`, means that + * the file should be read-able if opened. + * + * @default {true} */ + read?: boolean; + /** Sets the option for write access. This option, when `true`, means that + * the file should be write-able if opened. If the file already exists, + * any write calls on it will overwrite its contents, by default without + * truncating it. + * + * @default {false} */ + write?: boolean; + /** Sets the option for the append mode. This option, when `true`, means + * that writes will append to a file instead of overwriting previous + * contents. + * + * Note that setting `{ write: true, append: true }` has the same effect as + * setting only `{ append: true }`. + * + * @default {false} */ + append?: boolean; + /** Sets the option for truncating a previous file. If a file is + * successfully opened with this option set it will truncate the file to `0` + * size if it already exists. The file must be opened with write access + * for truncate to work. + * + * @default {false} */ + truncate?: boolean; + /** Sets the option to allow creating a new file, if one doesn't already + * exist at the specified path. Requires write or append access to be + * used. + * + * @default {false} */ + create?: boolean; + /** If set to `true`, no file, directory, or symlink is allowed to exist at + * the target location. Requires write or append access to be used. When + * createNew is set to `true`, create and truncate are ignored. + * + * @default {false} */ + createNew?: boolean; + /** Permissions to use if creating the file (defaults to `0o666`, before + * the process's umask). + * + * Ignored on Windows. */ + mode?: number; + } + + /** + * Options which can be set when using {@linkcode Deno.readFile} or + * {@linkcode Deno.readFileSync}. + * + * @category File System */ + export interface ReadFileOptions { + /** + * An abort signal to allow cancellation of the file read operation. + * If the signal becomes aborted the readFile operation will be stopped + * and the promise returned will be rejected with an AbortError. + */ + signal?: AbortSignal; + } + + /** + * Check if a given resource id (`rid`) is a TTY (a terminal). + * + * ```ts + * // This example is system and context specific + * const nonTTYRid = Deno.openSync("my_file.txt").rid; + * const ttyRid = Deno.openSync("/dev/tty6").rid; + * console.log(Deno.isatty(nonTTYRid)); // false + * console.log(Deno.isatty(ttyRid)); // true + * Deno.close(nonTTYRid); + * Deno.close(ttyRid); + * ``` + * + * @category I/O + */ + export function isatty(rid: number): boolean; + + /** + * A variable-sized buffer of bytes with `read()` and `write()` methods. + * + * @deprecated Use the + * [Web Streams API]{@link https://developer.mozilla.org/en-US/docs/Web/API/Streams_API} + * instead. {@linkcode Deno.Buffer} will be removed in the future. + * + * @category I/O + */ + export class Buffer implements Reader, ReaderSync, Writer, WriterSync { + constructor(ab?: ArrayBuffer); + /** Returns a slice holding the unread portion of the buffer. + * + * The slice is valid for use only until the next buffer modification (that + * is, only until the next call to a method like `read()`, `write()`, + * `reset()`, or `truncate()`). If `options.copy` is false the slice aliases the buffer content at + * least until the next buffer modification, so immediate changes to the + * slice will affect the result of future reads. + * @param options Defaults to `{ copy: true }` + */ + bytes(options?: { copy?: boolean }): Uint8Array; + /** Returns whether the unread portion of the buffer is empty. */ + empty(): boolean; + /** A read only number of bytes of the unread portion of the buffer. */ + readonly length: number; + /** The read only capacity of the buffer's underlying byte slice, that is, + * the total space allocated for the buffer's data. */ + readonly capacity: number; + /** Discards all but the first `n` unread bytes from the buffer but + * continues to use the same allocated storage. It throws if `n` is + * negative or greater than the length of the buffer. */ + truncate(n: number): void; + /** Resets the buffer to be empty, but it retains the underlying storage for + * use by future writes. `.reset()` is the same as `.truncate(0)`. */ + reset(): void; + /** Reads the next `p.length` bytes from the buffer or until the buffer is + * drained. Returns the number of bytes read. If the buffer has no data to + * return, the return is EOF (`null`). */ + readSync(p: Uint8Array): number | null; + /** Reads the next `p.length` bytes from the buffer or until the buffer is + * drained. Resolves to the number of bytes read. If the buffer has no + * data to return, resolves to EOF (`null`). + * + * NOTE: This methods reads bytes synchronously; it's provided for + * compatibility with `Reader` interfaces. + */ + read(p: Uint8Array): Promise; + writeSync(p: Uint8Array): number; + /** NOTE: This methods writes bytes synchronously; it's provided for + * compatibility with `Writer` interface. */ + write(p: Uint8Array): Promise; + /** Grows the buffer's capacity, if necessary, to guarantee space for + * another `n` bytes. After `.grow(n)`, at least `n` bytes can be written to + * the buffer without another allocation. If `n` is negative, `.grow()` will + * throw. If the buffer can't grow it will throw an error. + * + * Based on Go Lang's + * [Buffer.Grow](https://golang.org/pkg/bytes/#Buffer.Grow). */ + grow(n: number): void; + /** Reads data from `r` until EOF (`null`) and appends it to the buffer, + * growing the buffer as needed. It resolves to the number of bytes read. + * If the buffer becomes too large, `.readFrom()` will reject with an error. + * + * Based on Go Lang's + * [Buffer.ReadFrom](https://golang.org/pkg/bytes/#Buffer.ReadFrom). */ + readFrom(r: Reader): Promise; + /** Reads data from `r` until EOF (`null`) and appends it to the buffer, + * growing the buffer as needed. It returns the number of bytes read. If the + * buffer becomes too large, `.readFromSync()` will throw an error. + * + * Based on Go Lang's + * [Buffer.ReadFrom](https://golang.org/pkg/bytes/#Buffer.ReadFrom). */ + readFromSync(r: ReaderSync): number; + } + + /** + * Read Reader `r` until EOF (`null`) and resolve to the content as + * Uint8Array`. + * + * @deprecated Use {@linkcode ReadableStream} and + * [`toArrayBuffer()`](https://deno.land/std/streams/to_array_buffer.ts?s=toArrayBuffer) + * instead. {@linkcode Deno.readAll} will be removed in the future. + * + * @category I/O + */ + export function readAll(r: Reader): Promise; + + /** + * Synchronously reads Reader `r` until EOF (`null`) and returns the content + * as `Uint8Array`. + * + * @deprecated Use {@linkcode ReadableStream} and + * [`toArrayBuffer()`](https://deno.land/std/streams/to_array_buffer.ts?s=toArrayBuffer) + * instead. {@linkcode Deno.readAllSync} will be removed in the future. + * + * @category I/O + */ + export function readAllSync(r: ReaderSync): Uint8Array; + + /** + * Write all the content of the array buffer (`arr`) to the writer (`w`). + * + * @deprecated Use {@linkcode WritableStream}, {@linkcode ReadableStream.from} + * and {@linkcode ReadableStream.pipeTo} instead. {@linkcode Deno.writeAll} + * will be removed in the future. + * + * @category I/O + */ + export function writeAll(w: Writer, arr: Uint8Array): Promise; + + /** + * Synchronously write all the content of the array buffer (`arr`) to the + * writer (`w`). + * + * @deprecated Use {@linkcode WritableStream}, {@linkcode ReadableStream.from} + * and {@linkcode ReadableStream.pipeTo} instead. + * {@linkcode Deno.writeAllSync} will be removed in the future. + * + * @category I/O + */ + export function writeAllSync(w: WriterSync, arr: Uint8Array): void; + + /** + * Options which can be set when using {@linkcode Deno.mkdir} and + * {@linkcode Deno.mkdirSync}. + * + * @category File System */ + export interface MkdirOptions { + /** If set to `true`, means that any intermediate directories will also be + * created (as with the shell command `mkdir -p`). + * + * Intermediate directories are created with the same permissions. + * + * When recursive is set to `true`, succeeds silently (without changing any + * permissions) if a directory already exists at the path, or if the path + * is a symlink to an existing directory. + * + * @default {false} */ + recursive?: boolean; + /** Permissions to use when creating the directory (defaults to `0o777`, + * before the process's umask). + * + * Ignored on Windows. */ + mode?: number; + } + + /** Creates a new directory with the specified path. + * + * ```ts + * await Deno.mkdir("new_dir"); + * await Deno.mkdir("nested/directories", { recursive: true }); + * await Deno.mkdir("restricted_access_dir", { mode: 0o700 }); + * ``` + * + * Defaults to throwing error if the directory already exists. + * + * Requires `allow-write` permission. + * + * @tags allow-write + * @category File System + */ + export function mkdir( + path: string | URL, + options?: MkdirOptions, + ): Promise; + + /** Synchronously creates a new directory with the specified path. + * + * ```ts + * Deno.mkdirSync("new_dir"); + * Deno.mkdirSync("nested/directories", { recursive: true }); + * Deno.mkdirSync("restricted_access_dir", { mode: 0o700 }); + * ``` + * + * Defaults to throwing error if the directory already exists. + * + * Requires `allow-write` permission. + * + * @tags allow-write + * @category File System + */ + export function mkdirSync(path: string | URL, options?: MkdirOptions): void; + + /** + * Options which can be set when using {@linkcode Deno.makeTempDir}, + * {@linkcode Deno.makeTempDirSync}, {@linkcode Deno.makeTempFile}, and + * {@linkcode Deno.makeTempFileSync}. + * + * @category File System */ + export interface MakeTempOptions { + /** Directory where the temporary directory should be created (defaults to + * the env variable `TMPDIR`, or the system's default, usually `/tmp`). + * + * Note that if the passed `dir` is relative, the path returned by + * `makeTempFile()` and `makeTempDir()` will also be relative. Be mindful of + * this when changing working directory. */ + dir?: string; + /** String that should precede the random portion of the temporary + * directory's name. */ + prefix?: string; + /** String that should follow the random portion of the temporary + * directory's name. */ + suffix?: string; + } + + /** Creates a new temporary directory in the default directory for temporary + * files, unless `dir` is specified. Other optional options include + * prefixing and suffixing the directory name with `prefix` and `suffix` + * respectively. + * + * This call resolves to the full path to the newly created directory. + * + * Multiple programs calling this function simultaneously will create different + * directories. It is the caller's responsibility to remove the directory when + * no longer needed. + * + * ```ts + * const tempDirName0 = await Deno.makeTempDir(); // e.g. /tmp/2894ea76 + * const tempDirName1 = await Deno.makeTempDir({ prefix: 'my_temp' }); // e.g. /tmp/my_temp339c944d + * ``` + * + * Requires `allow-write` permission. + * + * @tags allow-write + * @category File System + */ + // TODO(ry) Doesn't check permissions. + export function makeTempDir(options?: MakeTempOptions): Promise; + + /** Synchronously creates a new temporary directory in the default directory + * for temporary files, unless `dir` is specified. Other optional options + * include prefixing and suffixing the directory name with `prefix` and + * `suffix` respectively. + * + * The full path to the newly created directory is returned. + * + * Multiple programs calling this function simultaneously will create different + * directories. It is the caller's responsibility to remove the directory when + * no longer needed. + * + * ```ts + * const tempDirName0 = Deno.makeTempDirSync(); // e.g. /tmp/2894ea76 + * const tempDirName1 = Deno.makeTempDirSync({ prefix: 'my_temp' }); // e.g. /tmp/my_temp339c944d + * ``` + * + * Requires `allow-write` permission. + * + * @tags allow-write + * @category File System + */ + // TODO(ry) Doesn't check permissions. + export function makeTempDirSync(options?: MakeTempOptions): string; + + /** Creates a new temporary file in the default directory for temporary + * files, unless `dir` is specified. + * + * Other options include prefixing and suffixing the directory name with + * `prefix` and `suffix` respectively. + * + * This call resolves to the full path to the newly created file. + * + * Multiple programs calling this function simultaneously will create + * different files. It is the caller's responsibility to remove the file when + * no longer needed. + * + * ```ts + * const tmpFileName0 = await Deno.makeTempFile(); // e.g. /tmp/419e0bf2 + * const tmpFileName1 = await Deno.makeTempFile({ prefix: 'my_temp' }); // e.g. /tmp/my_temp754d3098 + * ``` + * + * Requires `allow-write` permission. + * + * @tags allow-write + * @category File System + */ + export function makeTempFile(options?: MakeTempOptions): Promise; + + /** Synchronously creates a new temporary file in the default directory for + * temporary files, unless `dir` is specified. + * + * Other options include prefixing and suffixing the directory name with + * `prefix` and `suffix` respectively. + * + * The full path to the newly created file is returned. + * + * Multiple programs calling this function simultaneously will create + * different files. It is the caller's responsibility to remove the file when + * no longer needed. + * + * ```ts + * const tempFileName0 = Deno.makeTempFileSync(); // e.g. /tmp/419e0bf2 + * const tempFileName1 = Deno.makeTempFileSync({ prefix: 'my_temp' }); // e.g. /tmp/my_temp754d3098 + * ``` + * + * Requires `allow-write` permission. + * + * @tags allow-write + * @category File System + */ + export function makeTempFileSync(options?: MakeTempOptions): string; + + /** Changes the permission of a specific file/directory of specified path. + * Ignores the process's umask. + * + * ```ts + * await Deno.chmod("/path/to/file", 0o666); + * ``` + * + * The mode is a sequence of 3 octal numbers. The first/left-most number + * specifies the permissions for the owner. The second number specifies the + * permissions for the group. The last/right-most number specifies the + * permissions for others. For example, with a mode of 0o764, the owner (7) + * can read/write/execute, the group (6) can read/write and everyone else (4) + * can read only. + * + * | Number | Description | + * | ------ | ----------- | + * | 7 | read, write, and execute | + * | 6 | read and write | + * | 5 | read and execute | + * | 4 | read only | + * | 3 | write and execute | + * | 2 | write only | + * | 1 | execute only | + * | 0 | no permission | + * + * NOTE: This API currently throws on Windows + * + * Requires `allow-write` permission. + * + * @tags allow-write + * @category File System + */ + export function chmod(path: string | URL, mode: number): Promise; + + /** Synchronously changes the permission of a specific file/directory of + * specified path. Ignores the process's umask. + * + * ```ts + * Deno.chmodSync("/path/to/file", 0o666); + * ``` + * + * For a full description, see {@linkcode Deno.chmod}. + * + * NOTE: This API currently throws on Windows + * + * Requires `allow-write` permission. + * + * @tags allow-write + * @category File System + */ + export function chmodSync(path: string | URL, mode: number): void; + + /** Change owner of a regular file or directory. + * + * This functionality is not available on Windows. + * + * ```ts + * await Deno.chown("myFile.txt", 1000, 1002); + * ``` + * + * Requires `allow-write` permission. + * + * Throws Error (not implemented) if executed on Windows. + * + * @tags allow-write + * @category File System + * + * @param path path to the file + * @param uid user id (UID) of the new owner, or `null` for no change + * @param gid group id (GID) of the new owner, or `null` for no change + */ + export function chown( + path: string | URL, + uid: number | null, + gid: number | null, + ): Promise; + + /** Synchronously change owner of a regular file or directory. + * + * This functionality is not available on Windows. + * + * ```ts + * Deno.chownSync("myFile.txt", 1000, 1002); + * ``` + * + * Requires `allow-write` permission. + * + * Throws Error (not implemented) if executed on Windows. + * + * @tags allow-write + * @category File System + * + * @param path path to the file + * @param uid user id (UID) of the new owner, or `null` for no change + * @param gid group id (GID) of the new owner, or `null` for no change + */ + export function chownSync( + path: string | URL, + uid: number | null, + gid: number | null, + ): void; + + /** + * Options which can be set when using {@linkcode Deno.remove} and + * {@linkcode Deno.removeSync}. + * + * @category File System */ + export interface RemoveOptions { + /** If set to `true`, path will be removed even if it's a non-empty directory. + * + * @default {false} */ + recursive?: boolean; + } + + /** Removes the named file or directory. + * + * ```ts + * await Deno.remove("/path/to/empty_dir/or/file"); + * await Deno.remove("/path/to/populated_dir/or/file", { recursive: true }); + * ``` + * + * Throws error if permission denied, path not found, or path is a non-empty + * directory and the `recursive` option isn't set to `true`. + * + * Requires `allow-write` permission. + * + * @tags allow-write + * @category File System + */ + export function remove( + path: string | URL, + options?: RemoveOptions, + ): Promise; + + /** Synchronously removes the named file or directory. + * + * ```ts + * Deno.removeSync("/path/to/empty_dir/or/file"); + * Deno.removeSync("/path/to/populated_dir/or/file", { recursive: true }); + * ``` + * + * Throws error if permission denied, path not found, or path is a non-empty + * directory and the `recursive` option isn't set to `true`. + * + * Requires `allow-write` permission. + * + * @tags allow-write + * @category File System + */ + export function removeSync(path: string | URL, options?: RemoveOptions): void; + + /** Synchronously renames (moves) `oldpath` to `newpath`. Paths may be files or + * directories. If `newpath` already exists and is not a directory, + * `renameSync()` replaces it. OS-specific restrictions may apply when + * `oldpath` and `newpath` are in different directories. + * + * ```ts + * Deno.renameSync("old/path", "new/path"); + * ``` + * + * On Unix-like OSes, this operation does not follow symlinks at either path. + * + * It varies between platforms when the operation throws errors, and if so what + * they are. It's always an error to rename anything to a non-empty directory. + * + * Requires `allow-read` and `allow-write` permissions. + * + * @tags allow-read, allow-write + * @category File System + */ + export function renameSync( + oldpath: string | URL, + newpath: string | URL, + ): void; + + /** Renames (moves) `oldpath` to `newpath`. Paths may be files or directories. + * If `newpath` already exists and is not a directory, `rename()` replaces it. + * OS-specific restrictions may apply when `oldpath` and `newpath` are in + * different directories. + * + * ```ts + * await Deno.rename("old/path", "new/path"); + * ``` + * + * On Unix-like OSes, this operation does not follow symlinks at either path. + * + * It varies between platforms when the operation throws errors, and if so + * what they are. It's always an error to rename anything to a non-empty + * directory. + * + * Requires `allow-read` and `allow-write` permissions. + * + * @tags allow-read, allow-write + * @category File System + */ + export function rename( + oldpath: string | URL, + newpath: string | URL, + ): Promise; + + /** Asynchronously reads and returns the entire contents of a file as an UTF-8 + * decoded string. Reading a directory throws an error. + * + * ```ts + * const data = await Deno.readTextFile("hello.txt"); + * console.log(data); + * ``` + * + * Requires `allow-read` permission. + * + * @tags allow-read + * @category File System + */ + export function readTextFile( + path: string | URL, + options?: ReadFileOptions, + ): Promise; + + /** Synchronously reads and returns the entire contents of a file as an UTF-8 + * decoded string. Reading a directory throws an error. + * + * ```ts + * const data = Deno.readTextFileSync("hello.txt"); + * console.log(data); + * ``` + * + * Requires `allow-read` permission. + * + * @tags allow-read + * @category File System + */ + export function readTextFileSync(path: string | URL): string; + + /** Reads and resolves to the entire contents of a file as an array of bytes. + * `TextDecoder` can be used to transform the bytes to string if required. + * Reading a directory returns an empty data array. + * + * ```ts + * const decoder = new TextDecoder("utf-8"); + * const data = await Deno.readFile("hello.txt"); + * console.log(decoder.decode(data)); + * ``` + * + * Requires `allow-read` permission. + * + * @tags allow-read + * @category File System + */ + export function readFile( + path: string | URL, + options?: ReadFileOptions, + ): Promise; + + /** Synchronously reads and returns the entire contents of a file as an array + * of bytes. `TextDecoder` can be used to transform the bytes to string if + * required. Reading a directory returns an empty data array. + * + * ```ts + * const decoder = new TextDecoder("utf-8"); + * const data = Deno.readFileSync("hello.txt"); + * console.log(decoder.decode(data)); + * ``` + * + * Requires `allow-read` permission. + * + * @tags allow-read + * @category File System + */ + export function readFileSync(path: string | URL): Uint8Array; + + /** Provides information about a file and is returned by + * {@linkcode Deno.stat}, {@linkcode Deno.lstat}, {@linkcode Deno.statSync}, + * and {@linkcode Deno.lstatSync} or from calling `stat()` and `statSync()` + * on an {@linkcode Deno.FsFile} instance. + * + * @category File System + */ + export interface FileInfo { + /** True if this is info for a regular file. Mutually exclusive to + * `FileInfo.isDirectory` and `FileInfo.isSymlink`. */ + isFile: boolean; + /** True if this is info for a regular directory. Mutually exclusive to + * `FileInfo.isFile` and `FileInfo.isSymlink`. */ + isDirectory: boolean; + /** True if this is info for a symlink. Mutually exclusive to + * `FileInfo.isFile` and `FileInfo.isDirectory`. */ + isSymlink: boolean; + /** The size of the file, in bytes. */ + size: number; + /** The last modification time of the file. This corresponds to the `mtime` + * field from `stat` on Linux/Mac OS and `ftLastWriteTime` on Windows. This + * may not be available on all platforms. */ + mtime: Date | null; + /** The last access time of the file. This corresponds to the `atime` + * field from `stat` on Unix and `ftLastAccessTime` on Windows. This may not + * be available on all platforms. */ + atime: Date | null; + /** The creation time of the file. This corresponds to the `birthtime` + * field from `stat` on Mac/BSD and `ftCreationTime` on Windows. This may + * not be available on all platforms. */ + birthtime: Date | null; + /** ID of the device containing the file. */ + dev: number; + /** Inode number. + * + * _Linux/Mac OS only._ */ + ino: number | null; + /** The underlying raw `st_mode` bits that contain the standard Unix + * permissions for this file/directory. + * + * _Linux/Mac OS only._ */ + mode: number | null; + /** Number of hard links pointing to this file. + * + * _Linux/Mac OS only._ */ + nlink: number | null; + /** User ID of the owner of this file. + * + * _Linux/Mac OS only._ */ + uid: number | null; + /** Group ID of the owner of this file. + * + * _Linux/Mac OS only._ */ + gid: number | null; + /** Device ID of this file. + * + * _Linux/Mac OS only._ */ + rdev: number | null; + /** Blocksize for filesystem I/O. + * + * _Linux/Mac OS only._ */ + blksize: number | null; + /** Number of blocks allocated to the file, in 512-byte units. + * + * _Linux/Mac OS only._ */ + blocks: number | null; + /** True if this is info for a block device. + * + * _Linux/Mac OS only._ */ + isBlockDevice: boolean | null; + /** True if this is info for a char device. + * + * _Linux/Mac OS only._ */ + isCharDevice: boolean | null; + /** True if this is info for a fifo. + * + * _Linux/Mac OS only._ */ + isFifo: boolean | null; + /** True if this is info for a socket. + * + * _Linux/Mac OS only._ */ + isSocket: boolean | null; + } + + /** Resolves to the absolute normalized path, with symbolic links resolved. + * + * ```ts + * // e.g. given /home/alice/file.txt and current directory /home/alice + * await Deno.symlink("file.txt", "symlink_file.txt"); + * const realPath = await Deno.realPath("./file.txt"); + * const realSymLinkPath = await Deno.realPath("./symlink_file.txt"); + * console.log(realPath); // outputs "/home/alice/file.txt" + * console.log(realSymLinkPath); // outputs "/home/alice/file.txt" + * ``` + * + * Requires `allow-read` permission for the target path. + * + * Also requires `allow-read` permission for the `CWD` if the target path is + * relative. + * + * @tags allow-read + * @category File System + */ + export function realPath(path: string | URL): Promise; + + /** Synchronously returns absolute normalized path, with symbolic links + * resolved. + * + * ```ts + * // e.g. given /home/alice/file.txt and current directory /home/alice + * Deno.symlinkSync("file.txt", "symlink_file.txt"); + * const realPath = Deno.realPathSync("./file.txt"); + * const realSymLinkPath = Deno.realPathSync("./symlink_file.txt"); + * console.log(realPath); // outputs "/home/alice/file.txt" + * console.log(realSymLinkPath); // outputs "/home/alice/file.txt" + * ``` + * + * Requires `allow-read` permission for the target path. + * + * Also requires `allow-read` permission for the `CWD` if the target path is + * relative. + * + * @tags allow-read + * @category File System + */ + export function realPathSync(path: string | URL): string; + + /** + * Information about a directory entry returned from {@linkcode Deno.readDir} + * and {@linkcode Deno.readDirSync}. + * + * @category File System */ + export interface DirEntry { + /** The file name of the entry. It is just the entity name and does not + * include the full path. */ + name: string; + /** True if this is info for a regular file. Mutually exclusive to + * `DirEntry.isDirectory` and `DirEntry.isSymlink`. */ + isFile: boolean; + /** True if this is info for a regular directory. Mutually exclusive to + * `DirEntry.isFile` and `DirEntry.isSymlink`. */ + isDirectory: boolean; + /** True if this is info for a symlink. Mutually exclusive to + * `DirEntry.isFile` and `DirEntry.isDirectory`. */ + isSymlink: boolean; + } + + /** Reads the directory given by `path` and returns an async iterable of + * {@linkcode Deno.DirEntry}. + * + * ```ts + * for await (const dirEntry of Deno.readDir("/")) { + * console.log(dirEntry.name); + * } + * ``` + * + * Throws error if `path` is not a directory. + * + * Requires `allow-read` permission. + * + * @tags allow-read + * @category File System + */ + export function readDir(path: string | URL): AsyncIterable; + + /** Synchronously reads the directory given by `path` and returns an iterable + * of `Deno.DirEntry`. + * + * ```ts + * for (const dirEntry of Deno.readDirSync("/")) { + * console.log(dirEntry.name); + * } + * ``` + * + * Throws error if `path` is not a directory. + * + * Requires `allow-read` permission. + * + * @tags allow-read + * @category File System + */ + export function readDirSync(path: string | URL): Iterable; + + /** Copies the contents and permissions of one file to another specified path, + * by default creating a new file if needed, else overwriting. Fails if target + * path is a directory or is unwritable. + * + * ```ts + * await Deno.copyFile("from.txt", "to.txt"); + * ``` + * + * Requires `allow-read` permission on `fromPath`. + * + * Requires `allow-write` permission on `toPath`. + * + * @tags allow-read, allow-write + * @category File System + */ + export function copyFile( + fromPath: string | URL, + toPath: string | URL, + ): Promise; + + /** Synchronously copies the contents and permissions of one file to another + * specified path, by default creating a new file if needed, else overwriting. + * Fails if target path is a directory or is unwritable. + * + * ```ts + * Deno.copyFileSync("from.txt", "to.txt"); + * ``` + * + * Requires `allow-read` permission on `fromPath`. + * + * Requires `allow-write` permission on `toPath`. + * + * @tags allow-read, allow-write + * @category File System + */ + export function copyFileSync( + fromPath: string | URL, + toPath: string | URL, + ): void; + + /** Resolves to the full path destination of the named symbolic link. + * + * ```ts + * await Deno.symlink("./test.txt", "./test_link.txt"); + * const target = await Deno.readLink("./test_link.txt"); // full path of ./test.txt + * ``` + * + * Throws TypeError if called with a hard link. + * + * Requires `allow-read` permission. + * + * @tags allow-read + * @category File System + */ + export function readLink(path: string | URL): Promise; + + /** Synchronously returns the full path destination of the named symbolic + * link. + * + * ```ts + * Deno.symlinkSync("./test.txt", "./test_link.txt"); + * const target = Deno.readLinkSync("./test_link.txt"); // full path of ./test.txt + * ``` + * + * Throws TypeError if called with a hard link. + * + * Requires `allow-read` permission. + * + * @tags allow-read + * @category File System + */ + export function readLinkSync(path: string | URL): string; + + /** Resolves to a {@linkcode Deno.FileInfo} for the specified `path`. If + * `path` is a symlink, information for the symlink will be returned instead + * of what it points to. + * + * ```ts + * import { assert } from "https://deno.land/std/assert/mod.ts"; + * const fileInfo = await Deno.lstat("hello.txt"); + * assert(fileInfo.isFile); + * ``` + * + * Requires `allow-read` permission. + * + * @tags allow-read + * @category File System + */ + export function lstat(path: string | URL): Promise; + + /** Synchronously returns a {@linkcode Deno.FileInfo} for the specified + * `path`. If `path` is a symlink, information for the symlink will be + * returned instead of what it points to. + * + * ```ts + * import { assert } from "https://deno.land/std/assert/mod.ts"; + * const fileInfo = Deno.lstatSync("hello.txt"); + * assert(fileInfo.isFile); + * ``` + * + * Requires `allow-read` permission. + * + * @tags allow-read + * @category File System + */ + export function lstatSync(path: string | URL): FileInfo; + + /** Resolves to a {@linkcode Deno.FileInfo} for the specified `path`. Will + * always follow symlinks. + * + * ```ts + * import { assert } from "https://deno.land/std/assert/mod.ts"; + * const fileInfo = await Deno.stat("hello.txt"); + * assert(fileInfo.isFile); + * ``` + * + * Requires `allow-read` permission. + * + * @tags allow-read + * @category File System + */ + export function stat(path: string | URL): Promise; + + /** Synchronously returns a {@linkcode Deno.FileInfo} for the specified + * `path`. Will always follow symlinks. + * + * ```ts + * import { assert } from "https://deno.land/std/assert/mod.ts"; + * const fileInfo = Deno.statSync("hello.txt"); + * assert(fileInfo.isFile); + * ``` + * + * Requires `allow-read` permission. + * + * @tags allow-read + * @category File System + */ + export function statSync(path: string | URL): FileInfo; + + /** Options for writing to a file. + * + * @category File System + */ + export interface WriteFileOptions { + /** If set to `true`, will append to a file instead of overwriting previous + * contents. + * + * @default {false} */ + append?: boolean; + /** Sets the option to allow creating a new file, if one doesn't already + * exist at the specified path. + * + * @default {true} */ + create?: boolean; + /** If set to `true`, no file, directory, or symlink is allowed to exist at + * the target location. When createNew is set to `true`, `create` is ignored. + * + * @default {false} */ + createNew?: boolean; + /** Permissions always applied to file. */ + mode?: number; + /** An abort signal to allow cancellation of the file write operation. + * + * If the signal becomes aborted the write file operation will be stopped + * and the promise returned will be rejected with an {@linkcode AbortError}. + */ + signal?: AbortSignal; + } + + /** Write `data` to the given `path`, by default creating a new file if + * needed, else overwriting. + * + * ```ts + * const encoder = new TextEncoder(); + * const data = encoder.encode("Hello world\n"); + * await Deno.writeFile("hello1.txt", data); // overwrite "hello1.txt" or create it + * await Deno.writeFile("hello2.txt", data, { create: false }); // only works if "hello2.txt" exists + * await Deno.writeFile("hello3.txt", data, { mode: 0o777 }); // set permissions on new file + * await Deno.writeFile("hello4.txt", data, { append: true }); // add data to the end of the file + * ``` + * + * Requires `allow-write` permission, and `allow-read` if `options.create` is + * `false`. + * + * @tags allow-read, allow-write + * @category File System + */ + export function writeFile( + path: string | URL, + data: Uint8Array | ReadableStream, + options?: WriteFileOptions, + ): Promise; + + /** Synchronously write `data` to the given `path`, by default creating a new + * file if needed, else overwriting. + * + * ```ts + * const encoder = new TextEncoder(); + * const data = encoder.encode("Hello world\n"); + * Deno.writeFileSync("hello1.txt", data); // overwrite "hello1.txt" or create it + * Deno.writeFileSync("hello2.txt", data, { create: false }); // only works if "hello2.txt" exists + * Deno.writeFileSync("hello3.txt", data, { mode: 0o777 }); // set permissions on new file + * Deno.writeFileSync("hello4.txt", data, { append: true }); // add data to the end of the file + * ``` + * + * Requires `allow-write` permission, and `allow-read` if `options.create` is + * `false`. + * + * @tags allow-read, allow-write + * @category File System + */ + export function writeFileSync( + path: string | URL, + data: Uint8Array, + options?: WriteFileOptions, + ): void; + + /** Write string `data` to the given `path`, by default creating a new file if + * needed, else overwriting. + * + * ```ts + * await Deno.writeTextFile("hello1.txt", "Hello world\n"); // overwrite "hello1.txt" or create it + * ``` + * + * Requires `allow-write` permission, and `allow-read` if `options.create` is + * `false`. + * + * @tags allow-read, allow-write + * @category File System + */ + export function writeTextFile( + path: string | URL, + data: string | ReadableStream, + options?: WriteFileOptions, + ): Promise; + + /** Synchronously write string `data` to the given `path`, by default creating + * a new file if needed, else overwriting. + * + * ```ts + * Deno.writeTextFileSync("hello1.txt", "Hello world\n"); // overwrite "hello1.txt" or create it + * ``` + * + * Requires `allow-write` permission, and `allow-read` if `options.create` is + * `false`. + * + * @tags allow-read, allow-write + * @category File System + */ + export function writeTextFileSync( + path: string | URL, + data: string, + options?: WriteFileOptions, + ): void; + + /** Truncates (or extends) the specified file, to reach the specified `len`. + * If `len` is not specified then the entire file contents are truncated. + * + * ### Truncate the entire file + * ```ts + * await Deno.truncate("my_file.txt"); + * ``` + * + * ### Truncate part of the file + * + * ```ts + * const file = await Deno.makeTempFile(); + * await Deno.writeFile(file, new TextEncoder().encode("Hello World")); + * await Deno.truncate(file, 7); + * const data = await Deno.readFile(file); + * console.log(new TextDecoder().decode(data)); // "Hello W" + * ``` + * + * Requires `allow-write` permission. + * + * @tags allow-write + * @category File System + */ + export function truncate(name: string, len?: number): Promise; + + /** Synchronously truncates (or extends) the specified file, to reach the + * specified `len`. If `len` is not specified then the entire file contents + * are truncated. + * + * ### Truncate the entire file + * + * ```ts + * Deno.truncateSync("my_file.txt"); + * ``` + * + * ### Truncate part of the file + * + * ```ts + * const file = Deno.makeTempFileSync(); + * Deno.writeFileSync(file, new TextEncoder().encode("Hello World")); + * Deno.truncateSync(file, 7); + * const data = Deno.readFileSync(file); + * console.log(new TextDecoder().decode(data)); + * ``` + * + * Requires `allow-write` permission. + * + * @tags allow-write + * @category File System + */ + export function truncateSync(name: string, len?: number): void; + + /** @category Observability + * + * @deprecated This API has been deprecated in Deno v1.37.1. + */ + export interface OpMetrics { + opsDispatched: number; + opsDispatchedSync: number; + opsDispatchedAsync: number; + opsDispatchedAsyncUnref: number; + opsCompleted: number; + opsCompletedSync: number; + opsCompletedAsync: number; + opsCompletedAsyncUnref: number; + bytesSentControl: number; + bytesSentData: number; + bytesReceived: number; + } + + /** @category Observability + * + * @deprecated This API has been deprecated in Deno v1.37.1. + */ + export interface Metrics extends OpMetrics { + ops: Record; + } + + /** Receive metrics from the privileged side of Deno. This is primarily used + * in the development of Deno. _Ops_, also called _bindings_, are the + * go-between between Deno JavaScript sandbox and the rest of Deno. + * + * ```shell + * > console.table(Deno.metrics()) + * ┌─────────────────────────┬────────┐ + * │ (index) │ Values │ + * ├─────────────────────────┼────────┤ + * │ opsDispatched │ 3 │ + * │ opsDispatchedSync │ 2 │ + * │ opsDispatchedAsync │ 1 │ + * │ opsDispatchedAsyncUnref │ 0 │ + * │ opsCompleted │ 3 │ + * │ opsCompletedSync │ 2 │ + * │ opsCompletedAsync │ 1 │ + * │ opsCompletedAsyncUnref │ 0 │ + * │ bytesSentControl │ 73 │ + * │ bytesSentData │ 0 │ + * │ bytesReceived │ 375 │ + * └─────────────────────────┴────────┘ + * ``` + * + * @category Observability + * + * @deprecated This API has been deprecated in Deno v1.37.1. + */ + export function metrics(): Metrics; + + /** + * A map of open resources that Deno is tracking. The key is the resource ID + * (_rid_) and the value is its representation. + * + * @category Observability */ + interface ResourceMap { + [rid: number]: unknown; + } + + /** Returns a map of open resource IDs (_rid_) along with their string + * representations. This is an internal API and as such resource + * representation has `unknown` type; that means it can change any time and + * should not be depended upon. + * + * ```ts + * console.log(Deno.resources()); + * // { 0: "stdin", 1: "stdout", 2: "stderr" } + * Deno.openSync('../test.file'); + * console.log(Deno.resources()); + * // { 0: "stdin", 1: "stdout", 2: "stderr", 3: "fsFile" } + * ``` + * + * @category Observability + */ + export function resources(): ResourceMap; + + /** + * Additional information for FsEvent objects with the "other" kind. + * + * - `"rescan"`: rescan notices indicate either a lapse in the events or a + * change in the filesystem such that events received so far can no longer + * be relied on to represent the state of the filesystem now. An + * application that simply reacts to file changes may not care about this. + * An application that keeps an in-memory representation of the filesystem + * will need to care, and will need to refresh that representation directly + * from the filesystem. + * + * @category File System + */ + export type FsEventFlag = "rescan"; + + /** + * Represents a unique file system event yielded by a + * {@linkcode Deno.FsWatcher}. + * + * @category File System */ + export interface FsEvent { + /** The kind/type of the file system event. */ + kind: "any" | "access" | "create" | "modify" | "remove" | "other"; + /** An array of paths that are associated with the file system event. */ + paths: string[]; + /** Any additional flags associated with the event. */ + flag?: FsEventFlag; + } + + /** + * Returned by {@linkcode Deno.watchFs}. It is an async iterator yielding up + * system events. To stop watching the file system by calling `.close()` + * method. + * + * @category File System + */ + export interface FsWatcher extends AsyncIterable, Disposable { + /** The resource id. */ + readonly rid: number; + /** Stops watching the file system and closes the watcher resource. */ + close(): void; + /** + * Stops watching the file system and closes the watcher resource. + * + * @deprecated Will be removed in the future. + */ + return?(value?: any): Promise>; + [Symbol.asyncIterator](): AsyncIterableIterator; + } + + /** Watch for file system events against one or more `paths`, which can be + * files or directories. These paths must exist already. One user action (e.g. + * `touch test.file`) can generate multiple file system events. Likewise, + * one user action can result in multiple file paths in one event (e.g. `mv + * old_name.txt new_name.txt`). + * + * The recursive option is `true` by default and, for directories, will watch + * the specified directory and all sub directories. + * + * Note that the exact ordering of the events can vary between operating + * systems. + * + * ```ts + * const watcher = Deno.watchFs("/"); + * for await (const event of watcher) { + * console.log(">>>> event", event); + * // { kind: "create", paths: [ "/foo.txt" ] } + * } + * ``` + * + * Call `watcher.close()` to stop watching. + * + * ```ts + * const watcher = Deno.watchFs("/"); + * + * setTimeout(() => { + * watcher.close(); + * }, 5000); + * + * for await (const event of watcher) { + * console.log(">>>> event", event); + * } + * ``` + * + * Requires `allow-read` permission. + * + * @tags allow-read + * @category File System + */ + export function watchFs( + paths: string | string[], + options?: { recursive: boolean }, + ): FsWatcher; + + /** + * @deprecated Use {@linkcode Deno.Command} instead. + * + * Options which can be used with {@linkcode Deno.run}. + * + * @category Sub Process */ + export interface RunOptions { + /** Arguments to pass. + * + * _Note_: the first element needs to be a path to the executable that is + * being run. */ + cmd: readonly string[] | [string | URL, ...string[]]; + /** The current working directory that should be used when running the + * sub-process. */ + cwd?: string; + /** Any environment variables to be set when running the sub-process. */ + env?: Record; + /** By default subprocess inherits `stdout` of parent process. To change + * this this option can be set to a resource ID (_rid_) of an open file, + * `"inherit"`, `"piped"`, or `"null"`: + * + * - _number_: the resource ID of an open file/resource. This allows you to + * write to a file. + * - `"inherit"`: The default if unspecified. The subprocess inherits from the + * parent. + * - `"piped"`: A new pipe should be arranged to connect the parent and child + * sub-process. + * - `"null"`: This stream will be ignored. This is the equivalent of attaching + * the stream to `/dev/null`. + */ + stdout?: "inherit" | "piped" | "null" | number; + /** By default subprocess inherits `stderr` of parent process. To change + * this this option can be set to a resource ID (_rid_) of an open file, + * `"inherit"`, `"piped"`, or `"null"`: + * + * - _number_: the resource ID of an open file/resource. This allows you to + * write to a file. + * - `"inherit"`: The default if unspecified. The subprocess inherits from the + * parent. + * - `"piped"`: A new pipe should be arranged to connect the parent and child + * sub-process. + * - `"null"`: This stream will be ignored. This is the equivalent of attaching + * the stream to `/dev/null`. + */ + stderr?: "inherit" | "piped" | "null" | number; + /** By default subprocess inherits `stdin` of parent process. To change + * this this option can be set to a resource ID (_rid_) of an open file, + * `"inherit"`, `"piped"`, or `"null"`: + * + * - _number_: the resource ID of an open file/resource. This allows you to + * read from a file. + * - `"inherit"`: The default if unspecified. The subprocess inherits from the + * parent. + * - `"piped"`: A new pipe should be arranged to connect the parent and child + * sub-process. + * - `"null"`: This stream will be ignored. This is the equivalent of attaching + * the stream to `/dev/null`. + */ + stdin?: "inherit" | "piped" | "null" | number; + } + + /** + * @deprecated Use {@linkcode Deno.Command} instead. + * + * The status resolved from the `.status()` method of a + * {@linkcode Deno.Process} instance. + * + * If `success` is `true`, then `code` will be `0`, but if `success` is + * `false`, the sub-process exit code will be set in `code`. + * + * @category Sub Process */ + export type ProcessStatus = + | { + success: true; + code: 0; + signal?: undefined; + } + | { + success: false; + code: number; + signal?: number; + }; + + /** + * * @deprecated Use {@linkcode Deno.Command} instead. + * + * Represents an instance of a sub process that is returned from + * {@linkcode Deno.run} which can be used to manage the sub-process. + * + * @category Sub Process */ + export class Process { + /** The resource ID of the sub-process. */ + readonly rid: number; + /** The operating system's process ID for the sub-process. */ + readonly pid: number; + /** A reference to the sub-processes `stdin`, which allows interacting with + * the sub-process at a low level. */ + readonly stdin: T["stdin"] extends "piped" ? Writer & Closer & { + writable: WritableStream; + } + : (Writer & Closer & { writable: WritableStream }) | null; + /** A reference to the sub-processes `stdout`, which allows interacting with + * the sub-process at a low level. */ + readonly stdout: T["stdout"] extends "piped" ? Reader & Closer & { + readable: ReadableStream; + } + : (Reader & Closer & { readable: ReadableStream }) | null; + /** A reference to the sub-processes `stderr`, which allows interacting with + * the sub-process at a low level. */ + readonly stderr: T["stderr"] extends "piped" ? Reader & Closer & { + readable: ReadableStream; + } + : (Reader & Closer & { readable: ReadableStream }) | null; + /** Wait for the process to exit and return its exit status. + * + * Calling this function multiple times will return the same status. + * + * The `stdin` reference to the process will be closed before waiting to + * avoid a deadlock. + * + * If `stdout` and/or `stderr` were set to `"piped"`, they must be closed + * manually before the process can exit. + * + * To run process to completion and collect output from both `stdout` and + * `stderr` use: + * + * ```ts + * const p = Deno.run({ cmd: [ "echo", "hello world" ], stderr: 'piped', stdout: 'piped' }); + * const [status, stdout, stderr] = await Promise.all([ + * p.status(), + * p.output(), + * p.stderrOutput() + * ]); + * p.close(); + * ``` + */ + status(): Promise; + /** Buffer the stdout until EOF and return it as `Uint8Array`. + * + * You must set `stdout` to `"piped"` when creating the process. + * + * This calls `close()` on stdout after its done. */ + output(): Promise; + /** Buffer the stderr until EOF and return it as `Uint8Array`. + * + * You must set `stderr` to `"piped"` when creating the process. + * + * This calls `close()` on stderr after its done. */ + stderrOutput(): Promise; + /** Clean up resources associated with the sub-process instance. */ + close(): void; + /** Send a signal to process. + * Default signal is `"SIGTERM"`. + * + * ```ts + * const p = Deno.run({ cmd: [ "sleep", "20" ]}); + * p.kill("SIGTERM"); + * p.close(); + * ``` + */ + kill(signo?: Signal): void; + } + + /** Operating signals which can be listened for or sent to sub-processes. What + * signals and what their standard behaviors are OS dependent. + * + * @category Runtime Environment */ + export type Signal = + | "SIGABRT" + | "SIGALRM" + | "SIGBREAK" + | "SIGBUS" + | "SIGCHLD" + | "SIGCONT" + | "SIGEMT" + | "SIGFPE" + | "SIGHUP" + | "SIGILL" + | "SIGINFO" + | "SIGINT" + | "SIGIO" + | "SIGKILL" + | "SIGPIPE" + | "SIGPROF" + | "SIGPWR" + | "SIGQUIT" + | "SIGSEGV" + | "SIGSTKFLT" + | "SIGSTOP" + | "SIGSYS" + | "SIGTERM" + | "SIGTRAP" + | "SIGTSTP" + | "SIGTTIN" + | "SIGTTOU" + | "SIGURG" + | "SIGUSR1" + | "SIGUSR2" + | "SIGVTALRM" + | "SIGWINCH" + | "SIGXCPU" + | "SIGXFSZ"; + + /** Registers the given function as a listener of the given signal event. + * + * ```ts + * Deno.addSignalListener( + * "SIGTERM", + * () => { + * console.log("SIGTERM!") + * } + * ); + * ``` + * + * _Note_: On Windows only `"SIGINT"` (CTRL+C) and `"SIGBREAK"` (CTRL+Break) + * are supported. + * + * @category Runtime Environment + */ + export function addSignalListener(signal: Signal, handler: () => void): void; + + /** Removes the given signal listener that has been registered with + * {@linkcode Deno.addSignalListener}. + * + * ```ts + * const listener = () => { + * console.log("SIGTERM!") + * }; + * Deno.addSignalListener("SIGTERM", listener); + * Deno.removeSignalListener("SIGTERM", listener); + * ``` + * + * _Note_: On Windows only `"SIGINT"` (CTRL+C) and `"SIGBREAK"` (CTRL+Break) + * are supported. + * + * @category Runtime Environment + */ + export function removeSignalListener( + signal: Signal, + handler: () => void, + ): void; + + /** + * @deprecated Use {@linkcode Deno.Command} instead. + * + * Spawns new subprocess. RunOptions must contain at a minimum the `opt.cmd`, + * an array of program arguments, the first of which is the binary. + * + * ```ts + * const p = Deno.run({ + * cmd: ["curl", "https://example.com"], + * }); + * const status = await p.status(); + * ``` + * + * Subprocess uses same working directory as parent process unless `opt.cwd` + * is specified. + * + * Environmental variables from parent process can be cleared using `opt.clearEnv`. + * Doesn't guarantee that only `opt.env` variables are present, + * as the OS may set environmental variables for processes. + * + * Environmental variables for subprocess can be specified using `opt.env` + * mapping. + * + * `opt.uid` sets the child process’s user ID. This translates to a setuid call + * in the child process. Failure in the setuid call will cause the spawn to fail. + * + * `opt.gid` is similar to `opt.uid`, but sets the group ID of the child process. + * This has the same semantics as the uid field. + * + * By default subprocess inherits stdio of parent process. To change + * this this, `opt.stdin`, `opt.stdout`, and `opt.stderr` can be set + * independently to a resource ID (_rid_) of an open file, `"inherit"`, + * `"piped"`, or `"null"`: + * + * - _number_: the resource ID of an open file/resource. This allows you to + * read or write to a file. + * - `"inherit"`: The default if unspecified. The subprocess inherits from the + * parent. + * - `"piped"`: A new pipe should be arranged to connect the parent and child + * sub-process. + * - `"null"`: This stream will be ignored. This is the equivalent of attaching + * the stream to `/dev/null`. + * + * Details of the spawned process are returned as an instance of + * {@linkcode Deno.Process}. + * + * Requires `allow-run` permission. + * + * @tags allow-run + * @category Sub Process + */ + export function run(opt: T): Process; + + /** Create a child process. + * + * If any stdio options are not set to `"piped"`, accessing the corresponding + * field on the `Command` or its `CommandOutput` will throw a `TypeError`. + * + * If `stdin` is set to `"piped"`, the `stdin` {@linkcode WritableStream} + * needs to be closed manually. + * + * @example Spawn a subprocess and pipe the output to a file + * + * ```ts + * const command = new Deno.Command(Deno.execPath(), { + * args: [ + * "eval", + * "console.log('Hello World')", + * ], + * stdin: "piped", + * stdout: "piped", + * }); + * const child = command.spawn(); + * + * // open a file and pipe the subprocess output to it. + * child.stdout.pipeTo( + * Deno.openSync("output", { write: true, create: true }).writable, + * ); + * + * // manually close stdin + * child.stdin.close(); + * const status = await child.status; + * ``` + * + * @example Spawn a subprocess and collect its output + * + * ```ts + * const command = new Deno.Command(Deno.execPath(), { + * args: [ + * "eval", + * "console.log('hello'); console.error('world')", + * ], + * }); + * const { code, stdout, stderr } = await command.output(); + * console.assert(code === 0); + * console.assert("hello\n" === new TextDecoder().decode(stdout)); + * console.assert("world\n" === new TextDecoder().decode(stderr)); + * ``` + * + * @example Spawn a subprocess and collect its output synchronously + * + * ```ts + * const command = new Deno.Command(Deno.execPath(), { + * args: [ + * "eval", + * "console.log('hello'); console.error('world')", + * ], + * }); + * const { code, stdout, stderr } = command.outputSync(); + * console.assert(code === 0); + * console.assert("hello\n" === new TextDecoder().decode(stdout)); + * console.assert("world\n" === new TextDecoder().decode(stderr)); + * ``` + * + * @tags allow-run + * @category Sub Process + */ + export class Command { + constructor(command: string | URL, options?: CommandOptions); + /** + * Executes the {@linkcode Deno.Command}, waiting for it to finish and + * collecting all of its output. + * If `spawn()` was called, calling this function will collect the remaining + * output. + * + * Will throw an error if `stdin: "piped"` is set. + * + * If options `stdout` or `stderr` are not set to `"piped"`, accessing the + * corresponding field on {@linkcode Deno.CommandOutput} will throw a `TypeError`. + */ + output(): Promise; + /** + * Synchronously executes the {@linkcode Deno.Command}, waiting for it to + * finish and collecting all of its output. + * + * Will throw an error if `stdin: "piped"` is set. + * + * If options `stdout` or `stderr` are not set to `"piped"`, accessing the + * corresponding field on {@linkcode Deno.CommandOutput} will throw a `TypeError`. + */ + outputSync(): CommandOutput; + /** + * Spawns a streamable subprocess, allowing to use the other methods. + */ + spawn(): ChildProcess; + } + + /** + * The interface for handling a child process returned from + * {@linkcode Deno.Command.spawn}. + * + * @category Sub Process + */ + export class ChildProcess implements AsyncDisposable { + get stdin(): WritableStream; + get stdout(): ReadableStream; + get stderr(): ReadableStream; + readonly pid: number; + /** Get the status of the child. */ + readonly status: Promise; + + /** Waits for the child to exit completely, returning all its output and + * status. */ + output(): Promise; + /** Kills the process with given {@linkcode Deno.Signal}. + * + * Defaults to `SIGTERM` if no signal is provided. + * + * @param [signo="SIGTERM"] + */ + kill(signo?: Signal): void; + + /** Ensure that the status of the child process prevents the Deno process + * from exiting. */ + ref(): void; + /** Ensure that the status of the child process does not block the Deno + * process from exiting. */ + unref(): void; + + [Symbol.asyncDispose](): Promise; + } + + /** + * Options which can be set when calling {@linkcode Deno.Command}. + * + * @category Sub Process + */ + export interface CommandOptions { + /** Arguments to pass to the process. */ + args?: string[]; + /** + * The working directory of the process. + * + * If not specified, the `cwd` of the parent process is used. + */ + cwd?: string | URL; + /** + * Clear environmental variables from parent process. + * + * Doesn't guarantee that only `env` variables are present, as the OS may + * set environmental variables for processes. + * + * @default {false} + */ + clearEnv?: boolean; + /** Environmental variables to pass to the subprocess. */ + env?: Record; + /** + * Sets the child process’s user ID. This translates to a setuid call in the + * child process. Failure in the set uid call will cause the spawn to fail. + */ + uid?: number; + /** Similar to `uid`, but sets the group ID of the child process. */ + gid?: number; + /** + * An {@linkcode AbortSignal} that allows closing the process using the + * corresponding {@linkcode AbortController} by sending the process a + * SIGTERM signal. + * + * Not supported in {@linkcode Deno.Command.outputSync}. + */ + signal?: AbortSignal; + + /** How `stdin` of the spawned process should be handled. + * + * Defaults to `"inherit"` for `output` & `outputSync`, + * and `"inherit"` for `spawn`. */ + stdin?: "piped" | "inherit" | "null"; + /** How `stdout` of the spawned process should be handled. + * + * Defaults to `"piped"` for `output` & `outputSync`, + * and `"inherit"` for `spawn`. */ + stdout?: "piped" | "inherit" | "null"; + /** How `stderr` of the spawned process should be handled. + * + * Defaults to `"piped"` for `output` & `outputSync`, + * and `"inherit"` for `spawn`. */ + stderr?: "piped" | "inherit" | "null"; + + /** Skips quoting and escaping of the arguments on windows. This option + * is ignored on non-windows platforms. + * + * @default {false} */ + windowsRawArguments?: boolean; + } + + /** + * @category Sub Process + */ + export interface CommandStatus { + /** If the child process exits with a 0 status code, `success` will be set + * to `true`, otherwise `false`. */ + success: boolean; + /** The exit code of the child process. */ + code: number; + /** The signal associated with the child process. */ + signal: Signal | null; + } + + /** + * The interface returned from calling {@linkcode Deno.Command.output} or + * {@linkcode Deno.Command.outputSync} which represents the result of spawning the + * child process. + * + * @category Sub Process + */ + export interface CommandOutput extends CommandStatus { + /** The buffered output from the child process' `stdout`. */ + readonly stdout: Uint8Array; + /** The buffered output from the child process' `stderr`. */ + readonly stderr: Uint8Array; + } + + /** Option which can be specified when performing {@linkcode Deno.inspect}. + * + * @category Console and Debugging */ + export interface InspectOptions { + /** Stylize output with ANSI colors. + * + * @default {false} */ + colors?: boolean; + /** Try to fit more than one entry of a collection on the same line. + * + * @default {true} */ + compact?: boolean; + /** Traversal depth for nested objects. + * + * @default {4} */ + depth?: number; + /** The maximum length for an inspection to take up a single line. + * + * @default {80} */ + breakLength?: number; + /** Whether or not to escape sequences. + * + * @default {true} */ + escapeSequences?: boolean; + /** The maximum number of iterable entries to print. + * + * @default {100} */ + iterableLimit?: number; + /** Show a Proxy's target and handler. + * + * @default {false} */ + showProxy?: boolean; + /** Sort Object, Set and Map entries by key. + * + * @default {false} */ + sorted?: boolean; + /** Add a trailing comma for multiline collections. + * + * @default {false} */ + trailingComma?: boolean; + /** Evaluate the result of calling getters. + * + * @default {false} */ + getters?: boolean; + /** Show an object's non-enumerable properties. + * + * @default {false} */ + showHidden?: boolean; + /** The maximum length of a string before it is truncated with an + * ellipsis. */ + strAbbreviateSize?: number; + } + + /** Converts the input into a string that has the same format as printed by + * `console.log()`. + * + * ```ts + * const obj = { + * a: 10, + * b: "hello", + * }; + * const objAsString = Deno.inspect(obj); // { a: 10, b: "hello" } + * console.log(obj); // prints same value as objAsString, e.g. { a: 10, b: "hello" } + * ``` + * + * A custom inspect functions can be registered on objects, via the symbol + * `Symbol.for("Deno.customInspect")`, to control and customize the output + * of `inspect()` or when using `console` logging: + * + * ```ts + * class A { + * x = 10; + * y = "hello"; + * [Symbol.for("Deno.customInspect")]() { + * return `x=${this.x}, y=${this.y}`; + * } + * } + * + * const inStringFormat = Deno.inspect(new A()); // "x=10, y=hello" + * console.log(inStringFormat); // prints "x=10, y=hello" + * ``` + * + * A depth can be specified by using the `depth` option: + * + * ```ts + * Deno.inspect({a: {b: {c: {d: 'hello'}}}}, {depth: 2}); // { a: { b: [Object] } } + * ``` + * + * @category Console and Debugging + */ + export function inspect(value: unknown, options?: InspectOptions): string; + + /** The name of a privileged feature which needs permission. + * + * @category Permissions + */ + export type PermissionName = + | "run" + | "read" + | "write" + | "net" + | "env" + | "sys" + | "ffi" + | "hrtime"; + + /** The current status of the permission: + * + * - `"granted"` - the permission has been granted. + * - `"denied"` - the permission has been explicitly denied. + * - `"prompt"` - the permission has not explicitly granted nor denied. + * + * @category Permissions + */ + export type PermissionState = + | "granted" + | "denied" + | "prompt"; + + /** The permission descriptor for the `allow-run` and `deny-run` permissions, which controls + * access to what sub-processes can be executed by Deno. The option `command` + * allows scoping the permission to a specific executable. + * + * **Warning, in practice, `allow-run` is effectively the same as `allow-all` + * in the sense that malicious code could execute any arbitrary code on the + * host.** + * + * @category Permissions */ + export interface RunPermissionDescriptor { + name: "run"; + /** An `allow-run` or `deny-run` permission can be scoped to a specific executable, + * which would be relative to the start-up CWD of the Deno CLI. */ + command?: string | URL; + } + + /** The permission descriptor for the `allow-read` and `deny-read` permissions, which controls + * access to reading resources from the local host. The option `path` allows + * scoping the permission to a specific path (and if the path is a directory + * any sub paths). + * + * Permission granted under `allow-read` only allows runtime code to attempt + * to read, the underlying operating system may apply additional permissions. + * + * @category Permissions */ + export interface ReadPermissionDescriptor { + name: "read"; + /** An `allow-read` or `deny-read` permission can be scoped to a specific path (and if + * the path is a directory, any sub paths). */ + path?: string | URL; + } + + /** The permission descriptor for the `allow-write` and `deny-write` permissions, which + * controls access to writing to resources from the local host. The option + * `path` allow scoping the permission to a specific path (and if the path is + * a directory any sub paths). + * + * Permission granted under `allow-write` only allows runtime code to attempt + * to write, the underlying operating system may apply additional permissions. + * + * @category Permissions */ + export interface WritePermissionDescriptor { + name: "write"; + /** An `allow-write` or `deny-write` permission can be scoped to a specific path (and if + * the path is a directory, any sub paths). */ + path?: string | URL; + } + + /** The permission descriptor for the `allow-net` and `deny-net` permissions, which controls + * access to opening network ports and connecting to remote hosts via the + * network. The option `host` allows scoping the permission for outbound + * connection to a specific host and port. + * + * @category Permissions */ + export interface NetPermissionDescriptor { + name: "net"; + /** Optional host string of the form `"[:]"`. Examples: + * + * "github.com" + * "deno.land:8080" + */ + host?: string; + } + + /** The permission descriptor for the `allow-env` and `deny-env` permissions, which controls + * access to being able to read and write to the process environment variables + * as well as access other information about the environment. The option + * `variable` allows scoping the permission to a specific environment + * variable. + * + * @category Permissions */ + export interface EnvPermissionDescriptor { + name: "env"; + /** Optional environment variable name (e.g. `PATH`). */ + variable?: string; + } + + /** The permission descriptor for the `allow-sys` and `deny-sys` permissions, which controls + * access to sensitive host system information, which malicious code might + * attempt to exploit. The option `kind` allows scoping the permission to a + * specific piece of information. + * + * @category Permissions */ + export interface SysPermissionDescriptor { + name: "sys"; + /** The specific information to scope the permission to. */ + kind?: + | "loadavg" + | "hostname" + | "systemMemoryInfo" + | "networkInterfaces" + | "osRelease" + | "osUptime" + | "uid" + | "gid"; + } + + /** The permission descriptor for the `allow-ffi` and `deny-ffi` permissions, which controls + * access to loading _foreign_ code and interfacing with it via the + * [Foreign Function Interface API](https://deno.land/manual/runtime/ffi_api) + * available in Deno. The option `path` allows scoping the permission to a + * specific path on the host. + * + * @category Permissions */ + export interface FfiPermissionDescriptor { + name: "ffi"; + /** Optional path on the local host to scope the permission to. */ + path?: string | URL; + } + + /** The permission descriptor for the `allow-hrtime` and `deny-hrtime` permissions, which + * controls if the runtime code has access to high resolution time. High + * resolution time is considered sensitive information, because it can be used + * by malicious code to gain information about the host that it might not + * otherwise have access to. + * + * @category Permissions */ + export interface HrtimePermissionDescriptor { + name: "hrtime"; + } + + /** Permission descriptors which define a permission and can be queried, + * requested, or revoked. + * + * View the specifics of the individual descriptors for more information about + * each permission kind. + * + * @category Permissions + */ + export type PermissionDescriptor = + | RunPermissionDescriptor + | ReadPermissionDescriptor + | WritePermissionDescriptor + | NetPermissionDescriptor + | EnvPermissionDescriptor + | SysPermissionDescriptor + | FfiPermissionDescriptor + | HrtimePermissionDescriptor; + + /** The interface which defines what event types are supported by + * {@linkcode PermissionStatus} instances. + * + * @category Permissions */ + export interface PermissionStatusEventMap { + "change": Event; + } + + /** An {@linkcode EventTarget} returned from the {@linkcode Deno.permissions} + * API which can provide updates to any state changes of the permission. + * + * @category Permissions */ + export class PermissionStatus extends EventTarget { + // deno-lint-ignore no-explicit-any + onchange: ((this: PermissionStatus, ev: Event) => any) | null; + readonly state: PermissionState; + /** + * Describes if permission is only granted partially, eg. an access + * might be granted to "/foo" directory, but denied for "/foo/bar". + * In such case this field will be set to `true` when querying for + * read permissions of "/foo" directory. + */ + readonly partial: boolean; + addEventListener( + type: K, + listener: ( + this: PermissionStatus, + ev: PermissionStatusEventMap[K], + ) => any, + options?: boolean | AddEventListenerOptions, + ): void; + addEventListener( + type: string, + listener: EventListenerOrEventListenerObject, + options?: boolean | AddEventListenerOptions, + ): void; + removeEventListener( + type: K, + listener: ( + this: PermissionStatus, + ev: PermissionStatusEventMap[K], + ) => any, + options?: boolean | EventListenerOptions, + ): void; + removeEventListener( + type: string, + listener: EventListenerOrEventListenerObject, + options?: boolean | EventListenerOptions, + ): void; + } + + /** + * Deno's permission management API. + * + * The class which provides the interface for the {@linkcode Deno.permissions} + * global instance and is based on the web platform + * [Permissions API](https://developer.mozilla.org/en-US/docs/Web/API/Permissions_API), + * though some proposed parts of the API which are useful in a server side + * runtime context were removed or abandoned in the web platform specification + * which is why it was chosen to locate it in the {@linkcode Deno} namespace + * instead. + * + * By default, if the `stdin`/`stdout` is TTY for the Deno CLI (meaning it can + * send and receive text), then the CLI will prompt the user to grant + * permission when an un-granted permission is requested. This behavior can + * be changed by using the `--no-prompt` command at startup. When prompting + * the CLI will request the narrowest permission possible, potentially making + * it annoying to the user. The permissions APIs allow the code author to + * request a wider set of permissions at one time in order to provide a better + * user experience. + * + * @category Permissions */ + export class Permissions { + /** Resolves to the current status of a permission. + * + * Note, if the permission is already granted, `request()` will not prompt + * the user again, therefore `query()` is only necessary if you are going + * to react differently existing permissions without wanting to modify them + * or prompt the user to modify them. + * + * ```ts + * const status = await Deno.permissions.query({ name: "read", path: "/etc" }); + * console.log(status.state); + * ``` + */ + query(desc: PermissionDescriptor): Promise; + + /** Returns the current status of a permission. + * + * Note, if the permission is already granted, `request()` will not prompt + * the user again, therefore `querySync()` is only necessary if you are going + * to react differently existing permissions without wanting to modify them + * or prompt the user to modify them. + * + * ```ts + * const status = Deno.permissions.querySync({ name: "read", path: "/etc" }); + * console.log(status.state); + * ``` + */ + querySync(desc: PermissionDescriptor): PermissionStatus; + + /** Revokes a permission, and resolves to the state of the permission. + * + * ```ts + * import { assert } from "https://deno.land/std/assert/mod.ts"; + * + * const status = await Deno.permissions.revoke({ name: "run" }); + * assert(status.state !== "granted") + * ``` + */ + revoke(desc: PermissionDescriptor): Promise; + + /** Revokes a permission, and returns the state of the permission. + * + * ```ts + * import { assert } from "https://deno.land/std/assert/mod.ts"; + * + * const status = Deno.permissions.revokeSync({ name: "run" }); + * assert(status.state !== "granted") + * ``` + */ + revokeSync(desc: PermissionDescriptor): PermissionStatus; + + /** Requests the permission, and resolves to the state of the permission. + * + * If the permission is already granted, the user will not be prompted to + * grant the permission again. + * + * ```ts + * const status = await Deno.permissions.request({ name: "env" }); + * if (status.state === "granted") { + * console.log("'env' permission is granted."); + * } else { + * console.log("'env' permission is denied."); + * } + * ``` + */ + request(desc: PermissionDescriptor): Promise; + + /** Requests the permission, and returns the state of the permission. + * + * If the permission is already granted, the user will not be prompted to + * grant the permission again. + * + * ```ts + * const status = Deno.permissions.requestSync({ name: "env" }); + * if (status.state === "granted") { + * console.log("'env' permission is granted."); + * } else { + * console.log("'env' permission is denied."); + * } + * ``` + */ + requestSync(desc: PermissionDescriptor): PermissionStatus; + } + + /** Deno's permission management API. + * + * It is a singleton instance of the {@linkcode Permissions} object and is + * based on the web platform + * [Permissions API](https://developer.mozilla.org/en-US/docs/Web/API/Permissions_API), + * though some proposed parts of the API which are useful in a server side + * runtime context were removed or abandoned in the web platform specification + * which is why it was chosen to locate it in the {@linkcode Deno} namespace + * instead. + * + * By default, if the `stdin`/`stdout` is TTY for the Deno CLI (meaning it can + * send and receive text), then the CLI will prompt the user to grant + * permission when an un-granted permission is requested. This behavior can + * be changed by using the `--no-prompt` command at startup. When prompting + * the CLI will request the narrowest permission possible, potentially making + * it annoying to the user. The permissions APIs allow the code author to + * request a wider set of permissions at one time in order to provide a better + * user experience. + * + * Requesting already granted permissions will not prompt the user and will + * return that the permission was granted. + * + * ### Querying + * + * ```ts + * const status = await Deno.permissions.query({ name: "read", path: "/etc" }); + * console.log(status.state); + * ``` + * + * ```ts + * const status = Deno.permissions.querySync({ name: "read", path: "/etc" }); + * console.log(status.state); + * ``` + * + * ### Revoking + * + * ```ts + * import { assert } from "https://deno.land/std/assert/mod.ts"; + * + * const status = await Deno.permissions.revoke({ name: "run" }); + * assert(status.state !== "granted") + * ``` + * + * ```ts + * import { assert } from "https://deno.land/std/assert/mod.ts"; + * + * const status = Deno.permissions.revokeSync({ name: "run" }); + * assert(status.state !== "granted") + * ``` + * + * ### Requesting + * + * ```ts + * const status = await Deno.permissions.request({ name: "env" }); + * if (status.state === "granted") { + * console.log("'env' permission is granted."); + * } else { + * console.log("'env' permission is denied."); + * } + * ``` + * + * ```ts + * const status = Deno.permissions.requestSync({ name: "env" }); + * if (status.state === "granted") { + * console.log("'env' permission is granted."); + * } else { + * console.log("'env' permission is denied."); + * } + * ``` + * + * @category Permissions + */ + export const permissions: Permissions; + + /** Information related to the build of the current Deno runtime. + * + * Users are discouraged from code branching based on this information, as + * assumptions about what is available in what build environment might change + * over time. Developers should specifically sniff out the features they + * intend to use. + * + * The intended use for the information is for logging and debugging purposes. + * + * @category Runtime Environment + */ + export const build: { + /** The [LLVM](https://llvm.org/) target triple, which is the combination + * of `${arch}-${vendor}-${os}` and represent the specific build target that + * the current runtime was built for. */ + target: string; + /** Instruction set architecture that the Deno CLI was built for. */ + arch: "x86_64" | "aarch64"; + /** The operating system that the Deno CLI was built for. `"darwin"` is + * also known as OSX or MacOS. */ + os: + | "darwin" + | "linux" + | "windows" + | "freebsd" + | "netbsd" + | "aix" + | "solaris" + | "illumos"; + /** The computer vendor that the Deno CLI was built for. */ + vendor: string; + /** Optional environment flags that were set for this build of Deno CLI. */ + env?: string; + }; + + /** Version information related to the current Deno CLI runtime environment. + * + * Users are discouraged from code branching based on this information, as + * assumptions about what is available in what build environment might change + * over time. Developers should specifically sniff out the features they + * intend to use. + * + * The intended use for the information is for logging and debugging purposes. + * + * @category Runtime Environment + */ + export const version: { + /** Deno CLI's version. For example: `"1.26.0"`. */ + deno: string; + /** The V8 version used by Deno. For example: `"10.7.100.0"`. + * + * V8 is the underlying JavaScript runtime platform that Deno is built on + * top of. */ + v8: string; + /** The TypeScript version used by Deno. For example: `"4.8.3"`. + * + * A version of the TypeScript type checker and language server is built-in + * to the Deno CLI. */ + typescript: string; + }; + + /** Returns the script arguments to the program. + * + * Give the following command line invocation of Deno: + * + * ```sh + * deno run --allow-read https://examples.deno.land/command-line-arguments.ts Sushi + * ``` + * + * Then `Deno.args` will contain: + * + * ```ts + * [ "Sushi" ] + * ``` + * + * If you are looking for a structured way to parse arguments, there is the + * [`std/flags`](https://deno.land/std/flags) module as part of the Deno + * standard library. + * + * @category Runtime Environment + */ + export const args: string[]; + + /** + * A symbol which can be used as a key for a custom method which will be + * called when `Deno.inspect()` is called, or when the object is logged to + * the console. + * + * @deprecated This symbol is deprecated since 1.9. Use + * `Symbol.for("Deno.customInspect")` instead. + * + * @category Console and Debugging + */ + export const customInspect: unique symbol; + + /** The URL of the entrypoint module entered from the command-line. It + * requires read permission to the CWD. + * + * Also see {@linkcode ImportMeta} for other related information. + * + * @tags allow-read + * @category Runtime Environment + */ + export const mainModule: string; + + /** Options that can be used with {@linkcode symlink} and + * {@linkcode symlinkSync}. + * + * @category File System */ + export interface SymlinkOptions { + /** If the symbolic link should be either a file or directory. This option + * only applies to Windows and is ignored on other operating systems. */ + type: "file" | "dir"; + } + + /** + * Creates `newpath` as a symbolic link to `oldpath`. + * + * The `options.type` parameter can be set to `"file"` or `"dir"`. This + * argument is only available on Windows and ignored on other platforms. + * + * ```ts + * await Deno.symlink("old/name", "new/name"); + * ``` + * + * Requires full `allow-read` and `allow-write` permissions. + * + * @tags allow-read, allow-write + * @category File System + */ + export function symlink( + oldpath: string | URL, + newpath: string | URL, + options?: SymlinkOptions, + ): Promise; + + /** + * Creates `newpath` as a symbolic link to `oldpath`. + * + * The `options.type` parameter can be set to `"file"` or `"dir"`. This + * argument is only available on Windows and ignored on other platforms. + * + * ```ts + * Deno.symlinkSync("old/name", "new/name"); + * ``` + * + * Requires full `allow-read` and `allow-write` permissions. + * + * @tags allow-read, allow-write + * @category File System + */ + export function symlinkSync( + oldpath: string | URL, + newpath: string | URL, + options?: SymlinkOptions, + ): void; + + /** + * Truncates or extends the specified file stream, to reach the specified + * `len`. + * + * If `len` is not specified then the entire file contents are truncated as if + * `len` was set to `0`. + * + * If the file previously was larger than this new length, the extra data is + * lost. + * + * If the file previously was shorter, it is extended, and the extended part + * reads as null bytes ('\0'). + * + * ### Truncate the entire file + * + * ```ts + * const file = await Deno.open( + * "my_file.txt", + * { read: true, write: true, create: true } + * ); + * await Deno.ftruncate(file.rid); + * ``` + * + * ### Truncate part of the file + * + * ```ts + * const file = await Deno.open( + * "my_file.txt", + * { read: true, write: true, create: true } + * ); + * await Deno.write(file.rid, new TextEncoder().encode("Hello World")); + * await Deno.ftruncate(file.rid, 7); + * const data = new Uint8Array(32); + * await Deno.read(file.rid, data); + * console.log(new TextDecoder().decode(data)); // Hello W + * ``` + * + * @category File System + */ + export function ftruncate(rid: number, len?: number): Promise; + + /** + * Synchronously truncates or extends the specified file stream, to reach the + * specified `len`. + * + * If `len` is not specified then the entire file contents are truncated as if + * `len` was set to `0`. + * + * If the file previously was larger than this new length, the extra data is + * lost. + * + * If the file previously was shorter, it is extended, and the extended part + * reads as null bytes ('\0'). + * + * ### Truncate the entire file + * + * ```ts + * const file = Deno.openSync( + * "my_file.txt", + * { read: true, write: true, truncate: true, create: true } + * ); + * Deno.ftruncateSync(file.rid); + * ``` + * + * ### Truncate part of the file + * + * ```ts + * const file = Deno.openSync( + * "my_file.txt", + * { read: true, write: true, create: true } + * ); + * Deno.writeSync(file.rid, new TextEncoder().encode("Hello World")); + * Deno.ftruncateSync(file.rid, 7); + * Deno.seekSync(file.rid, 0, Deno.SeekMode.Start); + * const data = new Uint8Array(32); + * Deno.readSync(file.rid, data); + * console.log(new TextDecoder().decode(data)); // Hello W + * ``` + * + * @category File System + */ + export function ftruncateSync(rid: number, len?: number): void; + + /** + * Synchronously changes the access (`atime`) and modification (`mtime`) times + * of a file stream resource referenced by `rid`. Given times are either in + * seconds (UNIX epoch time) or as `Date` objects. + * + * ```ts + * const file = Deno.openSync("file.txt", { create: true, write: true }); + * Deno.futimeSync(file.rid, 1556495550, new Date()); + * ``` + * + * @category File System + */ + export function futimeSync( + rid: number, + atime: number | Date, + mtime: number | Date, + ): void; + + /** + * Changes the access (`atime`) and modification (`mtime`) times of a file + * stream resource referenced by `rid`. Given times are either in seconds + * (UNIX epoch time) or as `Date` objects. + * + * ```ts + * const file = await Deno.open("file.txt", { create: true, write: true }); + * await Deno.futime(file.rid, 1556495550, new Date()); + * ``` + * + * @category File System + */ + export function futime( + rid: number, + atime: number | Date, + mtime: number | Date, + ): Promise; + + /** + * Returns a `Deno.FileInfo` for the given file stream. + * + * ```ts + * import { assert } from "https://deno.land/std/assert/mod.ts"; + * + * const file = await Deno.open("file.txt", { read: true }); + * const fileInfo = await Deno.fstat(file.rid); + * assert(fileInfo.isFile); + * ``` + * + * @category File System + */ + export function fstat(rid: number): Promise; + + /** + * Synchronously returns a {@linkcode Deno.FileInfo} for the given file + * stream. + * + * ```ts + * import { assert } from "https://deno.land/std/assert/mod.ts"; + * + * const file = Deno.openSync("file.txt", { read: true }); + * const fileInfo = Deno.fstatSync(file.rid); + * assert(fileInfo.isFile); + * ``` + * + * @category File System + */ + export function fstatSync(rid: number): FileInfo; + + /** + * Synchronously changes the access (`atime`) and modification (`mtime`) times + * of a file system object referenced by `path`. Given times are either in + * seconds (UNIX epoch time) or as `Date` objects. + * + * ```ts + * Deno.utimeSync("myfile.txt", 1556495550, new Date()); + * ``` + * + * Requires `allow-write` permission. + * + * @tags allow-write + * @category File System + */ + export function utimeSync( + path: string | URL, + atime: number | Date, + mtime: number | Date, + ): void; + + /** + * Changes the access (`atime`) and modification (`mtime`) times of a file + * system object referenced by `path`. Given times are either in seconds + * (UNIX epoch time) or as `Date` objects. + * + * ```ts + * await Deno.utime("myfile.txt", 1556495550, new Date()); + * ``` + * + * Requires `allow-write` permission. + * + * @tags allow-write + * @category File System + */ + export function utime( + path: string | URL, + atime: number | Date, + mtime: number | Date, + ): Promise; + + /** The event yielded from an {@linkcode HttpConn} which represents an HTTP + * request from a remote client. + * + * @category HTTP Server */ + export interface RequestEvent { + /** The request from the client in the form of the web platform + * {@linkcode Request}. */ + readonly request: Request; + /** The method to be used to respond to the event. The response needs to + * either be an instance of {@linkcode Response} or a promise that resolves + * with an instance of `Response`. + * + * When the response is successfully processed then the promise returned + * will be resolved. If there are any issues with sending the response, + * the promise will be rejected. */ + respondWith(r: Response | PromiseLike): Promise; + } + + /** The async iterable that is returned from {@linkcode Deno.serveHttp} which + * yields up {@linkcode RequestEvent} events, representing individual + * requests on the HTTP server connection. + * + * @category HTTP Server */ + export interface HttpConn extends AsyncIterable, Disposable { + /** The resource ID associated with this connection. Generally users do not + * need to be aware of this identifier. */ + readonly rid: number; + + /** An alternative to the async iterable interface which provides promises + * which resolve with either a {@linkcode RequestEvent} when there is + * another request or `null` when the client has closed the connection. */ + nextRequest(): Promise; + /** Initiate a server side closure of the connection, indicating to the + * client that you refuse to accept any more requests on this connection. + * + * Typically the client closes the connection, which will result in the + * async iterable terminating or the `nextRequest()` method returning + * `null`. */ + close(): void; + } + + /** + * Provides an interface to handle HTTP request and responses over TCP or TLS + * connections. The method returns an {@linkcode HttpConn} which yields up + * {@linkcode RequestEvent} events, which utilize the web platform standard + * {@linkcode Request} and {@linkcode Response} objects to handle the request. + * + * ```ts + * const conn = Deno.listen({ port: 80 }); + * const httpConn = Deno.serveHttp(await conn.accept()); + * const e = await httpConn.nextRequest(); + * if (e) { + * e.respondWith(new Response("Hello World")); + * } + * ``` + * + * Alternatively, you can also use the async iterator approach: + * + * ```ts + * async function handleHttp(conn: Deno.Conn) { + * for await (const e of Deno.serveHttp(conn)) { + * e.respondWith(new Response("Hello World")); + * } + * } + * + * for await (const conn of Deno.listen({ port: 80 })) { + * handleHttp(conn); + * } + * ``` + * + * If `httpConn.nextRequest()` encounters an error or returns `null` then the + * underlying {@linkcode HttpConn} resource is closed automatically. + * + * Also see the experimental Flash HTTP server {@linkcode Deno.serve} which + * provides a ground up rewrite of handling of HTTP requests and responses + * within the Deno CLI. + * + * Note that this function *consumes* the given connection passed to it, thus + * the original connection will be unusable after calling this. Additionally, + * you need to ensure that the connection is not being used elsewhere when + * calling this function in order for the connection to be consumed properly. + * + * For instance, if there is a `Promise` that is waiting for read operation on + * the connection to complete, it is considered that the connection is being + * used elsewhere. In such a case, this function will fail. + * + * @category HTTP Server + */ + export function serveHttp(conn: Conn): HttpConn; + + /** The object that is returned from a {@linkcode Deno.upgradeWebSocket} + * request. + * + * @category Web Sockets */ + export interface WebSocketUpgrade { + /** The response object that represents the HTTP response to the client, + * which should be used to the {@linkcode RequestEvent} `.respondWith()` for + * the upgrade to be successful. */ + response: Response; + /** The {@linkcode WebSocket} interface to communicate to the client via a + * web socket. */ + socket: WebSocket; + } + + /** Options which can be set when performing a + * {@linkcode Deno.upgradeWebSocket} upgrade of a {@linkcode Request} + * + * @category Web Sockets */ + export interface UpgradeWebSocketOptions { + /** Sets the `.protocol` property on the client side web socket to the + * value provided here, which should be one of the strings specified in the + * `protocols` parameter when requesting the web socket. This is intended + * for clients and servers to specify sub-protocols to use to communicate to + * each other. */ + protocol?: string; + /** If the client does not respond to this frame with a + * `pong` within the timeout specified, the connection is deemed + * unhealthy and is closed. The `close` and `error` event will be emitted. + * + * The default is 120 seconds. Set to `0` to disable timeouts. */ + idleTimeout?: number; + } + + /** + * Upgrade an incoming HTTP request to a WebSocket. + * + * Given a {@linkcode Request}, returns a pair of {@linkcode WebSocket} and + * {@linkcode Response} instances. The original request must be responded to + * with the returned response for the websocket upgrade to be successful. + * + * ```ts + * const conn = Deno.listen({ port: 80 }); + * const httpConn = Deno.serveHttp(await conn.accept()); + * const e = await httpConn.nextRequest(); + * if (e) { + * const { socket, response } = Deno.upgradeWebSocket(e.request); + * socket.onopen = () => { + * socket.send("Hello World!"); + * }; + * socket.onmessage = (e) => { + * console.log(e.data); + * socket.close(); + * }; + * socket.onclose = () => console.log("WebSocket has been closed."); + * socket.onerror = (e) => console.error("WebSocket error:", e); + * e.respondWith(response); + * } + * ``` + * + * If the request body is disturbed (read from) before the upgrade is + * completed, upgrading fails. + * + * This operation does not yet consume the request or open the websocket. This + * only happens once the returned response has been passed to `respondWith()`. + * + * @category Web Sockets + */ + export function upgradeWebSocket( + request: Request, + options?: UpgradeWebSocketOptions, + ): WebSocketUpgrade; + + /** Send a signal to process under given `pid`. The value and meaning of the + * `signal` to the process is operating system and process dependant. + * {@linkcode Signal} provides the most common signals. Default signal + * is `"SIGTERM"`. + * + * The term `kill` is adopted from the UNIX-like command line command `kill` + * which also signals processes. + * + * If `pid` is negative, the signal will be sent to the process group + * identified by `pid`. An error will be thrown if a negative `pid` is used on + * Windows. + * + * ```ts + * const p = Deno.run({ + * cmd: ["sleep", "10000"] + * }); + * + * Deno.kill(p.pid, "SIGINT"); + * ``` + * + * Requires `allow-run` permission. + * + * @tags allow-run + * @category Sub Process + */ + export function kill(pid: number, signo?: Signal): void; + + /** The type of the resource record to resolve via DNS using + * {@linkcode Deno.resolveDns}. + * + * Only the listed types are supported currently. + * + * @category Network + */ + export type RecordType = + | "A" + | "AAAA" + | "ANAME" + | "CAA" + | "CNAME" + | "MX" + | "NAPTR" + | "NS" + | "PTR" + | "SOA" + | "SRV" + | "TXT"; + + /** + * Options which can be set when using {@linkcode Deno.resolveDns}. + * + * @category Network */ + export interface ResolveDnsOptions { + /** The name server to be used for lookups. + * + * If not specified, defaults to the system configuration. For example + * `/etc/resolv.conf` on Unix-like systems. */ + nameServer?: { + /** The IP address of the name server. */ + ipAddr: string; + /** The port number the query will be sent to. + * + * @default {53} */ + port?: number; + }; + /** + * An abort signal to allow cancellation of the DNS resolution operation. + * If the signal becomes aborted the resolveDns operation will be stopped + * and the promise returned will be rejected with an AbortError. + */ + signal?: AbortSignal; + } + + /** If {@linkcode Deno.resolveDns} is called with `"CAA"` record type + * specified, it will resolve with an array of objects with this interface. + * + * @category Network + */ + export interface CAARecord { + /** If `true`, indicates that the corresponding property tag **must** be + * understood if the semantics of the CAA record are to be correctly + * interpreted by an issuer. + * + * Issuers **must not** issue certificates for a domain if the relevant CAA + * Resource Record set contains unknown property tags that have `critical` + * set. */ + critical: boolean; + /** An string that represents the identifier of the property represented by + * the record. */ + tag: string; + /** The value associated with the tag. */ + value: string; + } + + /** If {@linkcode Deno.resolveDns} is called with `"MX"` record type + * specified, it will return an array of objects with this interface. + * + * @category Network */ + export interface MXRecord { + /** A priority value, which is a relative value compared to the other + * preferences of MX records for the domain. */ + preference: number; + /** The server that mail should be delivered to. */ + exchange: string; + } + + /** If {@linkcode Deno.resolveDns} is called with `"NAPTR"` record type + * specified, it will return an array of objects with this interface. + * + * @category Network */ + export interface NAPTRRecord { + order: number; + preference: number; + flags: string; + services: string; + regexp: string; + replacement: string; + } + + /** If {@linkcode Deno.resolveDns} is called with `"SOA"` record type + * specified, it will return an array of objects with this interface. + * + * @category Network */ + export interface SOARecord { + mname: string; + rname: string; + serial: number; + refresh: number; + retry: number; + expire: number; + minimum: number; + } + + /** If {@linkcode Deno.resolveDns} is called with `"SRV"` record type + * specified, it will return an array of objects with this interface. + * + * @category Network + */ + export interface SRVRecord { + priority: number; + weight: number; + port: number; + target: string; + } + + /** + * Performs DNS resolution against the given query, returning resolved + * records. + * + * Fails in the cases such as: + * + * - the query is in invalid format. + * - the options have an invalid parameter. For example `nameServer.port` is + * beyond the range of 16-bit unsigned integer. + * - the request timed out. + * + * ```ts + * const a = await Deno.resolveDns("example.com", "A"); + * + * const aaaa = await Deno.resolveDns("example.com", "AAAA", { + * nameServer: { ipAddr: "8.8.8.8", port: 53 }, + * }); + * ``` + * + * Requires `allow-net` permission. + * + * @tags allow-net + * @category Network + */ + export function resolveDns( + query: string, + recordType: "A" | "AAAA" | "ANAME" | "CNAME" | "NS" | "PTR", + options?: ResolveDnsOptions, + ): Promise; + + /** + * Performs DNS resolution against the given query, returning resolved + * records. + * + * Fails in the cases such as: + * + * - the query is in invalid format. + * - the options have an invalid parameter. For example `nameServer.port` is + * beyond the range of 16-bit unsigned integer. + * - the request timed out. + * + * ```ts + * const a = await Deno.resolveDns("example.com", "A"); + * + * const aaaa = await Deno.resolveDns("example.com", "AAAA", { + * nameServer: { ipAddr: "8.8.8.8", port: 53 }, + * }); + * ``` + * + * Requires `allow-net` permission. + * + * @tags allow-net + * @category Network + */ + export function resolveDns( + query: string, + recordType: "CAA", + options?: ResolveDnsOptions, + ): Promise; + + /** + * Performs DNS resolution against the given query, returning resolved + * records. + * + * Fails in the cases such as: + * + * - the query is in invalid format. + * - the options have an invalid parameter. For example `nameServer.port` is + * beyond the range of 16-bit unsigned integer. + * - the request timed out. + * + * ```ts + * const a = await Deno.resolveDns("example.com", "A"); + * + * const aaaa = await Deno.resolveDns("example.com", "AAAA", { + * nameServer: { ipAddr: "8.8.8.8", port: 53 }, + * }); + * ``` + * + * Requires `allow-net` permission. + * + * @tags allow-net + * @category Network + */ + export function resolveDns( + query: string, + recordType: "MX", + options?: ResolveDnsOptions, + ): Promise; + + /** + * Performs DNS resolution against the given query, returning resolved + * records. + * + * Fails in the cases such as: + * + * - the query is in invalid format. + * - the options have an invalid parameter. For example `nameServer.port` is + * beyond the range of 16-bit unsigned integer. + * - the request timed out. + * + * ```ts + * const a = await Deno.resolveDns("example.com", "A"); + * + * const aaaa = await Deno.resolveDns("example.com", "AAAA", { + * nameServer: { ipAddr: "8.8.8.8", port: 53 }, + * }); + * ``` + * + * Requires `allow-net` permission. + * + * @tags allow-net + * @category Network + */ + export function resolveDns( + query: string, + recordType: "NAPTR", + options?: ResolveDnsOptions, + ): Promise; + + /** + * Performs DNS resolution against the given query, returning resolved + * records. + * + * Fails in the cases such as: + * + * - the query is in invalid format. + * - the options have an invalid parameter. For example `nameServer.port` is + * beyond the range of 16-bit unsigned integer. + * - the request timed out. + * + * ```ts + * const a = await Deno.resolveDns("example.com", "A"); + * + * const aaaa = await Deno.resolveDns("example.com", "AAAA", { + * nameServer: { ipAddr: "8.8.8.8", port: 53 }, + * }); + * ``` + * + * Requires `allow-net` permission. + * + * @tags allow-net + * @category Network + */ + export function resolveDns( + query: string, + recordType: "SOA", + options?: ResolveDnsOptions, + ): Promise; + + /** + * Performs DNS resolution against the given query, returning resolved + * records. + * + * Fails in the cases such as: + * + * - the query is in invalid format. + * - the options have an invalid parameter. For example `nameServer.port` is + * beyond the range of 16-bit unsigned integer. + * - the request timed out. + * + * ```ts + * const a = await Deno.resolveDns("example.com", "A"); + * + * const aaaa = await Deno.resolveDns("example.com", "AAAA", { + * nameServer: { ipAddr: "8.8.8.8", port: 53 }, + * }); + * ``` + * + * Requires `allow-net` permission. + * + * @tags allow-net + * @category Network + */ + export function resolveDns( + query: string, + recordType: "SRV", + options?: ResolveDnsOptions, + ): Promise; + + /** + * Performs DNS resolution against the given query, returning resolved + * records. + * + * Fails in the cases such as: + * + * - the query is in invalid format. + * - the options have an invalid parameter. For example `nameServer.port` is + * beyond the range of 16-bit unsigned integer. + * - the request timed out. + * + * ```ts + * const a = await Deno.resolveDns("example.com", "A"); + * + * const aaaa = await Deno.resolveDns("example.com", "AAAA", { + * nameServer: { ipAddr: "8.8.8.8", port: 53 }, + * }); + * ``` + * + * Requires `allow-net` permission. + * + * @tags allow-net + * @category Network + */ + export function resolveDns( + query: string, + recordType: "TXT", + options?: ResolveDnsOptions, + ): Promise; + + /** + * Performs DNS resolution against the given query, returning resolved + * records. + * + * Fails in the cases such as: + * + * - the query is in invalid format. + * - the options have an invalid parameter. For example `nameServer.port` is + * beyond the range of 16-bit unsigned integer. + * - the request timed out. + * + * ```ts + * const a = await Deno.resolveDns("example.com", "A"); + * + * const aaaa = await Deno.resolveDns("example.com", "AAAA", { + * nameServer: { ipAddr: "8.8.8.8", port: 53 }, + * }); + * ``` + * + * Requires `allow-net` permission. + * + * @tags allow-net + * @category Network + */ + export function resolveDns( + query: string, + recordType: RecordType, + options?: ResolveDnsOptions, + ): Promise< + | string[] + | CAARecord[] + | MXRecord[] + | NAPTRRecord[] + | SOARecord[] + | SRVRecord[] + | string[][] + >; + + /** + * Make the timer of the given `id` block the event loop from finishing. + * + * @category Timers + */ + export function refTimer(id: number): void; + + /** + * Make the timer of the given `id` not block the event loop from finishing. + * + * @category Timers + */ + export function unrefTimer(id: number): void; + + /** + * Returns the user id of the process on POSIX platforms. Returns null on Windows. + * + * ```ts + * console.log(Deno.uid()); + * ``` + * + * Requires `allow-sys` permission. + * + * @tags allow-sys + * @category Runtime Environment + */ + export function uid(): number | null; + + /** + * Returns the group id of the process on POSIX platforms. Returns null on windows. + * + * ```ts + * console.log(Deno.gid()); + * ``` + * + * Requires `allow-sys` permission. + * + * @tags allow-sys + * @category Runtime Environment + */ + export function gid(): number | null; + + /** Information for a HTTP request. + * + * @category HTTP Server + */ + export interface ServeHandlerInfo { + /** The remote address of the connection. */ + remoteAddr: Deno.NetAddr; + } + + /** A handler for HTTP requests. Consumes a request and returns a response. + * + * If a handler throws, the server calling the handler will assume the impact + * of the error is isolated to the individual request. It will catch the error + * and if necessary will close the underlying connection. + * + * @category HTTP Server + */ + export type ServeHandler = ( + request: Request, + info: ServeHandlerInfo, + ) => Response | Promise; + + /** Options which can be set when calling {@linkcode Deno.serve}. + * + * @category HTTP Server + */ + export interface ServeOptions { + /** The port to listen on. + * + * @default {8000} */ + port?: number; + + /** A literal IP address or host name that can be resolved to an IP address. + * + * __Note about `0.0.0.0`__ While listening `0.0.0.0` works on all platforms, + * the browsers on Windows don't work with the address `0.0.0.0`. + * You should show the message like `server running on localhost:8080` instead of + * `server running on 0.0.0.0:8080` if your program supports Windows. + * + * @default {"0.0.0.0"} */ + hostname?: string; + + /** An {@linkcode AbortSignal} to close the server and all connections. */ + signal?: AbortSignal; + + /** Sets `SO_REUSEPORT` on POSIX systems. */ + reusePort?: boolean; + + /** The handler to invoke when route handlers throw an error. */ + onError?: (error: unknown) => Response | Promise; + + /** The callback which is called when the server starts listening. */ + onListen?: (params: { hostname: string; port: number }) => void; + } + + /** Additional options which are used when opening a TLS (HTTPS) server. + * + * @category HTTP Server + */ + export interface ServeTlsOptions extends ServeOptions { + /** Server private key in PEM format */ + cert: string; + + /** Cert chain in PEM format */ + key: string; + } + + /** + * @category HTTP Server + */ + export interface ServeInit { + /** The handler to invoke to process each incoming request. */ + handler: ServeHandler; + } + + export interface ServeUnixOptions { + /** The unix domain socket path to listen on. */ + path: string; + + /** An {@linkcode AbortSignal} to close the server and all connections. */ + signal?: AbortSignal; + + /** The handler to invoke when route handlers throw an error. */ + onError?: (error: unknown) => Response | Promise; + + /** The callback which is called when the server starts listening. */ + onListen?: (params: { path: string }) => void; + } + + /** Information for a unix domain socket HTTP request. + * + * @category HTTP Server + */ + export interface ServeUnixHandlerInfo { + /** The remote address of the connection. */ + remoteAddr: Deno.UnixAddr; + } + + /** A handler for unix domain socket HTTP requests. Consumes a request and returns a response. + * + * If a handler throws, the server calling the handler will assume the impact + * of the error is isolated to the individual request. It will catch the error + * and if necessary will close the underlying connection. + * + * @category HTTP Server + */ + export type ServeUnixHandler = ( + request: Request, + info: ServeUnixHandlerInfo, + ) => Response | Promise; + + /** + * @category HTTP Server + */ + export interface ServeUnixInit { + /** The handler to invoke to process each incoming request. */ + handler: ServeUnixHandler; + } + + /** An instance of the server created using `Deno.serve()` API. + * + * @category HTTP Server + */ + export interface HttpServer extends AsyncDisposable { + /** A promise that resolves once server finishes - eg. when aborted using + * the signal passed to {@linkcode ServeOptions.signal}. + */ + finished: Promise; + + /** + * Make the server block the event loop from finishing. + * + * Note: the server blocks the event loop from finishing by default. + * This method is only meaningful after `.unref()` is called. + */ + ref(): void; + + /** Make the server not block the event loop from finishing. */ + unref(): void; + + /** Gracefully close the server. No more new connections will be accepted, + * while pending requests will be allowed to finish. + */ + shutdown(): Promise; + } + + /** + * @category HTTP Server + * @deprecated Use {@linkcode HttpServer} instead. + */ + export type Server = HttpServer; + + /** Serves HTTP requests with the given handler. + * + * The below example serves with the port `8000` on hostname `"127.0.0.1"`. + * + * ```ts + * Deno.serve((_req) => new Response("Hello, world")); + * ``` + * + * @category HTTP Server + */ + export function serve(handler: ServeHandler): HttpServer; + /** Serves HTTP requests with the given option bag and handler. + * + * You can specify the socket path with `path` option. + * + * ```ts + * Deno.serve( + * { path: "path/to/socket" }, + * (_req) => new Response("Hello, world") + * ); + * ``` + * + * You can stop the server with an {@linkcode AbortSignal}. The abort signal + * needs to be passed as the `signal` option in the options bag. The server + * aborts when the abort signal is aborted. To wait for the server to close, + * await the promise returned from the `Deno.serve` API. + * + * ```ts + * const ac = new AbortController(); + * + * const server = Deno.serve( + * { signal: ac.signal, path: "path/to/socket" }, + * (_req) => new Response("Hello, world") + * ); + * server.finished.then(() => console.log("Server closed")); + * + * console.log("Closing server..."); + * ac.abort(); + * ``` + * + * By default `Deno.serve` prints the message + * `Listening on path/to/socket` on listening. If you like to + * change this behavior, you can specify a custom `onListen` callback. + * + * ```ts + * Deno.serve({ + * onListen({ path }) { + * console.log(`Server started at ${path}`); + * // ... more info specific to your server .. + * }, + * path: "path/to/socket", + * }, (_req) => new Response("Hello, world")); + * ``` + * + * @category HTTP Server + */ + export function serve( + options: ServeUnixOptions, + handler: ServeUnixHandler, + ): HttpServer; + /** Serves HTTP requests with the given option bag and handler. + * + * You can specify an object with a port and hostname option, which is the + * address to listen on. The default is port `8000` on hostname `"127.0.0.1"`. + * + * You can change the address to listen on using the `hostname` and `port` + * options. The below example serves on port `3000` and hostname `"0.0.0.0"`. + * + * ```ts + * Deno.serve( + * { port: 3000, hostname: "0.0.0.0" }, + * (_req) => new Response("Hello, world") + * ); + * ``` + * + * You can stop the server with an {@linkcode AbortSignal}. The abort signal + * needs to be passed as the `signal` option in the options bag. The server + * aborts when the abort signal is aborted. To wait for the server to close, + * await the promise returned from the `Deno.serve` API. + * + * ```ts + * const ac = new AbortController(); + * + * const server = Deno.serve( + * { signal: ac.signal }, + * (_req) => new Response("Hello, world") + * ); + * server.finished.then(() => console.log("Server closed")); + * + * console.log("Closing server..."); + * ac.abort(); + * ``` + * + * By default `Deno.serve` prints the message + * `Listening on http://:/` on listening. If you like to + * change this behavior, you can specify a custom `onListen` callback. + * + * ```ts + * Deno.serve({ + * onListen({ port, hostname }) { + * console.log(`Server started at http://${hostname}:${port}`); + * // ... more info specific to your server .. + * }, + * }, (_req) => new Response("Hello, world")); + * ``` + * + * To enable TLS you must specify the `key` and `cert` options. + * + * ```ts + * const cert = "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n"; + * const key = "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n"; + * Deno.serve({ cert, key }, (_req) => new Response("Hello, world")); + * ``` + * + * @category HTTP Server + */ + export function serve( + options: ServeOptions | ServeTlsOptions, + handler: ServeHandler, + ): HttpServer; + /** Serves HTTP requests with the given option bag. + * + * You can specify an object with the path option, which is the + * unix domain socket to listen on. + * + * ```ts + * const ac = new AbortController(); + * + * const server = Deno.serve({ + * path: "path/to/socket", + * handler: (_req) => new Response("Hello, world"), + * signal: ac.signal, + * onListen({ path }) { + * console.log(`Server started at ${path}`); + * }, + * }); + * server.finished.then(() => console.log("Server closed")); + * + * console.log("Closing server..."); + * ac.abort(); + * ``` + * + * @category HTTP Server + */ + export function serve( + options: ServeUnixInit & ServeUnixOptions, + ): HttpServer; + /** Serves HTTP requests with the given option bag. + * + * You can specify an object with a port and hostname option, which is the + * address to listen on. The default is port `8000` on hostname `"127.0.0.1"`. + * + * ```ts + * const ac = new AbortController(); + * + * const server = Deno.serve({ + * port: 3000, + * hostname: "0.0.0.0", + * handler: (_req) => new Response("Hello, world"), + * signal: ac.signal, + * onListen({ port, hostname }) { + * console.log(`Server started at http://${hostname}:${port}`); + * }, + * }); + * server.finished.then(() => console.log("Server closed")); + * + * console.log("Closing server..."); + * ac.abort(); + * ``` + * + * @category HTTP Server + */ + export function serve( + options: ServeInit & (ServeOptions | ServeTlsOptions), + ): HttpServer; +} + +// Copyright 2018-2023 the Deno authors. All rights reserved. MIT license. + +// deno-lint-ignore-file no-explicit-any + +/// +/// + +/** @category Console and Debugging */ +declare interface Console { + assert(condition?: boolean, ...data: any[]): void; + clear(): void; + count(label?: string): void; + countReset(label?: string): void; + debug(...data: any[]): void; + dir(item?: any, options?: any): void; + dirxml(...data: any[]): void; + error(...data: any[]): void; + group(...data: any[]): void; + groupCollapsed(...data: any[]): void; + groupEnd(): void; + info(...data: any[]): void; + log(...data: any[]): void; + table(tabularData?: any, properties?: string[]): void; + time(label?: string): void; + timeEnd(label?: string): void; + timeLog(label?: string, ...data: any[]): void; + trace(...data: any[]): void; + warn(...data: any[]): void; + + /** This method is a noop, unless used in inspector */ + timeStamp(label?: string): void; + + /** This method is a noop, unless used in inspector */ + profile(label?: string): void; + + /** This method is a noop, unless used in inspector */ + profileEnd(label?: string): void; +} + +// Copyright 2018-2023 the Deno authors. All rights reserved. MIT license. + +// deno-lint-ignore-file no-explicit-any no-var + +/// +/// + +/** @category Web APIs */ +declare interface URLSearchParams { + /** Appends a specified key/value pair as a new search parameter. + * + * ```ts + * let searchParams = new URLSearchParams(); + * searchParams.append('name', 'first'); + * searchParams.append('name', 'second'); + * ``` + */ + append(name: string, value: string): void; + + /** Deletes search parameters that match a name, and optional value, + * from the list of all search parameters. + * + * ```ts + * let searchParams = new URLSearchParams([['name', 'value']]); + * searchParams.delete('name'); + * searchParams.delete('name', 'value'); + * ``` + */ + delete(name: string, value?: string): void; + + /** Returns all the values associated with a given search parameter + * as an array. + * + * ```ts + * searchParams.getAll('name'); + * ``` + */ + getAll(name: string): string[]; + + /** Returns the first value associated to the given search parameter. + * + * ```ts + * searchParams.get('name'); + * ``` + */ + get(name: string): string | null; + + /** Returns a boolean value indicating if a given parameter, + * or parameter and value pair, exists. + * + * ```ts + * searchParams.has('name'); + * searchParams.has('name', 'value'); + * ``` + */ + has(name: string, value?: string): boolean; + + /** Sets the value associated with a given search parameter to the + * given value. If there were several matching values, this method + * deletes the others. If the search parameter doesn't exist, this + * method creates it. + * + * ```ts + * searchParams.set('name', 'value'); + * ``` + */ + set(name: string, value: string): void; + + /** Sort all key/value pairs contained in this object in place and + * return undefined. The sort order is according to Unicode code + * points of the keys. + * + * ```ts + * searchParams.sort(); + * ``` + */ + sort(): void; + + /** Calls a function for each element contained in this object in + * place and return undefined. Optionally accepts an object to use + * as this when executing callback as second argument. + * + * ```ts + * const params = new URLSearchParams([["a", "b"], ["c", "d"]]); + * params.forEach((value, key, parent) => { + * console.log(value, key, parent); + * }); + * ``` + */ + forEach( + callbackfn: (value: string, key: string, parent: this) => void, + thisArg?: any, + ): void; + + /** Returns an iterator allowing to go through all keys contained + * in this object. + * + * ```ts + * const params = new URLSearchParams([["a", "b"], ["c", "d"]]); + * for (const key of params.keys()) { + * console.log(key); + * } + * ``` + */ + keys(): IterableIterator; + + /** Returns an iterator allowing to go through all values contained + * in this object. + * + * ```ts + * const params = new URLSearchParams([["a", "b"], ["c", "d"]]); + * for (const value of params.values()) { + * console.log(value); + * } + * ``` + */ + values(): IterableIterator; + + /** Returns an iterator allowing to go through all key/value + * pairs contained in this object. + * + * ```ts + * const params = new URLSearchParams([["a", "b"], ["c", "d"]]); + * for (const [key, value] of params.entries()) { + * console.log(key, value); + * } + * ``` + */ + entries(): IterableIterator<[string, string]>; + + /** Returns an iterator allowing to go through all key/value + * pairs contained in this object. + * + * ```ts + * const params = new URLSearchParams([["a", "b"], ["c", "d"]]); + * for (const [key, value] of params) { + * console.log(key, value); + * } + * ``` + */ + [Symbol.iterator](): IterableIterator<[string, string]>; + + /** Returns a query string suitable for use in a URL. + * + * ```ts + * searchParams.toString(); + * ``` + */ + toString(): string; + + /** Contains the number of search parameters + * + * ```ts + * searchParams.size + * ``` + */ + size: number; +} + +/** @category Web APIs */ +declare var URLSearchParams: { + readonly prototype: URLSearchParams; + new ( + init?: Iterable | Record | string, + ): URLSearchParams; +}; + +/** The URL interface represents an object providing static methods used for + * creating object URLs. + * + * @category Web APIs + */ +declare interface URL { + hash: string; + host: string; + hostname: string; + href: string; + toString(): string; + readonly origin: string; + password: string; + pathname: string; + port: string; + protocol: string; + search: string; + readonly searchParams: URLSearchParams; + username: string; + toJSON(): string; +} + +/** The URL interface represents an object providing static methods used for + * creating object URLs. + * + * @category Web APIs + */ +declare var URL: { + readonly prototype: URL; + new (url: string | URL, base?: string | URL): URL; + canParse(url: string | URL, base?: string | URL): boolean; + createObjectURL(blob: Blob): string; + revokeObjectURL(url: string): void; +}; + +/** @category Web APIs */ +declare interface URLPatternInit { + protocol?: string; + username?: string; + password?: string; + hostname?: string; + port?: string; + pathname?: string; + search?: string; + hash?: string; + baseURL?: string; +} + +/** @category Web APIs */ +declare type URLPatternInput = string | URLPatternInit; + +/** @category Web APIs */ +declare interface URLPatternComponentResult { + input: string; + groups: Record; +} + +/** `URLPatternResult` is the object returned from `URLPattern.exec`. + * + * @category Web APIs + */ +declare interface URLPatternResult { + /** The inputs provided when matching. */ + inputs: [URLPatternInit] | [URLPatternInit, string]; + + /** The matched result for the `protocol` matcher. */ + protocol: URLPatternComponentResult; + /** The matched result for the `username` matcher. */ + username: URLPatternComponentResult; + /** The matched result for the `password` matcher. */ + password: URLPatternComponentResult; + /** The matched result for the `hostname` matcher. */ + hostname: URLPatternComponentResult; + /** The matched result for the `port` matcher. */ + port: URLPatternComponentResult; + /** The matched result for the `pathname` matcher. */ + pathname: URLPatternComponentResult; + /** The matched result for the `search` matcher. */ + search: URLPatternComponentResult; + /** The matched result for the `hash` matcher. */ + hash: URLPatternComponentResult; +} + +/** + * The URLPattern API provides a web platform primitive for matching URLs based + * on a convenient pattern syntax. + * + * The syntax is based on path-to-regexp. Wildcards, named capture groups, + * regular groups, and group modifiers are all supported. + * + * ```ts + * // Specify the pattern as structured data. + * const pattern = new URLPattern({ pathname: "/users/:user" }); + * const match = pattern.exec("https://blog.example.com/users/joe"); + * console.log(match.pathname.groups.user); // joe + * ``` + * + * ```ts + * // Specify a fully qualified string pattern. + * const pattern = new URLPattern("https://example.com/books/:id"); + * console.log(pattern.test("https://example.com/books/123")); // true + * console.log(pattern.test("https://deno.land/books/123")); // false + * ``` + * + * ```ts + * // Specify a relative string pattern with a base URL. + * const pattern = new URLPattern("/article/:id", "https://blog.example.com"); + * console.log(pattern.test("https://blog.example.com/article")); // false + * console.log(pattern.test("https://blog.example.com/article/123")); // true + * ``` + * + * @category Web APIs + */ +declare interface URLPattern { + /** + * Test if the given input matches the stored pattern. + * + * The input can either be provided as an absolute URL string with an optional base, + * relative URL string with a required base, or as individual components + * in the form of an `URLPatternInit` object. + * + * ```ts + * const pattern = new URLPattern("https://example.com/books/:id"); + * + * // Test an absolute url string. + * console.log(pattern.test("https://example.com/books/123")); // true + * + * // Test a relative url with a base. + * console.log(pattern.test("/books/123", "https://example.com")); // true + * + * // Test an object of url components. + * console.log(pattern.test({ pathname: "/books/123" })); // true + * ``` + */ + test(input: URLPatternInput, baseURL?: string): boolean; + + /** + * Match the given input against the stored pattern. + * + * The input can either be provided as an absolute URL string with an optional base, + * relative URL string with a required base, or as individual components + * in the form of an `URLPatternInit` object. + * + * ```ts + * const pattern = new URLPattern("https://example.com/books/:id"); + * + * // Match an absolute url string. + * let match = pattern.exec("https://example.com/books/123"); + * console.log(match.pathname.groups.id); // 123 + * + * // Match a relative url with a base. + * match = pattern.exec("/books/123", "https://example.com"); + * console.log(match.pathname.groups.id); // 123 + * + * // Match an object of url components. + * match = pattern.exec({ pathname: "/books/123" }); + * console.log(match.pathname.groups.id); // 123 + * ``` + */ + exec(input: URLPatternInput, baseURL?: string): URLPatternResult | null; + + /** The pattern string for the `protocol`. */ + readonly protocol: string; + /** The pattern string for the `username`. */ + readonly username: string; + /** The pattern string for the `password`. */ + readonly password: string; + /** The pattern string for the `hostname`. */ + readonly hostname: string; + /** The pattern string for the `port`. */ + readonly port: string; + /** The pattern string for the `pathname`. */ + readonly pathname: string; + /** The pattern string for the `search`. */ + readonly search: string; + /** The pattern string for the `hash`. */ + readonly hash: string; +} + +/** + * The URLPattern API provides a web platform primitive for matching URLs based + * on a convenient pattern syntax. + * + * The syntax is based on path-to-regexp. Wildcards, named capture groups, + * regular groups, and group modifiers are all supported. + * + * ```ts + * // Specify the pattern as structured data. + * const pattern = new URLPattern({ pathname: "/users/:user" }); + * const match = pattern.exec("https://blog.example.com/users/joe"); + * console.log(match.pathname.groups.user); // joe + * ``` + * + * ```ts + * // Specify a fully qualified string pattern. + * const pattern = new URLPattern("https://example.com/books/:id"); + * console.log(pattern.test("https://example.com/books/123")); // true + * console.log(pattern.test("https://deno.land/books/123")); // false + * ``` + * + * ```ts + * // Specify a relative string pattern with a base URL. + * const pattern = new URLPattern("/article/:id", "https://blog.example.com"); + * console.log(pattern.test("https://blog.example.com/article")); // false + * console.log(pattern.test("https://blog.example.com/article/123")); // true + * ``` + * + * @category Web APIs + */ +declare var URLPattern: { + readonly prototype: URLPattern; + new (input: URLPatternInput, baseURL?: string): URLPattern; +}; + +// Copyright 2018-2023 the Deno authors. All rights reserved. MIT license. + +// deno-lint-ignore-file no-explicit-any no-var + +/// +/// + +/** @category Web APIs */ +declare interface DOMException extends Error { + readonly name: string; + readonly message: string; + readonly code: number; + readonly INDEX_SIZE_ERR: 1; + readonly DOMSTRING_SIZE_ERR: 2; + readonly HIERARCHY_REQUEST_ERR: 3; + readonly WRONG_DOCUMENT_ERR: 4; + readonly INVALID_CHARACTER_ERR: 5; + readonly NO_DATA_ALLOWED_ERR: 6; + readonly NO_MODIFICATION_ALLOWED_ERR: 7; + readonly NOT_FOUND_ERR: 8; + readonly NOT_SUPPORTED_ERR: 9; + readonly INUSE_ATTRIBUTE_ERR: 10; + readonly INVALID_STATE_ERR: 11; + readonly SYNTAX_ERR: 12; + readonly INVALID_MODIFICATION_ERR: 13; + readonly NAMESPACE_ERR: 14; + readonly INVALID_ACCESS_ERR: 15; + readonly VALIDATION_ERR: 16; + readonly TYPE_MISMATCH_ERR: 17; + readonly SECURITY_ERR: 18; + readonly NETWORK_ERR: 19; + readonly ABORT_ERR: 20; + readonly URL_MISMATCH_ERR: 21; + readonly QUOTA_EXCEEDED_ERR: 22; + readonly TIMEOUT_ERR: 23; + readonly INVALID_NODE_TYPE_ERR: 24; + readonly DATA_CLONE_ERR: 25; +} + +/** @category Web APIs */ +declare var DOMException: { + readonly prototype: DOMException; + new (message?: string, name?: string): DOMException; + readonly INDEX_SIZE_ERR: 1; + readonly DOMSTRING_SIZE_ERR: 2; + readonly HIERARCHY_REQUEST_ERR: 3; + readonly WRONG_DOCUMENT_ERR: 4; + readonly INVALID_CHARACTER_ERR: 5; + readonly NO_DATA_ALLOWED_ERR: 6; + readonly NO_MODIFICATION_ALLOWED_ERR: 7; + readonly NOT_FOUND_ERR: 8; + readonly NOT_SUPPORTED_ERR: 9; + readonly INUSE_ATTRIBUTE_ERR: 10; + readonly INVALID_STATE_ERR: 11; + readonly SYNTAX_ERR: 12; + readonly INVALID_MODIFICATION_ERR: 13; + readonly NAMESPACE_ERR: 14; + readonly INVALID_ACCESS_ERR: 15; + readonly VALIDATION_ERR: 16; + readonly TYPE_MISMATCH_ERR: 17; + readonly SECURITY_ERR: 18; + readonly NETWORK_ERR: 19; + readonly ABORT_ERR: 20; + readonly URL_MISMATCH_ERR: 21; + readonly QUOTA_EXCEEDED_ERR: 22; + readonly TIMEOUT_ERR: 23; + readonly INVALID_NODE_TYPE_ERR: 24; + readonly DATA_CLONE_ERR: 25; +}; + +/** @category DOM Events */ +declare interface EventInit { + bubbles?: boolean; + cancelable?: boolean; + composed?: boolean; +} + +/** An event which takes place in the DOM. + * + * @category DOM Events + */ +declare interface Event { + /** Returns true or false depending on how event was initialized. True if + * event goes through its target's ancestors in reverse tree order, and + * false otherwise. */ + readonly bubbles: boolean; + cancelBubble: boolean; + /** Returns true or false depending on how event was initialized. Its return + * value does not always carry meaning, but true can indicate that part of the + * operation during which event was dispatched, can be canceled by invoking + * the preventDefault() method. */ + readonly cancelable: boolean; + /** Returns true or false depending on how event was initialized. True if + * event invokes listeners past a ShadowRoot node that is the root of its + * target, and false otherwise. */ + readonly composed: boolean; + /** Returns the object whose event listener's callback is currently being + * invoked. */ + readonly currentTarget: EventTarget | null; + /** Returns true if preventDefault() was invoked successfully to indicate + * cancellation, and false otherwise. */ + readonly defaultPrevented: boolean; + /** Returns the event's phase, which is one of NONE, CAPTURING_PHASE, + * AT_TARGET, and BUBBLING_PHASE. */ + readonly eventPhase: number; + /** Returns true if event was dispatched by the user agent, and false + * otherwise. */ + readonly isTrusted: boolean; + /** Returns the object to which event is dispatched (its target). */ + readonly target: EventTarget | null; + /** Returns the event's timestamp as the number of milliseconds measured + * relative to the time origin. */ + readonly timeStamp: number; + /** Returns the type of event, e.g. "click", "hashchange", or "submit". */ + readonly type: string; + /** Returns the invocation target objects of event's path (objects on which + * listeners will be invoked), except for any nodes in shadow trees of which + * the shadow root's mode is "closed" that are not reachable from event's + * currentTarget. */ + composedPath(): EventTarget[]; + /** If invoked when the cancelable attribute value is true, and while + * executing a listener for the event with passive set to false, signals to + * the operation that caused event to be dispatched that it needs to be + * canceled. */ + preventDefault(): void; + /** Invoking this method prevents event from reaching any registered event + * listeners after the current one finishes running and, when dispatched in a + * tree, also prevents event from reaching any other objects. */ + stopImmediatePropagation(): void; + /** When dispatched in a tree, invoking this method prevents event from + * reaching any objects other than the current object. */ + stopPropagation(): void; + readonly AT_TARGET: number; + readonly BUBBLING_PHASE: number; + readonly CAPTURING_PHASE: number; + readonly NONE: number; +} + +/** An event which takes place in the DOM. + * + * @category DOM Events + */ +declare var Event: { + readonly prototype: Event; + new (type: string, eventInitDict?: EventInit): Event; + readonly AT_TARGET: number; + readonly BUBBLING_PHASE: number; + readonly CAPTURING_PHASE: number; + readonly NONE: number; +}; + +/** + * EventTarget is a DOM interface implemented by objects that can receive events + * and may have listeners for them. + * + * @category DOM Events + */ +declare interface EventTarget { + /** Appends an event listener for events whose type attribute value is type. + * The callback argument sets the callback that will be invoked when the event + * is dispatched. + * + * The options argument sets listener-specific options. For compatibility this + * can be a boolean, in which case the method behaves exactly as if the value + * was specified as options's capture. + * + * When set to true, options's capture prevents callback from being invoked + * when the event's eventPhase attribute value is BUBBLING_PHASE. When false + * (or not present), callback will not be invoked when event's eventPhase + * attribute value is CAPTURING_PHASE. Either way, callback will be invoked if + * event's eventPhase attribute value is AT_TARGET. + * + * When set to true, options's passive indicates that the callback will not + * cancel the event by invoking preventDefault(). This is used to enable + * performance optimizations described in § 2.8 Observing event listeners. + * + * When set to true, options's once indicates that the callback will only be + * invoked once after which the event listener will be removed. + * + * The event listener is appended to target's event listener list and is not + * appended if it has the same type, callback, and capture. */ + addEventListener( + type: string, + listener: EventListenerOrEventListenerObject | null, + options?: boolean | AddEventListenerOptions, + ): void; + /** Dispatches a synthetic event to event target and returns true if either + * event's cancelable attribute value is false or its preventDefault() method + * was not invoked, and false otherwise. */ + dispatchEvent(event: Event): boolean; + /** Removes the event listener in target's event listener list with the same + * type, callback, and options. */ + removeEventListener( + type: string, + callback: EventListenerOrEventListenerObject | null, + options?: EventListenerOptions | boolean, + ): void; +} + +/** + * EventTarget is a DOM interface implemented by objects that can receive events + * and may have listeners for them. + * + * @category DOM Events + */ +declare var EventTarget: { + readonly prototype: EventTarget; + new (): EventTarget; +}; + +/** @category DOM Events */ +declare interface EventListener { + (evt: Event): void | Promise; +} + +/** @category DOM Events */ +declare interface EventListenerObject { + handleEvent(evt: Event): void | Promise; +} + +/** @category DOM Events */ +declare type EventListenerOrEventListenerObject = + | EventListener + | EventListenerObject; + +/** @category DOM Events */ +declare interface AddEventListenerOptions extends EventListenerOptions { + once?: boolean; + passive?: boolean; + signal?: AbortSignal; +} + +/** @category DOM Events */ +declare interface EventListenerOptions { + capture?: boolean; +} + +/** @category DOM Events */ +declare interface ProgressEventInit extends EventInit { + lengthComputable?: boolean; + loaded?: number; + total?: number; +} + +/** Events measuring progress of an underlying process, like an HTTP request + * (for an XMLHttpRequest, or the loading of the underlying resource of an + * ,