From 84f654b1698e56060b3f3059958217b82b2a8366 Mon Sep 17 00:00:00 2001 From: Jared Casey Date: Mon, 16 Sep 2024 11:30:06 -0500 Subject: [PATCH] JSCO-10: Add API Documentation (#15) --- README.md | 4 +- lib/authenticators.ts | 143 -------------------------------------- lib/columnar.ts | 1 - lib/querytypes.ts | 18 ++--- lib/streamablepromises.ts | 113 ------------------------------ package.json | 6 +- typedoc.json | 9 +-- 7 files changed, 16 insertions(+), 278 deletions(-) delete mode 100644 lib/authenticators.ts delete mode 100644 lib/streamablepromises.ts diff --git a/README.md b/README.md index 7432bad..f4bb9e6 100644 --- a/README.md +++ b/README.md @@ -7,10 +7,10 @@ Node.js client for [Couchbase](https://couchbase.com) Columnar Eventually the SDK will be published to npm, but in the interim a select set of packages with prebuilt binaries are available on the [Releases page](https://github.com/couchbaselabs/columnar-nodejs-client/releases). If a packages is not available for your specific platform, see the [BUILDING page](https://github.com/couchbaselabs/columnar-nodejs-client/blob/main/BUILDING.md) for details on how to build the SDK's binary. -To install the SDK from a wheel on the [Releases page](https://github.com/couchbaselabs/columnar-nodejs-client/releases): +To install the SDK from a prebuilt-binary (a.k.a. prebuild) on the [Releases page](https://github.com/couchbaselabs/columnar-nodejs-client/releases): 1. Download the appropriate package 2. Unzip the downloaded file -3. Install via npm: `npm install ` +3. Install via npm: `npm install ` If a compatible package is not available, the SDK's binary will need to be built from source: 1. Follow the steps on the [BUILDING page](https://github.com/couchbaselabs/columnar-nodejs-client/blob/main/BUILDING.md) diff --git a/lib/authenticators.ts b/lib/authenticators.ts deleted file mode 100644 index cb32eee..0000000 --- a/lib/authenticators.ts +++ /dev/null @@ -1,143 +0,0 @@ -/* - * Copyright 2016-2024. Couchbase, Inc. - * All Rights Reserved. - * - * Licensed under the Apache License, Version 2.0 (the "License"); - * you may not use this file except in compliance with the License. - * You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. - */ - -/** - * IPasswordAuthenticator specifies an authenticator which uses an RBAC - * username and password to authenticate with the cluster. - * - * @category Authentication - */ -export interface IPasswordAuthenticator { - /** - * The username to authenticate with. - */ - username: string - - /** - * The password to autehnticate with. - */ - password: string - - /** - * The sasl mechanisms to authenticate with. - */ - allowed_sasl_mechanisms?: string[] -} - -/** - * IPasswordAuthenticator specifies an authenticator which uses an SSL - * certificate and key to authenticate with the cluster. - * - * @category Authentication - */ -export interface ICertificateAuthenticator { - /** - * The path to the certificate which should be used for certificate authentication. - */ - certificatePath: string - - /** - * The path to the key which should be used for certificate authentication. - */ - keyPath: string -} - -/** - * PasswordAuthenticator implements a simple IPasswordAuthenticator. - * - * @category Authentication - */ -export class PasswordAuthenticator implements IPasswordAuthenticator { - /** - * The username that will be used to authenticate with. - */ - username: string - - /** - * The password that will be used to authenticate with. - */ - password: string - - /** - * The sasl mechanisms to authenticate with. - */ - allowed_sasl_mechanisms?: string[] | undefined - - /** - * Constructs this PasswordAuthenticator with the passed username and password. - * - * @param username The username to initialize this authenticator with. - * @param password The password to initialize this authenticator with. - */ - constructor(username: string, password: string) { - this.username = username - this.password = password - } - - /** - * Creates a LDAP compatible password authenticator which is INSECURE if not used with TLS. - * - * Please note that this is INSECURE and will leak user credentials on the wire to eavesdroppers. - * This should only be enabled in trusted environments. - * - * @param username The username to initialize this authenticator with. - * @param password The password to initialize this authenticator with. - */ - public static ldapCompatible( - username: string, - password: string - ): PasswordAuthenticator { - const auth = new PasswordAuthenticator(username, password) - auth.allowed_sasl_mechanisms = ['PLAIN'] - return auth - } -} - -/** - * CertificateAuthenticator implements a simple ICertificateAuthenticator. - * - * @category Authentication - */ -export class CertificateAuthenticator implements ICertificateAuthenticator { - /** - * The path to the certificate which should be used for certificate authentication. - */ - certificatePath: string - - /** - * The path to the key which should be used for certificate authentication. - */ - keyPath: string - - /** - * Constructs this CertificateAuthenticator with the passed certificate and key paths. - * - * @param certificatePath The certificate path to initialize this authenticator with. - * @param keyPath The key path to initialize this authenticator with. - */ - constructor(certificatePath: string, keyPath: string) { - this.certificatePath = certificatePath - this.keyPath = keyPath - } -} - -/** - * Represents any of the valid authenticators that could be passed to the SDK. - * - * @category Authentication - */ -export type Authenticator = IPasswordAuthenticator | ICertificateAuthenticator diff --git a/lib/columnar.ts b/lib/columnar.ts index 00b3fda..49efe70 100644 --- a/lib/columnar.ts +++ b/lib/columnar.ts @@ -76,6 +76,5 @@ export * from './cluster' export * from './credential' export * from './errors' export * from './scope' -export * from './streamablepromises' export { NodeCallback } from './utilities' diff --git a/lib/querytypes.ts b/lib/querytypes.ts index b564b23..a09f21d 100644 --- a/lib/querytypes.ts +++ b/lib/querytypes.ts @@ -23,7 +23,7 @@ import { errorFromCpp } from './bindingutilities' /** * Contains the results of a columnar query. * - * @category Analytics + * @category Query */ export class QueryResult { private _executor: QueryExecutor @@ -41,14 +41,16 @@ export class QueryResult { } /** - * Returns a {@link Readable} stream of rows returned from the Columnar query. + * Returns a [Readable](https://nodejs.org/api/stream.html#readable-streams) stream of rows returned from the Columnar query. */ rows(): QueryResultStream { return this._stream } /** - * Cancel. + * Volatile: This API is subject to change at any time. + * + * Cancel streaming the query results. */ cancel(): void { this._executor.triggerAbort() @@ -160,7 +162,7 @@ export class QueryResultStream extends Readable { /** * Contains the meta-data that is returned from a query. * - * @category Analytics + * @category Query */ export class QueryMetadata { /** @@ -192,7 +194,7 @@ export class QueryMetadata { * Contains information about a warning which occurred during the * execution of an analytics query. * - * @category Analytics + * @category Query */ export class QueryWarning { /** @@ -218,7 +220,7 @@ export class QueryWarning { * Contains various metrics that are returned by the server following * the execution of an analytics query. * - * @category Analytics + * @category Query */ export class QueryMetrics { /** @@ -262,7 +264,7 @@ export class QueryMetrics { * Represents the various scan consistency options that are available when * querying against columnar. * - * @category Analytics + * @category Query */ export enum QueryScanConsistency { /** @@ -282,7 +284,7 @@ export enum QueryScanConsistency { } /** - * @category Analytics + * @category Query */ export interface QueryOptions { /** diff --git a/lib/streamablepromises.ts b/lib/streamablepromises.ts deleted file mode 100644 index 8ac9a89..0000000 --- a/lib/streamablepromises.ts +++ /dev/null @@ -1,113 +0,0 @@ -/* - * Copyright 2016-2024. Couchbase, Inc. - * All Rights Reserved. - * - * Licensed under the Apache License, Version 2.0 (the "License"); - * you may not use this file except in compliance with the License. - * You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. - */ - -/* eslint jsdoc/require-jsdoc: off */ -import EventEmitter from 'events' - -/** - * @internal - */ -type PromisifyFunc = ( - emitter: StreamablePromise, - resolve: (result: T) => void, - reject: (err: Error) => void -) => void - -/** - * @internal - */ -export class StreamablePromise extends EventEmitter implements Promise { - private _promise: Promise | null = null - private _promiseifyFn: PromisifyFunc - - /** - * @internal - */ - constructor(promisefyFn: PromisifyFunc) { - super() - - this._promiseifyFn = promisefyFn - } - - private get promise(): Promise { - if (!this._promise) { - this._promise = new Promise((resolve, reject) => - this._promiseifyFn(this, resolve, reject) - ) - } - return this._promise - } - - then( - onfulfilled?: - | ((value: T) => TResult1 | PromiseLike) - | undefined - | null, - onrejected?: - | ((reason: any) => TResult2 | PromiseLike) - | undefined - | null - ): Promise { - return this.promise.then(onfulfilled, onrejected) - } - - catch( - onrejected?: - | ((reason: any) => TResult | PromiseLike) - | undefined - | null - ): Promise { - return this.promise.catch(onrejected) - } - - finally(onfinally?: (() => void) | undefined | null): Promise { - return this.promise.finally(onfinally) - } - - /** - * @internal - */ - get [Symbol.toStringTag](): string { - return (Promise as any)[Symbol.toStringTag] - } -} - -/** - * Provides the ability to be used as both a promise, or an event emitter. Enabling - * an application to easily retrieve all results using async/await, while also enabling - * streaming of results by listening for the row and meta events. - */ -export class StreamableRowPromise extends StreamablePromise { - constructor(fn: (rows: TRow[], meta: TMeta) => T) { - super((emitter, resolve, reject) => { - let err: Error | undefined - const rows: TRow[] = [] - let meta: TMeta | undefined - - emitter.on('row', (r) => rows.push(r)) - emitter.on('meta', (m) => (meta = m)) - emitter.on('error', (e) => (err = e)) - emitter.on('end', () => { - if (err) { - return reject(err) - } - - resolve(fn(rows, meta as TMeta)) - }) - }) - } -} diff --git a/package.json b/package.json index 3111c2e..4781e5a 100644 --- a/package.json +++ b/package.json @@ -1,12 +1,12 @@ { "bugs": { - "url": "http://www.couchbase.com/issues/browse/JSCO" + "url": "https://jira.issues.couchbase.com/projects/JSCO/issues" }, "description": "The official Couchbase Node.js Columnar Client Library.", "engines": { "node": ">=16" }, - "homepage": "http://www.couchbase.com/communities/nodejs", + "homepage": "https://www.couchbase.com/developers/sdks", "keywords": [ "couchbase", "columnar", @@ -53,7 +53,7 @@ }, "repository": { "type": "git", - "url": "http://github.com/couchbase/couchnode.git" + "url": "https://github.com/couchbaselabs/columnar-nodejs-client" }, "version": "1.0.0-dev", "config": { diff --git a/typedoc.json b/typedoc.json index 57ba56c..f4c43c4 100644 --- a/typedoc.json +++ b/typedoc.json @@ -1,5 +1,5 @@ { - "entryPoints": ["./lib/couchbase.ts"], + "entryPoints": ["./lib/columnar.ts"], "out": "docs", "excludePrivate": true, "excludeInternal": true, @@ -9,15 +9,8 @@ }, "categoryOrder": [ "Core", - "Key-Value", - "Transactions", "Query", - "Views", - "Full Text Search", - "Analytics", - "Datastructures", "Management", - "Diagnostics", "Authentication", "Error Handling", "Logging"