diff --git a/CHANGELOG.md b/CHANGELOG.md index b9f6d533..0e93656e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,7 @@ ## Unreleased +- Add `Symbol.asyncDispose` to clients, sessions, and operations, delegating to `close()`. Use `asyncDisposable()` with interface-typed results in TypeScript; existing interfaces and factory return types remain unchanged. (#331) - CloudFetch retry-exhaustion errors now identify the download and the last failure: the `RetryError` message reads `CloudFetch result download failed: (last error: )`. `` is `HTTP : ` (or `HTTP ` when the status text is empty) for HTTP failures, and `network error `, `network error ()` (e.g. `aborted`, when there is no `code`) or a bare `network error` for network failures (the raw network-error message, which can contain the presigned URL, is not copied). If no cause can be determined, the ` (last error: …)` suffix is omitted. The `RetryError` instance, `errorCode` and `payload` (including the node-fetch `Request` / `Response`) are unchanged. (#471) - Report untyped NULL columns as STRING in kernel result metadata, matching Thrift. (#470) - Reject non-scalar query parameter values at bind time with a `ParameterError` on both the Thrift and kernel backends, instead of stringifying them (which could leave a Thrift operation stuck before FINISHED). Newly rejected on the Thrift backend: arrays, plain objects, boxed primitives (e.g. `new String('x')`, `new Number(1)`), functions, symbols, and a `DBSQLParameter` that wraps another `DBSQLParameter`. Primitives, `Date`, `Int64`, and `DBSQLParameter` are still accepted. diff --git a/README.md b/README.md index 638cbf78..0fc3eafc 100644 --- a/README.md +++ b/README.md @@ -51,6 +51,35 @@ client }); ``` +### Automatic cleanup with `await using` + +The client, sessions, and operations implement `Symbol.asyncDispose`. On scope exit, `await using` calls `close()`, +including when the block throws. Disposal follows the existing `close()` behavior, and cleanup errors propagate. +If both the block and a disposal fail, `await using` throws a `SuppressedError` containing both errors. +Node.js 24+ supports +`await using` natively; on Node.js 22, compile it with TypeScript 5.2+. TypeScript also needs the disposable +declarations (such as the global `AsyncDisposable` type) to compile `await using`: if your typings don't already +provide them, add `"esnext.disposable"` (or `"esnext"`) to `compilerOptions.lib` in your `tsconfig.json`, otherwise the +example below can fail to compile even with TypeScript 5.2+. + +`openSession()` and the session's operation methods are typed as returning the `IDBSQLSession` and `IOperation` +interfaces, which don't require `Symbol.asyncDispose` (so existing custom implementations keep compiling). In +TypeScript, wrap their results with `asyncDisposable()`: it returns the driver's own sessions and operations unchanged, +typed as disposable. + +```typescript +import { DBSQLClient, asyncDisposable } from '@databricks/sql'; + +async function main() { + await using client = new DBSQLClient(); + await client.connect({ host, path, token }); + + await using session = asyncDisposable(await client.openSession()); + await using operation = asyncDisposable(await session.executeStatement('SELECT "Hello, World!"')); + console.table(await operation.fetchAll()); +} // disposes `operation`, `session`, then `client` +``` + ## Configuration See [CONNECTION_PARAMETERS.md](CONNECTION_PARAMETERS.md) for every connection, diff --git a/lib/DBSQLClient.ts b/lib/DBSQLClient.ts index cbf359df..a287d4f0 100644 --- a/lib/DBSQLClient.ts +++ b/lib/DBSQLClient.ts @@ -43,6 +43,8 @@ import MetricsAggregator from './telemetry/MetricsAggregator'; import { DriverConfiguration, DRIVER_NAME, TelemetryEventType, DEFAULT_TELEMETRY_CONFIG } from './telemetry/types'; import { safeEmit, isTelemetryDisabledByEnv } from './telemetry/telemetryUtils'; import driverVersion from './version'; +// Declares `Symbol.asyncDispose` for the emitted typings of `[Symbol.asyncDispose]()` below +import './contracts/asyncDispose'; function prependSlash(str: string): string { if (str.length > 0 && str.charAt(0) !== '/') { @@ -951,6 +953,13 @@ export default class DBSQLClient extends EventEmitter implements IDBSQLClient, I this.authProvider = undefined; } + /** + * Closes the client (see {@link close}); called by `await using client = ...` + */ + public async [Symbol.asyncDispose](): Promise { + await this.close(); + } + public getConfig(): ClientConfig { return this.config; } diff --git a/lib/DBSQLOperation.ts b/lib/DBSQLOperation.ts index 1ec1922c..0f693991 100644 --- a/lib/DBSQLOperation.ts +++ b/lib/DBSQLOperation.ts @@ -22,6 +22,8 @@ import { synthesizeThriftStatus, synthesizeThriftResultSetMetadata } from './thr import { mapOperationTypeToTelemetryType } from './telemetry/telemetryTypeMappers'; import ExceptionClassifier from './telemetry/ExceptionClassifier'; import { safeEmit } from './telemetry/telemetryUtils'; +// Declares `Symbol.asyncDispose` for the emitted typings of `[Symbol.asyncDispose]()` below +import './contracts/asyncDispose'; function mapNeutralResultFormatToTelemetryType(resultFormat?: ResultFormat): string | undefined { switch (resultFormat) { @@ -233,6 +235,14 @@ export default class DBSQLOperation implements IOperation { return result; } + /** + * Closes operation (see {@link close}); called by `await using operation = ...` + * @throws {StatusError} + */ + public async [Symbol.asyncDispose](): Promise { + await this.close(); + } + public async finished(options?: FinishedOptions): Promise { return this.withErrorTelemetry(async () => { await this.failIfClosed(); diff --git a/lib/DBSQLSession.ts b/lib/DBSQLSession.ts index 18588ac3..cc567e64 100644 --- a/lib/DBSQLSession.ts +++ b/lib/DBSQLSession.ts @@ -29,6 +29,8 @@ import ISessionBackend from './contracts/ISessionBackend'; import IOperationBackend from './contracts/IOperationBackend'; import { numberToInt64 as numberToInt64Impl } from './thrift-backend/ThriftSessionBackend'; import { safeEmit } from './telemetry/telemetryUtils'; +// Declares `Symbol.asyncDispose` for the emitted typings of `[Symbol.asyncDispose]()` below +import './contracts/asyncDispose'; // Explicitly promisify a callback-style `pipeline` because `node:stream/promises` is not available in Node 14 const pipeline = util.promisify(stream.pipeline); @@ -365,6 +367,14 @@ export default class DBSQLSession implements IDBSQLSession { } } + /** + * Closes the session (see {@link close}); called by `await using session = ...` + * @public + */ + public async [Symbol.asyncDispose](): Promise { + await this.close(); + } + private wrapOperation(backend: IOperationBackend): DBSQLOperation { const operation = new DBSQLOperation({ backend, diff --git a/lib/asyncDisposable.ts b/lib/asyncDisposable.ts new file mode 100644 index 00000000..2697a240 --- /dev/null +++ b/lib/asyncDisposable.ts @@ -0,0 +1,40 @@ +// Declares `Symbol.asyncDispose` for the emitted typings below +import './contracts/asyncDispose'; + +/** + * A closeable resource that can also be bound with `await using`. + */ +export type AsyncDisposableResource = T & { + [Symbol.asyncDispose](): Promise; +}; + +/** + * Returns `resource` typed as async-disposable, so that it can be bound with `await using`. + * + * `connect()`, `openSession()` and the session's operation methods return the `IDBSQLClient` / + * `IDBSQLSession` / `IOperation` interfaces, which don't require `Symbol.asyncDispose` (so custom + * implementations and subclasses written before it was added keep compiling). The driver's own clients, + * sessions, and operations implement it, so they are returned unchanged. A custom implementation without it gets a non-enumerable + * `[Symbol.asyncDispose]()` that calls its `close()` (this throws a `TypeError` if the object isn't + * extensible, e.g. a frozen object). + * + * @example + * await using session = asyncDisposable(await client.openSession()); + * await using operation = asyncDisposable(await session.executeStatement('SELECT 1')); + */ +export default function asyncDisposable }>( + resource: T, +): AsyncDisposableResource { + const candidate = resource as T & { [Symbol.asyncDispose]?: unknown }; + if (typeof candidate[Symbol.asyncDispose] !== 'function') { + Object.defineProperty(resource, Symbol.asyncDispose, { + configurable: true, + writable: true, + enumerable: false, + value: async function asyncDispose(this: T): Promise { + await this.close(); + }, + }); + } + return resource as AsyncDisposableResource; +} diff --git a/lib/contracts/asyncDispose.ts b/lib/contracts/asyncDispose.ts new file mode 100644 index 00000000..43c82458 --- /dev/null +++ b/lib/contracts/asyncDispose.ts @@ -0,0 +1,9 @@ +// Declares the built-in `Symbol.asyncDispose` (identical to the declaration in TypeScript's +// `esnext.disposable` lib and in `@types/node`) so the published typings work without either. +declare global { + interface SymbolConstructor { + readonly asyncDispose: unique symbol; + } +} + +export {}; diff --git a/lib/index.ts b/lib/index.ts index a2b90c9c..20d28b4f 100644 --- a/lib/index.ts +++ b/lib/index.ts @@ -23,6 +23,9 @@ import { LogLevel } from './contracts/IDBSQLLogger'; // Re-export types for TypeScript users export type { default as ITokenProvider } from './connection/auth/tokenProvider/ITokenProvider'; +export { default as asyncDisposable } from './asyncDisposable'; +export type { AsyncDisposableResource } from './asyncDisposable'; + export { LOG_FILE_UNAVAILABLE_WARNING_CODE } from './DBSQLLogger'; export { CircuitBreakerOpenError, CIRCUIT_BREAKER_OPEN_CODE } from './telemetry/CircuitBreaker'; export { TelemetryTerminalError } from './telemetry/DatabricksTelemetryExporter'; diff --git a/tests/unit/DBSQLClient.test.ts b/tests/unit/DBSQLClient.test.ts index a3727754..f955e57d 100644 --- a/tests/unit/DBSQLClient.test.ts +++ b/tests/unit/DBSQLClient.test.ts @@ -579,6 +579,49 @@ describe('DBSQLClient.close', () => { }); }); +describe('DBSQLClient[Symbol.asyncDispose]', () => { + it('should close the client and its sessions', async () => { + const client = new DBSQLClient(); + const thriftClient = sinon.spy(new ThriftClientStub()); + + client['client'] = thriftClient; + client['connectionProvider'] = new ConnectionProviderStub(); + client['authProvider'] = new AuthProviderStub(); + client['backend'] = new ThriftBackend({ context: client, onConnectionEvent: () => {} }); + + const session = await client.openSession(); + if (!(session instanceof DBSQLSession)) { + throw new Error('Assertion error: expected session to be DBSQLSession'); + } + const closeSpy = sinon.spy(client, 'close'); + + const result = await client[Symbol.asyncDispose](); + expect(result).to.be.undefined; + expect(closeSpy.calledOnce).to.be.true; + expect(session['isOpen']).to.be.false; + expect(thriftClient.CloseSession.calledOnce).to.be.true; + expect(client['backend']).to.be.undefined; + expect(client['client']).to.be.undefined; + }); + + it('should be a no-op for a closed or never-connected client', async () => { + const closedClient = new DBSQLClient(); + const thriftClient = sinon.spy(new ThriftClientStub()); + closedClient['client'] = thriftClient; + closedClient['connectionProvider'] = new ConnectionProviderStub(); + closedClient['authProvider'] = new AuthProviderStub(); + closedClient['backend'] = new ThriftBackend({ context: closedClient, onConnectionEvent: () => {} }); + await closedClient.openSession(); + + await closedClient.close(); + await closedClient[Symbol.asyncDispose](); + await closedClient[Symbol.asyncDispose](); + expect(thriftClient.CloseSession.calledOnce).to.be.true; + + await new DBSQLClient()[Symbol.asyncDispose](); + }); +}); + describe('DBSQLClient.createAuthProvider', () => { it('should use access token auth method', () => { const client = new DBSQLClient(); diff --git a/tests/unit/DBSQLOperation.test.ts b/tests/unit/DBSQLOperation.test.ts index f9195105..078fe639 100644 --- a/tests/unit/DBSQLOperation.test.ts +++ b/tests/unit/DBSQLOperation.test.ts @@ -418,6 +418,46 @@ describe('DBSQLOperation', () => { }); }); + describe('Symbol.asyncDispose', () => { + it('should close the operation', async () => { + const context = new ClientContextStub(); + const driver = sinon.spy(context.driver); + const operation = createOperationForTest({ handle: operationHandleStub({ hasResultSet: true }), context }); + + const result = await operation[Symbol.asyncDispose](); + expect(result).to.be.undefined; + expect(operation['closed']).to.be.true; + expect(driver.closeOperation.callCount).to.be.equal(1); + }); + + it('should be a no-op for an already closed operation', async () => { + const context = new ClientContextStub(); + const driver = sinon.spy(context.driver); + const closed = createOperationForTest({ handle: operationHandleStub({ hasResultSet: true }), context }); + + await closed.close(); + await closed[Symbol.asyncDispose](); + await closed[Symbol.asyncDispose](); + expect(driver.closeOperation.callCount).to.be.equal(1); + }); + + it('should propagate close errors', async () => { + const context = new ClientContextStub(); + context.driver.closeOperationResp.status.statusCode = TStatusCode.ERROR_STATUS; + const operation = createOperationForTest({ handle: operationHandleStub({ hasResultSet: true }), context }); + + try { + await operation[Symbol.asyncDispose](); + expect.fail('It should throw a StatusError'); + } catch (e) { + if (e instanceof AssertionError) { + throw e; + } + expect(e).to.be.instanceOf(StatusError); + } + }); + }); + describe('finished', () => { [TOperationState.INITIALIZED_STATE, TOperationState.RUNNING_STATE, TOperationState.PENDING_STATE].forEach( (operationState) => { diff --git a/tests/unit/DBSQLSession.test.ts b/tests/unit/DBSQLSession.test.ts index ce782207..36ab26e9 100644 --- a/tests/unit/DBSQLSession.test.ts +++ b/tests/unit/DBSQLSession.test.ts @@ -760,4 +760,49 @@ describe('DBSQLSession', () => { ); }); }); + + describe('Symbol.asyncDispose', () => { + it('should close the session and its operations', async () => { + const context = new ClientContextStub(); + const driver = sinon.spy(context.driver); + const session = createSessionForTest({ handle: sessionHandleStub, context }); + const operation = await session.executeStatement('SELECT * FROM table'); + if (!(operation instanceof DBSQLOperation)) { + expect.fail('Assertion error: operation is not a DBSQLOperation'); + } + + const result = await session[Symbol.asyncDispose](); + expect(result).to.be.undefined; + expect(session['isOpen']).to.be.false; + expect(operation['closed']).to.be.true; + expect(driver.closeSession.callCount).to.eq(1); + }); + + it('should be a no-op for an already closed session', async () => { + const context = new ClientContextStub(); + const driver = sinon.spy(context.driver); + const session = createSessionForTest({ handle: sessionHandleStub, context }); + + await session.close(); + await session[Symbol.asyncDispose](); + await session[Symbol.asyncDispose](); + expect(driver.closeSession.callCount).to.eq(1); + }); + + it('should propagate close errors', async () => { + const context = new ClientContextStub(); + const session = createSessionForTest({ handle: sessionHandleStub, context }); + const error = new Error('close failed'); + sinon.stub(context.driver, 'closeSession').rejects(error); + + try { + await session[Symbol.asyncDispose](); + expect.fail('It should throw an error'); + } catch (e) { + expect(e).to.equal(error); + } + // A failed close still marks the session closed, so disposing again is a no-op. + await session[Symbol.asyncDispose](); + }); + }); }); diff --git a/tests/unit/asyncDisposable.test.ts b/tests/unit/asyncDisposable.test.ts new file mode 100644 index 00000000..6a65bcc9 --- /dev/null +++ b/tests/unit/asyncDisposable.test.ts @@ -0,0 +1,69 @@ +import { expect } from 'chai'; +import sinon from 'sinon'; +import asyncDisposable from '../../lib/asyncDisposable'; +import * as driver from '../../lib'; +import DBSQLClient from '../../lib/DBSQLClient'; +import Status from '../../lib/dto/Status'; +import OperationStub from './.stubs/OperationStub'; +import ClientContextStub from './.stubs/ClientContextStub'; +import { createSessionForTest } from './.stubs/createSessionForTest'; + +describe('asyncDisposable', () => { + it('is exported from the package entry point', () => { + expect(driver.asyncDisposable).to.equal(asyncDisposable); + }); + + it("returns the driver's own resources unchanged", async () => { + const client = new DBSQLClient(); + const session = createSessionForTest({ + handle: { sessionId: { guid: Buffer.alloc(16), secret: Buffer.alloc(16) } }, + context: new ClientContextStub(), + }); + const operation = await session.executeStatement('SELECT 1'); + + for (const resource of [client, session, operation]) { + const dispose = (resource as any)[Symbol.asyncDispose]; + expect(asyncDisposable(resource)).to.equal(resource); + expect((resource as any)[Symbol.asyncDispose]).to.equal(dispose); + } + + const closeSpy = sinon.spy(operation, 'close'); + await asyncDisposable(operation)[Symbol.asyncDispose](); + expect(closeSpy.calledOnce).to.be.true; + }); + + it('adds a non-enumerable disposer that closes a custom implementation', async () => { + const operation = new OperationStub([]); + const disposable = asyncDisposable(operation); + + expect(disposable).to.equal(operation); + expect(Object.getOwnPropertyDescriptor(operation, Symbol.asyncDispose)?.enumerable).to.be.false; + expect(await disposable[Symbol.asyncDispose]()).to.be.undefined; + expect(operation.closed).to.be.true; + }); + + it('keeps an existing disposer of a custom implementation', async () => { + const dispose = sinon.stub().resolves(); + const resource = { close: async () => Status.success(), [Symbol.asyncDispose]: dispose }; + + await asyncDisposable(resource)[Symbol.asyncDispose](); + expect(dispose.calledOnce).to.be.true; + }); + + it('propagates close errors from the added disposer', async () => { + const error = new Error('close failed'); + const resource = { close: () => Promise.reject(error) }; + + try { + await asyncDisposable(resource)[Symbol.asyncDispose](); + expect.fail('It should throw an error'); + } catch (e) { + expect(e).to.equal(error); + } + }); + + it('throws a TypeError for a non-extensible custom implementation', () => { + const resource = Object.freeze({ close: async () => Status.success() }); + expect(() => asyncDisposable(resource)).to.throw(TypeError); + }); +}); diff --git a/tests/unit/asyncDispose.types.test.ts b/tests/unit/asyncDispose.types.test.ts new file mode 100644 index 00000000..ee30d5f4 --- /dev/null +++ b/tests/unit/asyncDispose.types.test.ts @@ -0,0 +1,289 @@ +import path from 'path'; +import { expect } from 'chai'; +import ts from 'typescript'; + +// Consumer type tests for `Symbol.asyncDispose` support: compile small consumer programs against the +// declarations emitted from `lib/` (with the `tsconfig.build.json` settings used to build `dist/`). The +// declarations and the consumer sources are kept in memory; nothing is written to disk. + +const repoRoot = path.resolve(__dirname, '../..'); +// Siblings of `lib/`, so the emitted `../thrift/...` imports resolve like they do from `dist/` +const declarationsDir = path.join(repoRoot, '.types-test-dist'); +const consumerDir = path.join(repoRoot, '.types-test-consumer'); + +const virtualFiles = new Map(); + +function emitDeclarations() { + const configPath = path.join(repoRoot, 'tsconfig.build.json'); + const { config, error } = ts.readConfigFile(configPath, ts.sys.readFile); + if (error) { + throw new Error(ts.flattenDiagnosticMessageText(error.messageText, '\n')); + } + const parsed = ts.parseJsonConfigFileContent( + config, + ts.sys, + repoRoot, + { outDir: declarationsDir, emitDeclarationOnly: true, sourceMap: false, declarationMap: false }, + configPath, + ); + const program = ts.createProgram({ rootNames: parsed.fileNames, options: parsed.options }); + const result = program.emit(undefined, (fileName, text) => { + virtualFiles.set(path.resolve(fileName), text); + }); + const diagnostics = [...ts.getPreEmitDiagnostics(program), ...result.diagnostics]; + expect(formatDiagnostics(diagnostics)).to.equal(''); + expect(virtualFiles.has(path.join(declarationsDir, 'index.d.ts'))).to.be.true; +} + +function formatDiagnostics(diagnostics: ReadonlyArray): string { + return ts.formatDiagnostics(diagnostics, { + getCanonicalFileName: (fileName) => fileName, + getCurrentDirectory: () => repoRoot, + getNewLine: () => '\n', + }); +} + +function isVirtual(fileName: string): boolean { + const resolved = path.resolve(fileName); + return [declarationsDir, consumerDir].some((dir) => resolved === dir || resolved.startsWith(`${dir}${path.sep}`)); +} + +type ConsumerLib = 'es2018' | 'esnext.disposable'; + +// `lib.dom.d.ts` is part of TypeScript's default libs and is needed by `@types/thrift` (`XMLHttpRequest`) +const consumerOptions: Record = { + // No disposable declarations at all: neither TypeScript's lib nor `@types/node` (the installed 18.11 typings + // predate `Symbol.asyncDispose`) declare it, so only the driver's own declaration shim can. + es2018: { target: ts.ScriptTarget.ES2018, lib: ['lib.es2018.d.ts', 'lib.dom.d.ts'] }, + 'esnext.disposable': { + target: ts.ScriptTarget.ES2022, + lib: ['lib.es2022.d.ts', 'lib.esnext.disposable.d.ts', 'lib.dom.d.ts'], + }, +}; + +/** Type-checks `source` as a consumer of the published typings and returns the formatted errors */ +function compileConsumer(source: string, consumerLib: ConsumerLib): string { + const fileName = path.join(consumerDir, 'consumer.ts'); + virtualFiles.set(fileName, source); + + const options: ts.CompilerOptions = { + ...consumerOptions[consumerLib], + module: ts.ModuleKind.CommonJS, + moduleResolution: ts.ModuleResolutionKind.Node10, + strict: true, + esModuleInterop: true, + noEmit: true, + skipLibCheck: false, + baseUrl: repoRoot, + paths: { + '@databricks/sql': [path.join(declarationsDir, 'index.d.ts')], + '@databricks/sql/dist/*': [path.join(declarationsDir, '*')], + }, + typeRoots: [path.join(repoRoot, 'node_modules', '@types')], + types: ['node'], + }; + + const host = ts.createCompilerHost(options); + const { fileExists, readFile, getSourceFile, directoryExists, realpath } = host; + host.fileExists = (name) => (isVirtual(name) ? virtualFiles.has(path.resolve(name)) : fileExists.call(host, name)); + host.readFile = (name) => (isVirtual(name) ? virtualFiles.get(path.resolve(name)) : readFile.call(host, name)); + host.directoryExists = (name) => { + if (isVirtual(name)) { + const dir = `${path.resolve(name)}${path.sep}`; + return [...virtualFiles.keys()].some((file) => file.startsWith(dir)); + } + return directoryExists ? directoryExists.call(host, name) : true; + }; + host.realpath = (name) => (isVirtual(name) || !realpath ? name : realpath.call(host, name)); + host.getSourceFile = (name, languageVersion, onError) => { + if (isVirtual(name)) { + const text = virtualFiles.get(path.resolve(name)); + return text === undefined ? undefined : ts.createSourceFile(name, text, languageVersion); + } + return getSourceFile.call(host, name, languageVersion, onError); + }; + + const program = ts.createProgram({ rootNames: [fileName], options, host }); + return formatDiagnostics(ts.getPreEmitDiagnostics(program)); +} + +// Implementations and subclasses written against the contracts before async disposal was added +const legacyConsumer = ` +import { Readable } from 'stream'; +import { DBSQLClient, DBSQLSession } from '@databricks/sql'; +import IDBSQLClient, { ConnectionOptions, OpenSessionRequest } from '@databricks/sql/dist/contracts/IDBSQLClient'; +import IDBSQLSession, { ExecuteStatementOptions, CatalogsRequest } from '@databricks/sql/dist/contracts/IDBSQLSession'; +import IOperation, { + IOperationChunksIterator, + IOperationRowsIterator, +} from '@databricks/sql/dist/contracts/IOperation'; +import Status from '@databricks/sql/dist/dto/Status'; + +function notImplemented(): never { + throw new Error('Not implemented'); +} + +const operationMock: IOperation = { + id: 'operation', + fetchChunk: async () => [], + fetchAll: async () => [], + status: async () => notImplemented(), + cancel: async () => Status.success(), + close: async () => Status.success(), + finished: async () => {}, + hasMoreRows: async () => false, + getSchema: async () => null, + getResultMetadata: async () => notImplemented(), + iterateChunks: (): IOperationChunksIterator => notImplemented(), + iterateRows: (): IOperationRowsIterator => notImplemented(), + toNodeStream: (): Readable => notImplemented(), +}; + +class LegacySession implements IDBSQLSession { + public readonly id = 'session'; + public getInfo = async () => notImplemented(); + public executeStatement = async (): Promise => operationMock; + public getTypeInfo = async (): Promise => operationMock; + public getCatalogs = async (): Promise => operationMock; + public getSchemas = async (): Promise => operationMock; + public getTables = async (): Promise => operationMock; + public getTableTypes = async (): Promise => operationMock; + public getColumns = async (): Promise => operationMock; + public getFunctions = async (): Promise => operationMock; + public getPrimaryKeys = async (): Promise => operationMock; + public getCrossReference = async (): Promise => operationMock; + public close = async () => Status.success(); +} + +class LegacyClient implements IDBSQLClient { + public async connect(): Promise { + return this; + } + + public async openSession(): Promise { + return new LegacySession(); + } + + public async close(): Promise {} +} + +// Subclasses overriding the factories with their original return types +class LoggingClient extends DBSQLClient { + public async connect(options: ConnectionOptions): Promise { + return super.connect(options); + } + + public async openSession(request?: OpenSessionRequest): Promise { + return super.openSession(request); + } +} + +class LoggingSession extends DBSQLSession { + public async executeStatement(statement: string, options?: ExecuteStatementOptions): Promise { + return super.executeStatement(statement, options); + } + + public async getCatalogs(request?: CatalogsRequest): Promise { + return super.getCatalogs(request); + } +} + +export const clients: Array = [new LegacyClient(), new DBSQLClient(), new LoggingClient()]; +export const sessionClass = LoggingSession; +`; + +// Explicit disposal, without `await using` +const explicitDisposalConsumer = ` +import { DBSQLClient, asyncDisposable, AsyncDisposableResource } from '@databricks/sql'; +import IDBSQLSession from '@databricks/sql/dist/contracts/IDBSQLSession'; +import IOperation from '@databricks/sql/dist/contracts/IOperation'; + +export async function main(): Promise { + const client = new DBSQLClient(); + await client.connect({ host: 'host', path: 'path', token: 'token' }); + const session: AsyncDisposableResource = asyncDisposable(await client.openSession()); + const operation: AsyncDisposableResource = asyncDisposable(await session.executeStatement('SELECT 1')); + const catalogs = asyncDisposable(await session.getCatalogs()); + const disposals: Array> = [ + catalogs[Symbol.asyncDispose](), + operation[Symbol.asyncDispose](), + session[Symbol.asyncDispose](), + client[Symbol.asyncDispose](), + ]; + await Promise.all(disposals); +} +`; + +// Each class declaration must make \`Symbol.asyncDispose\` available on its own +const deepImportConsumers: Record = { + DBSQLOperation: ` +import DBSQLOperation from '@databricks/sql/dist/DBSQLOperation'; +export const dispose = (operation: DBSQLOperation): Promise => operation[Symbol.asyncDispose](); +`, + DBSQLSession: ` +import DBSQLSession from '@databricks/sql/dist/DBSQLSession'; +export const dispose = (session: DBSQLSession): Promise => session[Symbol.asyncDispose](); +`, + DBSQLClient: ` +import DBSQLClient from '@databricks/sql/dist/DBSQLClient'; +export const dispose = (client: DBSQLClient): Promise => client[Symbol.asyncDispose](); +`, +}; + +const awaitUsingConsumer = ` +import { DBSQLClient, asyncDisposable } from '@databricks/sql'; + +export async function main(): Promise> { + await using client = new DBSQLClient(); + await client.connect({ host: 'host', path: 'path', token: 'token' }); + await using session = asyncDisposable(await client.openSession()); + await using operation = asyncDisposable(await session.executeStatement('SELECT 1')); + await using tables = asyncDisposable(await session.getTables({ catalogName: 'main' })); + await tables.fetchAll(); + return operation.fetchAll(); +} +`; + +describe('Symbol.asyncDispose consumer typings', function () { + this.timeout(180000); + + before(() => { + emitDeclarations(); + }); + + after(() => { + virtualFiles.clear(); + }); + + (['es2018', 'esnext.disposable'] as const).forEach((consumerLib) => { + it(`keeps legacy interface implementations, mocks and subclasses compiling (lib ${consumerLib})`, () => { + expect(compileConsumer(legacyConsumer, consumerLib)).to.equal(''); + }); + + it(`supports explicit disposal (lib ${consumerLib})`, () => { + expect(compileConsumer(explicitDisposalConsumer, consumerLib)).to.equal(''); + }); + + Object.entries(deepImportConsumers).forEach(([className, source]) => { + it(`declares Symbol.asyncDispose for a deep import of ${className} (lib ${consumerLib})`, () => { + expect(compileConsumer(source, consumerLib)).to.equal(''); + }); + }); + }); + + it('supports an `await using` client -> session -> operation chain (lib esnext.disposable)', () => { + expect(compileConsumer(awaitUsingConsumer, 'esnext.disposable')).to.equal(''); + }); + + it('rejects `await using` of an interface-typed session, which may lack Symbol.asyncDispose', () => { + const source = ` +import { DBSQLClient } from '@databricks/sql'; + +export async function main(): Promise { + await using client = new DBSQLClient(); + await using session = await client.openSession(); +} +`; + expect(compileConsumer(source, 'esnext.disposable')).to.include('Symbol.asyncDispose'); + }); +}); diff --git a/tests/unit/kernel/execution.test.ts b/tests/unit/kernel/execution.test.ts index eb80bba8..360bb5ea 100644 --- a/tests/unit/kernel/execution.test.ts +++ b/tests/unit/kernel/execution.test.ts @@ -19,6 +19,9 @@ import expectNativeConnectionOptions from './_helpers/nativeOptions'; import KernelBackend from '../../../lib/kernel/KernelBackend'; import KernelSessionBackend from '../../../lib/kernel/KernelSessionBackend'; import KernelOperationBackend from '../../../lib/kernel/KernelOperationBackend'; +import DBSQLSession from '../../../lib/DBSQLSession'; +import DBSQLOperation from '../../../lib/DBSQLOperation'; +import asyncDisposable from '../../../lib/asyncDisposable'; import { KernelNativeBinding, KernelConnection, KernelStatement } from '../../../lib/kernel/KernelNativeLoader'; import IClientContext, { ClientConfig } from '../../../lib/contracts/IClientContext'; import { CrossReferenceRequest, PrimaryKeysRequest } from '../../../lib/contracts/IDBSQLSession'; @@ -1673,3 +1676,39 @@ describe('KernelOperationBackend — sync (executeStatementCancellable) path', ( expect(status.errorDetailsJson).to.equal(null); }); }); + +describe('DBSQLSession / DBSQLOperation over kernel backends — Symbol.asyncDispose', () => { + function makeFacadeSession(connection: FakeNativeConnection) { + const context = makeContext(); + return new DBSQLSession({ backend: new KernelSessionBackend({ connection, context }), context }); + } + + it('disposing an operation closes the native statement; re-disposing is a no-op', async () => { + const connection = new FakeNativeConnection(); + const session = makeFacadeSession(connection); + const operation = await session.executeStatement('SELECT 1'); + if (!(operation instanceof DBSQLOperation)) { + expect.fail('Assertion error: operation is not a DBSQLOperation'); + } + const closeSpy = sinon.spy(connection.statementToReturn, 'close'); + + expect(await operation[Symbol.asyncDispose]()).to.equal(undefined); + expect(connection.statementToReturn.closed).to.equal(true); + await operation[Symbol.asyncDispose](); + expect(closeSpy.callCount).to.equal(1); + }); + + it('disposing a session closes its operations and the native connection; re-disposing is a no-op', async () => { + const connection = new FakeNativeConnection(); + const session = makeFacadeSession(connection); + const operation = asyncDisposable(await session.executeStatement('SELECT 1')); + const closeSpy = sinon.spy(connection, 'close'); + + expect(await session[Symbol.asyncDispose]()).to.equal(undefined); + expect(connection.closed).to.equal(true); + expect(connection.statementToReturn.closed).to.equal(true); + await session[Symbol.asyncDispose](); + await operation[Symbol.asyncDispose](); + expect(closeSpy.callCount).to.equal(1); + }); +});