Skip to content

Commit 8ac1f15

Browse files
toptobestoptobes
committed
TSDoc progress + other minor fixes (#86)
* updated serdes * add shorthand datatype functions * update readme w/ shorthand datatype fns * marked mroe internal values * start documentation of tables * added listIndexes * some altertable fixes * bump min node version to v18+
1 parent 7e87a3f commit 8ac1f15

File tree

17 files changed

+513
-246
lines changed

17 files changed

+513
-246
lines changed

‎README.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,8 @@
66

77
## Table of contents
88
- [Quickstart](#quickstart)
9+
- [Collections](#collections)
10+
- [Tables](#tables)
911
- [High-level architecture](#high-level-architecture)
1012
- [Getting the most out of the typing](#getting-the-most-out-of-the-typing)
1113
- [Working with Dates](#working-with-dates)

‎etc/astra-db-ts.api.md

Lines changed: 53 additions & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,7 @@ export interface AddColumnOperation {
2626
// @public (undocumented)
2727
export interface AddVectorizeOperation<Schema extends SomeRow> {
2828
// (undocumented)
29-
columns: Record<Cols<Schema>, VectorizeServiceOptions>;
29+
columns: Partial<Record<Cols<Schema>, VectorizeServiceOptions>>;
3030
}
3131

3232
// @public
@@ -642,6 +642,14 @@ export interface CreateTableDefinition {
642642
readonly primaryKey: CreateTablePrimaryKeyDefinition;
643643
}
644644

645+
// @public (undocumented)
646+
export interface CreateTableIndexOptions extends WithTimeout<'tableAdminTimeoutMs'> {
647+
// (undocumented)
648+
ifNotExists?: boolean;
649+
// (undocumented)
650+
options?: TableIndexOptions;
651+
}
652+
645653
// @public
646654
export interface CreateTableOptions<Schema extends SomeRow, Def extends CreateTableDefinition = CreateTableDefinition> extends WithTimeout<'tableAdminTimeoutMs'>, TableOptions<Schema> {
647655
// (undocumented)
@@ -653,6 +661,14 @@ export interface CreateTableOptions<Schema extends SomeRow, Def extends CreateTa
653661
// @public (undocumented)
654662
export type CreateTablePrimaryKeyDefinition = ShortCreateTablePrimaryKeyDefinition | FullCreateTablePrimaryKeyDefinition;
655663

664+
// @public (undocumented)
665+
export interface CreateTableVectorIndexOptions extends WithTimeout<'tableAdminTimeoutMs'> {
666+
// (undocumented)
667+
ifNotExists?: boolean;
668+
// (undocumented)
669+
options?: TableVectorIndexOptions;
670+
}
671+
656672
// @public
657673
export abstract class CumulativeOperationError extends DataAPIResponseError {
658674
readonly partialResult: unknown;
@@ -1750,17 +1766,16 @@ export class Table<Schema extends SomeRow = SomeRow> {
17501766
// (undocumented)
17511767
alter<NewSchema extends SomeRow>(options: AlterTableOptions<Schema>): Promise<Table<NewSchema>>;
17521768
// (undocumented)
1753-
createIndex(name: string, column: Cols<Schema> | string, options?: TableCreateIndexOptions): Promise<void>;
1769+
createIndex(name: string, column: Cols<Schema> | string, options?: CreateTableIndexOptions): Promise<void>;
17541770
// (undocumented)
1755-
createVectorIndex(name: string, column: Cols<Schema> | string, options?: TableCreateVectorIndexOptions): Promise<void>;
1771+
createVectorIndex(name: string, column: Cols<Schema> | string, options?: CreateTableVectorIndexOptions): Promise<void>;
17561772
// (undocumented)
17571773
definition(options?: WithTimeout<'tableAdminTimeoutMs'>): Promise<ListTableDefinition>;
17581774
// (undocumented)
17591775
deleteMany(filter: TableFilter<Schema>, options?: WithTimeout<'generalMethodTimeoutMs'>): Promise<void>;
1776+
deleteOne(filter: TableFilter<Schema>, options?: WithTimeout<'generalMethodTimeoutMs'>): Promise<void>;
17601777
// (undocumented)
1761-
deleteOne(filter: TableFilter<Schema>, options?: TableDeleteOneOptions): Promise<void>;
1762-
// (undocumented)
1763-
drop(options?: WithTimeout<'tableAdminTimeoutMs'>): Promise<void>;
1778+
drop(options?: Omit<DropTableOptions, 'keyspace'>): Promise<void>;
17641779
// (undocumented)
17651780
find(filter: TableFilter<Schema>, options?: TableFindOptions & {
17661781
projection?: never;
@@ -1771,43 +1786,27 @@ export class Table<Schema extends SomeRow = SomeRow> {
17711786
findOne(filter: TableFilter<Schema>, options?: TableFindOneOptions): Promise<FoundRow<Schema> | null>;
17721787
// (undocumented)
17731788
get _httpClient(): DataAPIHttpClient<"normal">;
1774-
// (undocumented)
1775-
insertMany(document: readonly Schema[], options?: TableInsertManyOptions): Promise<TableInsertManyResult<Schema>>;
1776-
insertOne(row: Schema, options?: WithTimeout<'generalMethodTimeoutMs'>): Promise<TableInsertOneResult<Schema>>;
1789+
insertMany(rows: readonly Schema[], options?: TableInsertManyOptions): Promise<TableInsertManyResult<Schema>>;
1790+
insertOne(row: Schema, timeout?: WithTimeout<'generalMethodTimeoutMs'>): Promise<TableInsertOneResult<Schema>>;
17771791
readonly keyspace: string;
1778-
readonly name: string;
1779-
// (undocumented)
1780-
updateOne(filter: TableFilter<Schema>, update: TableUpdateFilter<Schema>, options?: TableUpdateOneOptions): Promise<void>;
1781-
}
1782-
1783-
// @public (undocumented)
1784-
export type TableColumnTypeParser = (val: any, ctx: TableDesCtx, definition: SomeDoc) => any;
1785-
1786-
// @public (undocumented)
1787-
export interface TableCreateIndexOptions extends WithTimeout<'tableAdminTimeoutMs'> {
1788-
// (undocumented)
1789-
ifNotExists?: boolean;
1790-
// (undocumented)
1791-
options?: {
1792-
caseSensitive?: boolean;
1793-
normalize?: boolean;
1794-
ascii?: boolean;
1795-
};
1796-
}
1797-
1798-
// @public (undocumented)
1799-
export interface TableCreateVectorIndexOptions extends WithTimeout<'tableAdminTimeoutMs'> {
1792+
// Warning: (ae-forgotten-export) The symbol "ListIndexOptions" needs to be exported by the entry point index.d.ts
1793+
//
18001794
// (undocumented)
1801-
ifNotExists?: boolean;
1795+
listIndexes(options?: ListIndexOptions & {
1796+
nameOnly: true;
1797+
}): Promise<string[]>;
1798+
// Warning: (ae-forgotten-export) The symbol "TableIndexDescriptor" needs to be exported by the entry point index.d.ts
1799+
//
18021800
// (undocumented)
1803-
options?: {
1804-
metric: 'cosine' | 'euclidean' | 'dot_product';
1805-
sourceModel?: string;
1806-
};
1801+
listIndexes(options?: ListIndexOptions & {
1802+
nameOnly?: false;
1803+
}): Promise<TableIndexDescriptor[]>;
1804+
readonly name: string;
1805+
updateOne(filter: TableFilter<Schema>, update: TableUpdateFilter<Schema>, timeout?: WithTimeout<'generalMethodTimeoutMs'>): Promise<void>;
18071806
}
18081807

18091808
// @public (undocumented)
1810-
export type TableDeleteOneOptions = GenericDeleteOneOptions;
1809+
export type TableColumnTypeParser = (val: any, ctx: TableDesCtx, definition: SomeDoc) => any;
18111810

18121811
// @public (undocumented)
18131812
export interface TableDescriptor {
@@ -1875,6 +1874,16 @@ export type TableFindOneOptions = GenericFindOneOptions;
18751874
// @public (undocumented)
18761875
export type TableFindOptions = GenericFindOptions;
18771876

1877+
// @public (undocumented)
1878+
export interface TableIndexOptions {
1879+
// (undocumented)
1880+
ascii?: boolean;
1881+
// (undocumented)
1882+
caseSensitive?: boolean;
1883+
// (undocumented)
1884+
normalize?: boolean;
1885+
}
1886+
18781887
// @public
18791888
export class TableInsertManyError extends CumulativeOperationError {
18801889
name: string;
@@ -1892,7 +1901,6 @@ export interface TableInsertManyResult<Schema extends SomeRow> {
18921901

18931902
// @public
18941903
export interface TableInsertOneResult<Schema extends SomeRow> {
1895-
// (undocumented)
18961904
insertedId: KeyOf<Schema>;
18971905
}
18981906

@@ -1934,8 +1942,13 @@ export type TableUpdateManyOptions = GenericUpdateManyOptions;
19341942
// @public (undocumented)
19351943
export type TableUpdateManyResult<Schema extends SomeRow> = GenericUpdateResult<KeyOf<Schema>, number>;
19361944

1937-
// @public
1938-
export type TableUpdateOneOptions = GenericUpdateOneOptions;
1945+
// @public (undocumented)
1946+
export interface TableVectorIndexOptions {
1947+
// (undocumented)
1948+
metric: 'cosine' | 'euclidean' | 'dot_product';
1949+
// (undocumented)
1950+
sourceModel?: string;
1951+
}
19391952

19401953
// @public (undocumented)
19411954
export const time: (time?: string | Date | DataAPITimeComponents) => DataAPITime;

‎src/db/db.ts

Lines changed: 19 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1015,7 +1015,11 @@ export class Db {
10151015
}
10161016

10171017
public async dropTableIndex(name: string, options?: TableDropIndexOptions): Promise<void> {
1018-
await this.#httpClient.executeCommand({ dropIndex: { name, options: { ifExists: options?.ifExists } } }, {
1018+
const dropOpts = (options?.ifExists)
1019+
? { ifExists: true }
1020+
: undefined;
1021+
1022+
await this.#httpClient.executeCommand({ dropIndex: { name, options: dropOpts } }, {
10191023
timeoutManager: this.#httpClient.tm.single('tableAdminTimeoutMs', options),
10201024
});
10211025
}
@@ -1066,19 +1070,29 @@ export class Db {
10661070
public async listCollections(options?: ListCollectionsOptions & { nameOnly?: false }): Promise<CollectionDescriptor[]>
10671071

10681072
public async listCollections(options?: ListCollectionsOptions): Promise<string[] | CollectionDescriptor[]> {
1073+
const explain = options?.nameOnly !== true;
1074+
10691075
const command = {
10701076
findCollections: {
1071-
options: {
1072-
explain: options?.nameOnly !== true,
1073-
},
1077+
options: { explain },
10741078
},
10751079
};
10761080

10771081
const resp = await this.#httpClient.executeCommand(command, {
10781082
timeoutManager: this.#httpClient.tm.single('collectionAdminTimeoutMs', options),
10791083
keyspace: options?.keyspace,
10801084
});
1081-
return resp.status!.collections;
1085+
1086+
const colls = resp.status!.collections;
1087+
1088+
if (explain) {
1089+
for (let i = 0, n = colls.length; i < n; i++) {
1090+
colls[i].definition = colls[i].options;
1091+
delete colls[i].options;
1092+
}
1093+
}
1094+
1095+
return colls;
10821096
}
10831097

10841098
/**

‎src/db/types/tables/alter-table.ts

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -40,7 +40,7 @@ export interface DropColumnOperation<Schema extends SomeRow> {
4040
}
4141

4242
export interface AddVectorizeOperation<Schema extends SomeRow> {
43-
columns: Record<Cols<Schema>, VectorizeServiceOptions>
43+
columns: Partial<Record<Cols<Schema>, VectorizeServiceOptions>>,
4444
}
4545

4646
export interface DropVectorizeOperation<Schema extends SomeRow> {

‎src/db/types/tables/list-indexes.ts

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
// Copyright DataStax, Inc.
2+
//
3+
// Licensed under the Apache License, Version 2.0 (the "License");
4+
// you may not use this file except in compliance with the License.
5+
// You may obtain a copy of the License at
6+
//
7+
// http://www.apache.org/licenses/LICENSE-2.0
8+
//
9+
// Unless required by applicable law or agreed to in writing, software
10+
// distributed under the License is distributed on an "AS IS" BASIS,
11+
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
// See the License for the specific language governing permissions and
13+
// limitations under the License.
14+
15+
import { TableIndexOptions, TableVectorIndexOptions } from '@/src/documents';
16+
import { WithTimeout } from '@/src/lib';
17+
18+
export interface ListIndexOptions extends WithTimeout<'tableAdminTimeoutMs'> {
19+
nameOnly?: boolean,
20+
}
21+
22+
export interface TableIndexDescriptor {
23+
name: string,
24+
definition: TableNormalIndexDescriptor | TableVectorIndexDescriptor | TableUnknownIndex,
25+
}
26+
27+
interface TableNormalIndexDescriptor {
28+
column: string,
29+
options: TableIndexOptions,
30+
}
31+
32+
interface TableVectorIndexDescriptor {
33+
column: string,
34+
options: TableVectorIndexOptions,
35+
}
36+
37+
interface TableUnknownIndex {
38+
column: 'UNKNOWN',
39+
apiSupport: TableIndexUnsupportedColumnApiSupport,
40+
}
41+
42+
interface TableIndexUnsupportedColumnApiSupport {
43+
createIndex: boolean,
44+
filter: boolean,
45+
cqlDefinition: string,
46+
}

0 commit comments

Comments
 (0)