From 6b96db5615f5693c0848706bfac158d23e99ed21 Mon Sep 17 00:00:00 2001 From: Alan Plum Date: Wed, 18 Dec 2024 18:03:01 +0100 Subject: [PATCH 01/25] Add index types Fixes DE-956. Fixes DE-957. Fixes DE-958. --- CHANGELOG.md | 16 ++++ src/collection.ts | 96 ++++++++++++++------- src/indexes.ts | 214 +++++++++++++++++++++++++++++++--------------- 3 files changed, 226 insertions(+), 100 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 70f2ccf83..ad3f8e73c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -14,6 +14,21 @@ This driver uses semantic versioning: - A change in the major version (e.g. 1.Y.Z -> 2.0.0) indicates _breaking_ changes that require changes in your code to upgrade. +## [Unreleased] + +### Added + +- Added support for `mdi-prefixed` indexes (DE-956) + +- Restored `fulltext` index type support (DE-957) + + The `fulltext` index type is still no longer supported for creating new + indexes but can be used to cast existing indexes from `Index`. + +- Added support for `edge` indexes (DE-958) + + The `Index` type now can also be cast to the `EdgeIndex` type. + ## [9.2.0] - 2024-11-27 ### Added @@ -1962,6 +1977,7 @@ For a detailed list of changes between pre-release versions of v7 see the Graph methods now only return the relevant part of the response body. +[unreleased]: https://github.com/arangodb/arangojs/compare/v9.2.0...HEAD [9.2.0]: https://github.com/arangodb/arangojs/compare/v9.1.0...v9.2.0 [9.1.0]: https://github.com/arangodb/arangojs/compare/v9.0.0...v9.1.0 [9.0.0]: https://github.com/arangodb/arangojs/compare/v8.8.1...v9.0.0 diff --git a/src/collection.ts b/src/collection.ts index a9566f90b..2a9ff28cd 100644 --- a/src/collection.ts +++ b/src/collection.ts @@ -28,20 +28,22 @@ import { import { HttpError, isArangoError } from "./error.js"; import { EnsureGeoIndexOptions, + EnsureIndexOptions, EnsureInvertedIndexOptions, + EnsureMdiIndexOptions, + EnsureMdiPrefixedIndexOptions, EnsurePersistentIndexOptions, EnsureTtlIndexOptions, - EnsureMdiIndexOptions, GeoIndex, + HiddenIndex, Index, IndexSelector, InvertedIndex, + MdiIndex, + MdiPrefixedIndex, PersistentIndex, TtlIndex, - MdiIndex, _indexHandle, - EnsureIndexOptions, - HiddenIndex, } from "./indexes.js"; import { COLLECTION_NOT_FOUND, DOCUMENT_NOT_FOUND } from "./lib/codes.js"; @@ -1254,7 +1256,7 @@ export interface DocumentCollection< ): Promise< ArangoApiResponse< CollectionMetadata & - CollectionProperties & { count: number; figures: Record } + CollectionProperties & { count: number; figures: Record } > >; /** @@ -1341,7 +1343,9 @@ export interface DocumentCollection< * // the collection "some-collection" is now empty * ``` */ - truncate(options?: CollectionTruncateOptions): Promise>; + truncate( + options?: CollectionTruncateOptions + ): Promise>; /** * Deletes the collection from the database. * @@ -1589,9 +1593,9 @@ export interface DocumentCollection< ): Promise< Array< | (DocumentOperationMetadata & { - new?: Document; - old?: Document; - }) + new?: Document; + old?: Document; + }) | DocumentOperationFailure > >; @@ -1661,9 +1665,9 @@ export interface DocumentCollection< ): Promise< Array< | (DocumentOperationMetadata & { - new?: Document; - old?: Document; - }) + new?: Document; + old?: Document; + }) | DocumentOperationFailure > >; @@ -1733,9 +1737,9 @@ export interface DocumentCollection< ): Promise< Array< | (DocumentOperationMetadata & { - new?: Document; - old?: Document; - }) + new?: Document; + old?: Document; + }) | DocumentOperationFailure > >; @@ -2022,6 +2026,28 @@ export interface DocumentCollection< ensureIndex( details: EnsureMdiIndexOptions ): Promise>; + /** + * Creates a prefixed multi-dimensional index on the collection if it does not already exist. + * + * @param details - Options for creating the prefixed multi-dimensional index. + * + * @example + * ```js + * const db = new Database(); + * const collection = db.collection("some-points"); + * // Create a multi-dimensional index for the attributes x, y and z + * await collection.ensureIndex({ + * type: "mdi-prefixed", + * fields: ["x", "y", "z"], + * prefixFields: ["x"], + * fieldValueTypes: "double" + * }); + * ``` + * ``` + */ + ensureIndex( + details: EnsureMdiPrefixedIndexOptions + ): Promise>; /** * Creates a geo index on the collection if it does not already exist. * @@ -2294,9 +2320,9 @@ export interface EdgeCollection< ): Promise< Array< | (DocumentOperationMetadata & { - new?: Edge; - old?: Edge; - }) + new?: Edge; + old?: Edge; + }) | DocumentOperationFailure > >; @@ -2390,9 +2416,9 @@ export interface EdgeCollection< ): Promise< Array< | (DocumentOperationMetadata & { - new?: Edge; - old?: Edge; - }) + new?: Edge; + old?: Edge; + }) | DocumentOperationFailure > >; @@ -2484,9 +2510,9 @@ export interface EdgeCollection< ): Promise< Array< | (DocumentOperationMetadata & { - new?: Edge; - old?: Edge; - }) + new?: Edge; + old?: Edge; + }) | DocumentOperationFailure > >; @@ -2744,12 +2770,13 @@ export interface EdgeCollection< * @internal */ export class Collection< - EntryResultType extends Record = any, - EntryInputType extends Record = EntryResultType, -> + EntryResultType extends Record = any, + EntryInputType extends Record = EntryResultType, + > implements - EdgeCollection, - DocumentCollection { + EdgeCollection, + DocumentCollection +{ //#region attributes protected _name: string; protected _db: Database; @@ -2880,9 +2907,9 @@ export class Collection< details = false ): Promise< CollectionMetadata & - ArangoApiResponse< - CollectionProperties & { count: number; figures: Record } - > + ArangoApiResponse< + CollectionProperties & { count: number; figures: Record } + > > { return this._db.request({ path: `/_api/collection/${encodeURIComponent(this._name)}/figures`, @@ -2931,7 +2958,9 @@ export class Collection< return result; } - truncate(options?: CollectionTruncateOptions): Promise> { + truncate( + options?: CollectionTruncateOptions + ): Promise> { return this._db.request({ method: "PUT", path: `/_api/collection/${this._name}/truncate`, @@ -3268,6 +3297,7 @@ export class Collection< | EnsureGeoIndexOptions | EnsureTtlIndexOptions | EnsureMdiIndexOptions + | EnsureMdiPrefixedIndexOptions | EnsureInvertedIndexOptions ) { return this._db.request({ diff --git a/src/indexes.ts b/src/indexes.ts index 8be5833c5..9176cfb86 100644 --- a/src/indexes.ts +++ b/src/indexes.ts @@ -88,74 +88,74 @@ export type EnsurePersistentIndexOptions = { */ export type EnsureGeoIndexOptions = | { - type: "geo"; - /** - * If set to `true`, `fields` must be an array containing a single attribute - * path and the attribute value must be an array with two values, the first - * of which will be interpreted as the longitude and the second of which will - * be interpreted as the latitude of the document. - * - * Default: `false` - */ - geoJson?: false; - /** - * If set to `true`, the index will use pre-3.10 rules for parsing - * GeoJSON polygons. This option is always implicitly `true` when using - * ArangoDB 3.9 or lower. - */ - legacyPolygons?: boolean; - /** - * Attribute paths for the document's latitude and longitude values. - */ - fields: [string, string]; - /** - * A unique name for this index. - */ - name?: string; - /** - * If set to `true`, the index will be created in the background to reduce - * the write-lock duration for the collection during index creation. - * - * Default: `false` - */ - inBackground?: boolean; - } + type: "geo"; + /** + * If set to `true`, `fields` must be an array containing a single attribute + * path and the attribute value must be an array with two values, the first + * of which will be interpreted as the longitude and the second of which will + * be interpreted as the latitude of the document. + * + * Default: `false` + */ + geoJson?: false; + /** + * If set to `true`, the index will use pre-3.10 rules for parsing + * GeoJSON polygons. This option is always implicitly `true` when using + * ArangoDB 3.9 or lower. + */ + legacyPolygons?: boolean; + /** + * Attribute paths for the document's latitude and longitude values. + */ + fields: [string, string]; + /** + * A unique name for this index. + */ + name?: string; + /** + * If set to `true`, the index will be created in the background to reduce + * the write-lock duration for the collection during index creation. + * + * Default: `false` + */ + inBackground?: boolean; + } | { - type: "geo"; - /** - * If set to `true`, `fields` must be an array containing a single attribute - * path and the attribute value must be an array with two values, the first - * of which will be interpreted as the longitude and the second of which will - * be interpreted as the latitude of the document. - * - * Default: `false` - */ - geoJson?: boolean; - /** - * If set to `true`, the index will use pre-3.10 rules for parsing - * GeoJSON polygons. This option is always implicitly `true` when using - * ArangoDB 3.9 or lower. - */ - legacyPolygons?: boolean; - /** - * An array containing the attribute path for an array containing two values, - * the first of which will be interpreted as the latitude, the second as the - * longitude. If `geoJson` is set to `true`, the order is reversed to match - * the GeoJSON format. - */ - fields: [string]; - /** - * A unique name for this index. - */ - name?: string; - /** - * If set to `true`, the index will be created in the background to reduce - * the write-lock duration for the collection during index creation. - * - * Default: `false` - */ - inBackground?: boolean; - }; + type: "geo"; + /** + * If set to `true`, `fields` must be an array containing a single attribute + * path and the attribute value must be an array with two values, the first + * of which will be interpreted as the longitude and the second of which will + * be interpreted as the latitude of the document. + * + * Default: `false` + */ + geoJson?: boolean; + /** + * If set to `true`, the index will use pre-3.10 rules for parsing + * GeoJSON polygons. This option is always implicitly `true` when using + * ArangoDB 3.9 or lower. + */ + legacyPolygons?: boolean; + /** + * An array containing the attribute path for an array containing two values, + * the first of which will be interpreted as the latitude, the second as the + * longitude. If `geoJson` is set to `true`, the order is reversed to match + * the GeoJSON format. + */ + fields: [string]; + /** + * A unique name for this index. + */ + name?: string; + /** + * If set to `true`, the index will be created in the background to reduce + * the write-lock duration for the collection during index creation. + * + * Default: `false` + */ + inBackground?: boolean; + }; /** * Options for creating a TTL index. @@ -222,6 +222,45 @@ export type EnsureMdiIndexOptions = { inBackground?: boolean; }; +/** + * Options for creating a prefixed MDI index. + */ +export type EnsureMdiPrefixedIndexOptions = { + /** + * Type of this index. + */ + type: "mdi-prefixed"; + /** + * An array containing attribute paths for the dimensions. + */ + fields: string[]; + /** + * Data type of the dimension attributes. + */ + fieldValueTypes: "double"; + /** + * An array of attribute names used as a search prefix. + */ + prefixFields: string[]; + /** + * A unique name for this index. + */ + name?: string; + /** + * If set to `true`, a unique index will be created. + * + * Default: `false` + */ + unique?: boolean; + /** + * If set to `true`, the index will be created in the background to reduce + * the write-lock duration for the collection during index creation. + * + * Default: `false` + */ + inBackground?: boolean; +}; + /** * (Enterprise Edition only.) Options for a nested field in an inverted index. */ @@ -526,6 +565,7 @@ export type EnsureIndexOptions = | EnsureGeoIndexOptions | EnsureTtlIndexOptions | EnsureMdiIndexOptions + | EnsureMdiPrefixedIndexOptions | EnsureInvertedIndexOptions; /** @@ -564,6 +604,7 @@ export type PersistentIndex = GenericIndex & { cacheEnabled: boolean; deduplicate: boolean; estimates: boolean; + selectivityEstimate: number; storedValues?: string[]; }; @@ -576,6 +617,27 @@ export type PrimaryIndex = GenericIndex & { selectivityEstimate: number; }; +/** + * An object representing an edge index. + */ +export type EdgeIndex = GenericIndex & { + type: "edge"; + fields: ["_from", "_to"]; + selectivityEstimate: number; +}; + +/** + * An object representing a fulltext index. + * + * @deprecated The `fulltext` index type was deprecated in ArangoDB 3.10. Use + * {@link views.ArangoSearchView} instead. + */ +export type FulltextIndex = GenericIndex & { + type: "fulltext"; + fields: [string]; + minLength: number; +}; + /** * An object representing a geo index. */ @@ -596,6 +658,7 @@ export type TtlIndex = GenericIndex & { type: "ttl"; fields: [string]; expireAfter: number; + estimates: boolean; selectivityEstimate: number; }; @@ -606,6 +669,20 @@ export type MdiIndex = GenericIndex & { type: "mdi"; fields: string[]; fieldValueTypes: "double"; + estimates: boolean; + selectivityEstimate: number; +}; + +/** + * An object representing a prefixed MDI index. + */ +export type MdiPrefixedIndex = GenericIndex & { + type: "mdi-prefixed"; + fields: string[]; + prefixFields: string[]; + fieldValueTypes: "double"; + estimates: boolean; + selectivityEstimate: number; }; /** @@ -688,8 +765,11 @@ export type Index = | GeoIndex | PersistentIndex | PrimaryIndex + | EdgeIndex + | FulltextIndex | TtlIndex | MdiIndex + | MdiPrefixedIndex | InvertedIndex; /** From b20f3cdb21d9a41616794f4dcb9350894e263571 Mon Sep 17 00:00:00 2001 From: Alan Plum Date: Mon, 6 Jan 2025 12:08:19 +0100 Subject: [PATCH 02/25] Implement missing HTTP API methods Fixes DE-148. Fixes DE-149. Fixes DE-150. Fixes DE-151. Fixes DE-906. Fixes DE-932. Fixes DE-939. Fixes DE-949. --- CHANGELOG.md | 38 ++-- src/collection.ts | 41 +++++ src/database.ts | 438 +++++++++++++++++++++++++++++++++++++++------- 3 files changed, 446 insertions(+), 71 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index ad3f8e73c..c49804d55 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -18,6 +18,22 @@ This driver uses semantic versioning: ### Added +- Added `db.compact` method (DE-906) + +- Added `db.engineStats` method (DE-932) + +- Added `db.getLicense` and `db.setLicense` methods (DE-949) + +- Added `db.listQueryCacheEntries` method (DE-149) + +- Added `db.clearQueryCache` method (DE-148) + +- Added `db.getQueryCacheProperties` method (DE-150) + +- Added `db.setQueryCacheProperties` method (DE-151) + +- Added `collection.shards` method (DE-939) + - Added support for `mdi-prefixed` indexes (DE-956) - Restored `fulltext` index type support (DE-957) @@ -33,13 +49,13 @@ This driver uses semantic versioning: ### Added -- Added `database.availability` method +- Added `db.availability` method -- Added `database.engine` method (DE-931) +- Added `db.engine` method (DE-931) -- Added `database.status` method ([#811](https://github.com/arangodb/arangojs/issues/811)) +- Added `db.status` method ([#811](https://github.com/arangodb/arangojs/issues/811)) -- Added `database.supportInfo` method +- Added `db.supportInfo` method - Added `keepNull` option to `CollectionInsertOptions` type (DE-946) @@ -1132,7 +1148,7 @@ For a detailed list of changes between pre-release versions of v7 see the - Changed `db.createDatabase` return type to `Database` -- Renamed `database.setQueryTracking` to `database.queryTracking` +- Renamed `db.setQueryTracking` to `db.queryTracking` The method will now return the existing query tracking properties or set the new query tracking properties depending on whether an argument is provided. @@ -1528,7 +1544,7 @@ For a detailed list of changes between pre-release versions of v7 see the - Added support for ArangoDB 3.5 Analyzers API - See the documentation of the `database.analyzer` method and the `Analyzer` + See the documentation of the `db.analyzer` method and the `Analyzer` instances for information on using this API. - Added `collection.getResponsibleShard` method @@ -1702,7 +1718,7 @@ For a detailed list of changes between pre-release versions of v7 see the - Fixed `edgeCollection.save` not respecting options ([#554](https://github.com/arangodb/arangojs/issues/554)) -- Fixed `database.createDatabase` TypeScript signature ([#561](https://github.com/arangodb/arangojs/issues/561)) +- Fixed `db.createDatabase` TypeScript signature ([#561](https://github.com/arangodb/arangojs/issues/561)) ## [6.5.0] - 2018-08-03 @@ -1743,7 +1759,7 @@ For a detailed list of changes between pre-release versions of v7 see the - Added `ArangoError` and `CollectionType` to public exports -- Added `database.close` method +- Added `db.close` method - Added `opts` parameter to `EdgeCollection#save` @@ -1751,11 +1767,11 @@ For a detailed list of changes between pre-release versions of v7 see the ### Added -- Added `database.version` method +- Added `db.version` method -- Added `database.login` method +- Added `db.login` method -- Added `database.exists` method +- Added `db.exists` method - Added `collection.exists` method diff --git a/src/collection.ts b/src/collection.ts index 2a9ff28cd..2ce5a09da 100644 --- a/src/collection.ts +++ b/src/collection.ts @@ -1308,6 +1308,34 @@ export interface DocumentCollection< * ``` */ loadIndexes(): Promise; + /** + * Retrieves the collection's shard IDs. + * + * @param details - If set to `true`, the response will include the responsible + * servers for each shard. + */ + shards( + details?: false + ): Promise< + ArangoApiResponse< + CollectionMetadata & CollectionProperties & { shards: string[] } + > + >; + /** + * Retrieves the collection's shard IDs and the responsible servers for each + * shard. + * + * @param details - If set to `false`, the response will only include the + * shard IDs without the responsible servers for each shard. + */ + shards( + details: true + ): Promise< + ArangoApiResponse< + CollectionMetadata & + CollectionProperties & { shards: Record } + > + >; /** * Renames the collection and updates the instance's `name` to `newName`. * @@ -2952,6 +2980,19 @@ export class Collection< ); } + shards( + details?: boolean + ): Promise< + ArangoApiResponse< + CollectionMetadata & CollectionProperties & { shards: any } + > + > { + return this._db.request({ + path: `/_api/collection/${encodeURIComponent(this._name)}/shards`, + search: { details }, + }); + } + async rename(newName: string) { const result = await this._db.renameCollection(this._name, newName); this._name = newName; diff --git a/src/database.ts b/src/database.ts index 13836284e..388cd1758 100644 --- a/src/database.ts +++ b/src/database.ts @@ -20,11 +20,11 @@ import { ArangoCollection, Collection, CollectionMetadata, - collectionToString, CollectionType, CreateCollectionOptions, DocumentCollection, EdgeCollection, + collectionToString, isArangoCollection, } from "./collection.js"; import { @@ -619,6 +619,109 @@ export type QueryTrackingOptions = { trackSlowQueries?: boolean; }; +/** + * Entry in the AQL query results cache. + */ +export type QueryCacheEntry = { + /** + * Hash of the query results. + */ + hash: string; + /** + * Query string. + */ + query: string; + /** + * Bind parameters used in the query. Only shown if tracking for bind + * variables was enabled at server start. + */ + bindVars: Record; + /** + * Size of the query results and bind parameters in bytes. + */ + size: number; + /** + * Number of documents/rows in the query results. + */ + results: number; + /** + * Date and time the query was started as an ISO 8601 timestamp. + */ + started: string; + /** + * Number of times the result was served from the cache. + */ + hits: number; + /** + * Running time of the query in seconds. + */ + runTime: number; + /** + * Collections and views involved in the query. + */ + dataSources: string[]; +}; + +/** + * Properties of the global AQL query results cache configuration. + */ +export type QueryCacheProperties = { + /** + * If set to `true`, the query cache will include queries that involve + * system collections. + */ + includeSystem: boolean; + /** + * Maximum individual size of query results that will be stored per + * database-specific cache. + */ + maxEntrySize: number; + /** + * Maximum number of query results that will be stored per database-specific + * cache. + */ + maxResults: number; + /** + * Maximum cumulated size of query results that will be stored per + * database-specific cache. + */ + maxResultsSize: number; + /** + * Mode the AQL query cache should operate in. + */ + mode: "off" | "on" | "demand"; +}; + +/** + * Options for adjusting the global properties for the AQL query results cache. + */ +export type QueryCachePropertiesOptions = { + /** + * If set to `true`, the query cache will include queries that involve + * system collections. + */ + includeSystem?: boolean; + /** + * Maximum individual size of query results that will be stored per + * database-specific cache. + */ + maxEntrySize?: number; + /** + * Maximum number of query results that will be stored per database-specific + * cache. + */ + maxResults?: number; + /** + * Maximum cumulated size of query results that will be stored per + * database-specific cache. + */ + maxResultsSize?: number; + /** + * Mode the AQL query cache should operate in. + */ + mode?: "off" | "on" | "demand"; +}; + /** * Object describing a query. */ @@ -980,10 +1083,18 @@ export type EngineInfo = { * Index type aliases supported by the storage engine. */ indexes?: Record; - } + }; }; }; +/** + * Performance and resource usage information about the storage engine. + */ +export type EngineStatsInfo = Record< + string, + string | number | Record +>; + /** * Information about the server status. */ @@ -1049,7 +1160,7 @@ export type ServerStatusInformation = { */ foxxApi: boolean; /** - * A host identifier defined by the HOST or NODE_NAME environment variable, + * A host identifier defined by the HOST or NODE_NAME environment variable, * or a fallback value using a machine identifier or the cluster/Agency address. */ host: string; @@ -1063,7 +1174,7 @@ export type ServerStatusInformation = { license: "community" | "enterprise"; /** * Server operation mode. - * + * * @deprecated use `operationMode` instead */ mode: "server" | "console"; @@ -1135,7 +1246,7 @@ export type ServerStatusInformation = { version: string; /** * Whether writes are enabled. - * + * * @deprecated Use `readOnly` instead. */ writeOpsEnabled: boolean; @@ -1146,9 +1257,9 @@ export type ServerStatusInformation = { * Server availability. * * - `"default"`: The server is operational. - * + * * - `"readonly"`: The server is in read-only mode. - * + * * - `false`: The server is not available. */ export type ServerAvailability = "default" | "readonly" | false; @@ -1167,9 +1278,9 @@ export type SingleServerSupportInfo = { deployment: { /** * Deployment mode: - * + * * - `"single"`: A single server deployment. - * + * * - `"cluster"`: A cluster deployment. */ type: "single"; @@ -1190,9 +1301,9 @@ export type ClusterSupportInfo = { deployment: { /** * Deployment mode: - * + * * - `"single"`: A single server deployment. - * + * * - `"cluster"`: A cluster deployment. */ type: "cluster"; @@ -1240,14 +1351,78 @@ export type ClusterSupportInfo = { * Number of servers in the cluster. */ servers: number; - } + }; }; /** * (Cluster only.) Information about the ArangoDB instance as well as the * host machine. */ host: Record; -} +}; + +/** + * Information about the server license. + */ +export type LicenseInfo = { + /** + * Properties of the license. + */ + features: { + /** + * The timestamp of the expiration date of the license in seconds since the + * Unix epoch. + */ + expires?: number; + }; + /** + * The hash value of the license. + */ + hash: string; + /** + * The encrypted license key in base 64 encoding, or `"none"` when running + * in the Community Edition. + */ + license?: string; + /** + * The status of the installed license. + * + * - `"good"`: The license is valid for more than 2 weeks. + * + * - `"expiring"`: The license is valid for less than 2 weeks. + * + * - `"expired"`: The license has expired. + * + * - `"read-only"`: The license has been expired for more than 2 weeks. + */ + status: "good" | "expiring" | "expired" | "read-only"; + /** + * Whether the server is performing a database upgrade. + */ + upgrading: boolean; + /** + * The license version number. + */ + version: number; +}; + +/** + * Options for compacting all databases on the server. + */ +export type CompactOptions = { + /** + * Whether compacted data should be moved to the minimum possible level. + * + * Default: `false`. + */ + changeLevel?: boolean; + /** + * Whether to compact the bottom-most level of data. + * + * Default: `false`. + */ + compactBottomMostLevel?: boolean; +}; + /** * Definition of an AQL User Function. */ @@ -1539,14 +1714,14 @@ export type ServiceConfiguration = { * by software when managing the service. */ type: - | "integer" - | "boolean" - | "string" - | "number" - | "json" - | "password" - | "int" - | "bool"; + | "integer" + | "boolean" + | "string" + | "number" + | "json" + | "password" + | "int" + | "bool"; /** * Current value of the configuration option as stored internally. */ @@ -1726,10 +1901,10 @@ export type ServiceTestSuiteReport = { export type ServiceTestXunitTest = | ["testcase", { classname: string; name: string; time: number }] | [ - "testcase", - { classname: string; name: string; time: number }, - ["failure", { message: string; type: string }, string], - ]; + "testcase", + { classname: string; name: string; time: number }, + ["failure", { message: string; type: string }, string], + ]; /** * Test results for a Foxx service's tests in XUnit format using the JSONML @@ -2224,7 +2399,8 @@ export class Database { basePath, ...opts }: RequestOptions & { absolutePath?: boolean }, - transform: false | ((res: ArangojsResponse) => ReturnType) = (res) => res.parsedBody + transform: false | ((res: ArangojsResponse) => ReturnType) = (res) => + res.parsedBody ): Promise { if (!absolutePath) { basePath = `/_db/${encodeURIComponent(this._name)}${basePath || ""}`; @@ -2534,6 +2710,24 @@ export class Database { }); } + /** + * Fetches detailed storage engine performance and resource usage information + * from the ArangoDB server. + * + * @example + * ```js + * const db = new Database(); + * const stats = await db.engineStats(); + * // the stats object contains the storage engine stats + * ``` + */ + engineStats(): Promise { + return this.request({ + method: "GET", + path: "/_api/engine/stats", + }); + } + /** * Retrives the server's current system time in milliseconds with microsecond * precision. @@ -2569,7 +2763,7 @@ export class Database { /** * Fetches availability information about the server. - * + * * @param graceful - If set to `true`, the method will always return `false` * instead of throwing an error; otherwise `false` will only be returned * when the server responds with a 503 status code or an ArangoDB error with @@ -2583,10 +2777,13 @@ export class Database { */ async availability(graceful = false): Promise { try { - return this.request({ - method: "GET", - path: "/_admin/server/availability", - }, (res) => res.parsedBody.mode); + return this.request( + { + method: "GET", + path: "/_admin/server/availability", + }, + (res) => res.parsedBody.mode + ); } catch (e) { if (graceful) return false; if ((isArangoError(e) || e instanceof HttpError) && e.code === 503) { @@ -2598,7 +2795,7 @@ export class Database { /** * Fetches deployment information about the server for support purposes. - * + * * Note that this API may reveal sensitive data about the deployment. */ supportInfo(): Promise { @@ -2608,6 +2805,51 @@ export class Database { }); } + /** + * Fetches the license information and status of an Enterprise Edition server. + */ + getLicense(): Promise { + return this.request({ + method: "GET", + path: "/_admin/license", + }); + } + + /** + * Set a new license for an Enterprise Edition server. + * + * @param license - The license as a base 64 encoded string. + * @param force - If set to `true`, the license will be changed even if it + * expires sooner than the current license. + */ + setLicense(license: string, force = false): Promise { + return this.request( + { + method: "PUT", + path: "/_admin/license", + body: license, + search: { force }, + }, + () => undefined + ); + } + + /** + * Compacts all databases on the server. + * + * @param options - Options for compacting the databases. + */ + compact(options: CompactOptions = {}): Promise { + return this.request( + { + method: "PUT", + path: "/_admin/compact", + body: options, + }, + () => undefined + ); + } + /** * Attempts to initiate a clean shutdown of the server. */ @@ -2700,6 +2942,8 @@ export class Database { * Computes a set of move shard operations to rebalance the cluster and * executes them. * + * @param options - Options for rebalancing the cluster. + * * @example * ```js * const db = new Database(); @@ -2711,14 +2955,14 @@ export class Database { * ``` */ rebalanceCluster( - opts: ClusterRebalanceOptions + options: ClusterRebalanceOptions ): Promise { return this.request({ method: "PUT", path: "/_admin/cluster/rebalance", body: { version: 1, - ...opts, + ...options, }, }); } @@ -3739,14 +3983,14 @@ export class Database { ): Promise { const databaseName = isArangoDatabase(database) ? database.name - : database ?? - (isArangoCollection(collection) - ? ((collection as any)._db as Database).name - : this._name); + : (database ?? + (isArangoCollection(collection) + ? ((collection as any)._db as Database).name + : this._name)); const suffix = collection ? `/${encodeURIComponent( - isArangoCollection(collection) ? collection.name : collection - )}` + isArangoCollection(collection) ? collection.name : collection + )}` : ""; return this.request( { @@ -3840,14 +4084,14 @@ export class Database { ): Promise>> { const databaseName = isArangoDatabase(database) ? database.name - : database ?? - (isArangoCollection(collection) - ? ((collection as any)._db as Database).name - : this._name); + : (database ?? + (isArangoCollection(collection) + ? ((collection as any)._db as Database).name + : this._name)); const suffix = collection ? `/${encodeURIComponent( - isArangoCollection(collection) ? collection.name : collection - )}` + isArangoCollection(collection) ? collection.name : collection + )}` : ""; return this.request( { @@ -3930,14 +4174,14 @@ export class Database { ): Promise>> { const databaseName = isArangoDatabase(database) ? database.name - : database ?? - (isArangoCollection(collection) - ? ((collection as any)._db as Database).name - : this._name); + : (database ?? + (isArangoCollection(collection) + ? ((collection as any)._db as Database).name + : this._name)); const suffix = collection ? `/${encodeURIComponent( - isArangoCollection(collection) ? collection.name : collection - )}` + isArangoCollection(collection) ? collection.name : collection + )}` : ""; return this.request( { @@ -4458,7 +4702,7 @@ export class Database { } catch (e) { try { await trx.abort(); - } catch { } + } catch {} throw e; } } @@ -4881,14 +5125,14 @@ export class Database { return this.request( options ? { - method: "PUT", - path: "/_api/query/properties", - body: options, - } + method: "PUT", + path: "/_api/query/properties", + body: options, + } : { - method: "GET", - path: "/_api/query/properties", - } + method: "GET", + path: "/_api/query/properties", + } ); } @@ -4981,6 +5225,80 @@ export class Database { () => undefined ); } + + /** + * Fetches a list of all entries in the AQL query results cache of the + * current database. + * + * @example + * ```js + * const db = new Database(); + * const entries = await db.listQueryCacheEntries(); + * console.log(entries); + * ``` + */ + listQueryCacheEntries(): Promise { + return this.request({ + path: "/_api/query-cache/entries", + }); + } + + /** + * Clears the AQL query results cache of the current database. + * + * @example + * ```js + * const db = new Database(); + * await db.clearQueryCache(); + * // Cache is now cleared + * ``` + */ + clearQueryCache(): Promise { + return this.request( + { + method: "DELETE", + path: "/_api/query-cache", + }, + () => undefined + ); + } + + /** + * Fetches the global properties for the AQL query results cache. + * + * @example + * ```js + * const db = new Database(); + * const properties = await db.getQueryCacheProperties(); + * console.log(properties); + * ``` + */ + getQueryCacheProperties(): Promise { + return this.request({ + path: "/_api/query-cache/properties", + }); + } + + /** + * Updates the global properties for the AQL query results cache. + * + * @param properties - The new properties for the AQL query results cache. + * + * @example + * ```js + * const db = new Database(); + * await db.setQueryCacheProperties({ maxResults: 9000 }); + * ``` + */ + setQueryCacheProperties( + properties: QueryCachePropertiesOptions + ): Promise { + return this.request({ + method: "PUT", + path: "/_api/query-cache/properties", + body: properties, + }); + } //#endregion //#region functions From eeae04bf654521faf868787f7a166a3480a05684 Mon Sep 17 00:00:00 2001 From: Alan Plum Date: Mon, 6 Jan 2025 12:51:17 +0100 Subject: [PATCH 03/25] 9.3.0 --- CHANGELOG.md | 4 ++-- package.json | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index c49804d55..6d6f3aba6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -14,7 +14,7 @@ This driver uses semantic versioning: - A change in the major version (e.g. 1.Y.Z -> 2.0.0) indicates _breaking_ changes that require changes in your code to upgrade. -## [Unreleased] +## [9.3.0] - 2025-01-06 ### Added @@ -1993,7 +1993,7 @@ For a detailed list of changes between pre-release versions of v7 see the Graph methods now only return the relevant part of the response body. -[unreleased]: https://github.com/arangodb/arangojs/compare/v9.2.0...HEAD +[9.3.0]: https://github.com/arangodb/arangojs/compare/v9.2.0...v9.3.0 [9.2.0]: https://github.com/arangodb/arangojs/compare/v9.1.0...v9.2.0 [9.1.0]: https://github.com/arangodb/arangojs/compare/v9.0.0...v9.1.0 [9.0.0]: https://github.com/arangodb/arangojs/compare/v8.8.1...v9.0.0 diff --git a/package.json b/package.json index 89e98454e..133c340de 100644 --- a/package.json +++ b/package.json @@ -2,7 +2,7 @@ "private": true, "type": "module", "name": "arangojs", - "version": "9.2.0", + "version": "9.3.0", "engines": { "node": ">=18" }, From 465bbf9090b002dccd478788997ac32928879108 Mon Sep 17 00:00:00 2001 From: Alan Plum Date: Mon, 6 Jan 2025 13:22:21 +0100 Subject: [PATCH 04/25] ServerStatusInformation -> ServerStatusInfo --- CHANGELOG.md | 83 +++++++++++++++++++++++++------------------ src/administration.ts | 2 +- src/databases.ts | 2 +- 3 files changed, 50 insertions(+), 37 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 830dbf222..a9dff97b1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -14,38 +14,7 @@ This driver uses semantic versioning: - A change in the major version (e.g. 1.Y.Z -> 2.0.0) indicates _breaking_ changes that require changes in your code to upgrade. -## [9.3.0] - 2025-01-06 - -### Added - -- Added `db.compact` method (DE-906) - -- Added `db.engineStats` method (DE-932) - -- Added `db.getLicense` and `db.setLicense` methods (DE-949) - -- Added `db.listQueryCacheEntries` method (DE-149) - -- Added `db.clearQueryCache` method (DE-148) - -- Added `db.getQueryCacheProperties` method (DE-150) - -- Added `db.setQueryCacheProperties` method (DE-151) - -- Added `collection.shards` method (DE-939) - -- Added support for `mdi-prefixed` indexes (DE-956) - -- Restored `fulltext` index type support (DE-957) - - The `fulltext` index type is still no longer supported for creating new - indexes but can be used to cast existing indexes from `Index`. - -- Added support for `edge` indexes (DE-958) - - The `Index` type now can also be cast to the `EdgeIndex` type. - -## [10.0.0-rc.0] - 2024-12-10 +## [Unreleased] This is a major release and breaks backwards compatibility. @@ -244,7 +213,8 @@ for upgrading your code to arangojs v10. The following types were moved: `QueryOptions`, `ExplainOptions`, `ExplainPlan`, `ExplainStats`, `SingleExplainResult`, `MultiExplainResult`, - `AstNode`, `ParseResult`, `QueryOptimizerRule`, `QueryTracking`, + `AstNode`, `ParseResult`, `QueryCachePropertiesOptions`, `QueryCacheEntry`, + `QueryCacheProperties`, `QueryOptimizerRule`, `QueryTracking`, `QueryTrackingOptions`, `QueryInfo` and `AqlUserFunction`. - Moved service related types from `arangojs/database` module to new @@ -268,7 +238,10 @@ for upgrading your code to arangojs v10. - Moved server administration related types from `arangojs/database` module to new `arangojs/administration` module - The following types were moved: `QueueTimeMetrics` and `VersionInfo`. + The following types were moved: `CompactOptions`, `EngineInfo`, + `EngineStatsInfo`, `LicenseInfo`, `QueueTimeMetrics`, `ServerAvailability`, + `ServerStatusInformation`, `SingleServerSupportInfo`, `ClusterSupportInfo` + and `VersionInfo`. - Moved configuration related types to new `arangojs/config` module @@ -294,8 +267,11 @@ for upgrading your code to arangojs v10. - `GeoIndex` -> `GeoIndexDescription` - `PersistentIndex` -> `PersistentIndexDescription` - `PrimaryIndex` -> `PrimaryIndexDescription` + - `EdgeIndex` -> `EdgeIndexDescription` - `TtlIndex` -> `TtlIndexDescription` + - `FulltextIndex` -> `FulltextIndexDescription` - `MdiIndex` -> `MdiIndexDescription` + - `MdiPrefixedIndex` -> `MdiPrefixedIndexDescription` - `InvertedIndex` -> `InvertedIndexDescription` - `InternalArangosearchIndex` -> `ArangosearchIndexDescription` - `InternalIndex` -> `InternalIndexDescription` @@ -328,6 +304,7 @@ for upgrading your code to arangojs v10. or `VerbNounResult` naming pattern: - `QueryTracking` -> `QueryTrackingInfo` + - `ServerStatusInformation` -> `ServerStatusInfo` - `CollectionImportResult` -> `ImportDocumentsResult` - `CollectionEdgesResult` -> `DocumentEdgesResult` @@ -403,6 +380,11 @@ for upgrading your code to arangojs v10. This property provides a low-level interface for consuming the items of the cursor and is used by the regular item-wise `Cursor` class internally. +- Added `SystemIndexDescription` type + + This type represents either of the system index types `primary` and `edge` + and can be used to cast indexes returned by `collection.indexes`. + - Added `ProcessedResponse` type This type replaces the previously internal `ArangojsResponse` type and @@ -477,6 +459,37 @@ for upgrading your code to arangojs v10. `cause` property. This error is only thrown when `db.waitForPropagation` is invoked with a `timeout` option and the timeout duration is exceeded. +## [9.3.0] - 2025-01-06 + +### Added + +- Added `db.compact` method (DE-906) + +- Added `db.engineStats` method (DE-932) + +- Added `db.getLicense` and `db.setLicense` methods (DE-949) + +- Added `db.listQueryCacheEntries` method (DE-149) + +- Added `db.clearQueryCache` method (DE-148) + +- Added `db.getQueryCacheProperties` method (DE-150) + +- Added `db.setQueryCacheProperties` method (DE-151) + +- Added `collection.shards` method (DE-939) + +- Added support for `mdi-prefixed` indexes (DE-956) + +- Restored `fulltext` index type support (DE-957) + + The `fulltext` index type is still no longer supported for creating new + indexes but can be used to cast existing indexes from `Index`. + +- Added support for `edge` indexes (DE-958) + + The `Index` type now can also be cast to the `EdgeIndex` type. + ## [9.2.0] - 2024-11-27 ### Added @@ -2427,8 +2440,8 @@ For a detailed list of changes between pre-release versions of v7 see the Graph methods now only return the relevant part of the response body. +[unreleased]: https://github.com/arangodb/arangojs/compare/v9.3.0...HEAD [9.3.0]: https://github.com/arangodb/arangojs/compare/v9.2.0...v9.3.0 -[10.0.0-rc.0]: https://github.com/arangodb/arangojs/compare/v9.2.0...v10.0.0-rc.0 [9.2.0]: https://github.com/arangodb/arangojs/compare/v9.1.0...v9.2.0 [9.1.0]: https://github.com/arangodb/arangojs/compare/v9.0.0...v9.1.0 [9.0.0]: https://github.com/arangodb/arangojs/compare/v8.8.1...v9.0.0 diff --git a/src/administration.ts b/src/administration.ts index 9d148f228..d8862c69f 100644 --- a/src/administration.ts +++ b/src/administration.ts @@ -139,7 +139,7 @@ export type LicenseInfo = { /** * Information about the server status. */ -export type ServerStatusInformation = { +export type ServerStatusInfo = { /** * (Cluster Coordinators and DB-Servers only.) The address of the server. */ diff --git a/src/databases.ts b/src/databases.ts index b4b8e7d12..3e052a546 100644 --- a/src/databases.ts +++ b/src/databases.ts @@ -644,7 +644,7 @@ export class Database { * // serverInfo: detailed information about the server * ``` */ - status(): Promise { + status(): Promise { return this.request({ method: "GET", pathname: "/_admin/status", From 2673b317b87f2668dd754617c7b92a2a80d21a7d Mon Sep 17 00:00:00 2001 From: Alan Plum Date: Mon, 6 Jan 2025 13:35:37 +0100 Subject: [PATCH 05/25] Bump actions --- .github/workflows/codeql-analysis.yml | 8 ++++---- .github/workflows/tests.yml | 14 +++++++------- package.json | 2 +- 3 files changed, 12 insertions(+), 12 deletions(-) diff --git a/.github/workflows/codeql-analysis.yml b/.github/workflows/codeql-analysis.yml index e2c98607f..321095d60 100644 --- a/.github/workflows/codeql-analysis.yml +++ b/.github/workflows/codeql-analysis.yml @@ -36,11 +36,11 @@ jobs: steps: - name: Checkout repository - uses: actions/checkout@v3 + uses: actions/checkout@v4 # Initializes the CodeQL tools for scanning. - name: Initialize CodeQL - uses: github/codeql-action/init@v2 + uses: github/codeql-action/init@v3 with: languages: ${{ matrix.language }} # If you wish to specify custom queries, you can do so here or in a config file. @@ -53,7 +53,7 @@ jobs: # Autobuild attempts to build any compiled languages (C/C++, C#, or Java). # If this step fails, then you should remove it and run the build manually (see below) - name: Autobuild - uses: github/codeql-action/autobuild@v2 + uses: github/codeql-action/autobuild@v3 # ℹī¸ Command-line programs to run using the OS shell. # 📚 See https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsrun @@ -66,4 +66,4 @@ jobs: # ./location_of_script_within_repo/buildscript.sh - name: Perform CodeQL Analysis - uses: github/codeql-action/analyze@v2 + uses: github/codeql-action/analyze@v3 diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml index 707f3987f..abe55ffe3 100644 --- a/.github/workflows/tests.yml +++ b/.github/workflows/tests.yml @@ -13,12 +13,12 @@ jobs: fail-fast: false matrix: module-system: [cjs, esm] - node-version: [18, 20] + node-version: [20, 22, 23] arangodb-version: - - arangodb/arangodb:3.11.8 - - arangodb/enterprise:3.11.8 - - arangodb/arangodb:3.12.0 - - arangodb/enterprise:3.12.0 + - arangodb/arangodb:3.11.12 + - arangodb/enterprise:3.11.12 + - arangodb/arangodb:3.12.3 + - arangodb/enterprise:3.12.3 - arangodb/arangodb-test:devel-nightly - arangodb/enterprise-test:devel-nightly @@ -49,8 +49,8 @@ jobs: strategy: matrix: arangodb-version: - - arangodb/arangodb:3.11.8 - - arangodb/arangodb:3.12.0 + - arangodb/arangodb:3.11.12 + - arangodb/arangodb:3.12.3 - arangodb/arangodb-test:devel-nightly container: diff --git a/package.json b/package.json index 25fb2d52d..edf567413 100644 --- a/package.json +++ b/package.json @@ -4,7 +4,7 @@ "name": "arangojs", "version": "10.0.0", "engines": { - "node": ">=18" + "node": ">=20" }, "license": "Apache-2.0", "description": "The official ArangoDB JavaScript driver.", From 9ab2617ad8418649f3316a1bf0a4adad07bd3305 Mon Sep 17 00:00:00 2001 From: Alan Plum Date: Mon, 6 Jan 2025 13:38:48 +0100 Subject: [PATCH 06/25] Bump docs action --- .github/workflows/docs.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index f804b7e3e..7f4ee5af2 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -75,10 +75,10 @@ jobs: ./node_modules/.bin/typedoc --out gh-pages/${TAG} - name: Commit to gh-pages - uses: EndBug/add-and-commit@v4 + uses: EndBug/add-and-commit@v9 with: cwd: ./gh-pages - ref: gh-pages + push: origin gh-pages --force message: Update ${{ env.TAG }} docs via ${{ github.sha }} env: GITHUB_TOKEN: ${{ github.token }} From 1098c335fbd3eb22e5ca4b4a1d35fb761f3328a4 Mon Sep 17 00:00:00 2001 From: Alan Plum Date: Mon, 6 Jan 2025 13:46:31 +0100 Subject: [PATCH 07/25] Promotion no longer triggers workflow implicitly --- .github/workflows/docs.yml | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 7f4ee5af2..97f34bada 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -4,8 +4,13 @@ on: push: tags: - "v*.*.*" # all semver release tags + workflow_run: + workflows: + - Tests branches: - - stable + - main + types: + - completed jobs: publish-docs: From 0ee00bd081f34da66d852e625a20136d04bd896c Mon Sep 17 00:00:00 2001 From: Alan Plum Date: Mon, 6 Jan 2025 13:55:28 +0100 Subject: [PATCH 08/25] Use relative path? --- .github/workflows/docs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 97f34bada..0292e2bd0 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -27,7 +27,7 @@ jobs: uses: actions/checkout@v4 with: ref: gh-pages - path: gh-pages + path: ./gh-pages - run: apt-get update && apt-get install jq -y - run: npm install -g npm@10 From 80b5c5bccc9389c726ae56678f26f909c3d0aa8d Mon Sep 17 00:00:00 2001 From: Alan Plum Date: Mon, 6 Jan 2025 14:03:05 +0100 Subject: [PATCH 09/25] Workflow run doesn't set event.ref --- .github/workflows/docs.yml | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 0292e2bd0..2d5da578f 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -33,8 +33,7 @@ jobs: - run: npm install -g npm@10 - run: npm install - - name: Set TAG env to devel - if: startsWith( github.event.ref, 'refs/heads/' ) + - name: Set TAG env to devel (default) run: | echo "TAG=devel" >> $GITHUB_ENV echo "IS_PREVIEW=1" >> $GITHUB_ENV From 737bd681df468493c96cacd792ff60f2eee49732 Mon Sep 17 00:00:00 2001 From: Alan Plum Date: Mon, 6 Jan 2025 14:38:28 +0100 Subject: [PATCH 10/25] Tweak typedoc action --- .github/workflows/docs.yml | 35 ++++++++++++++++++----------------- typedoc.json | 9 +++------ 2 files changed, 21 insertions(+), 23 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 2d5da578f..8db544bf7 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -33,27 +33,28 @@ jobs: - run: npm install -g npm@10 - run: npm install - - name: Set TAG env to devel (default) + - name: Set VERSION env to devel (default) run: | - echo "TAG=devel" >> $GITHUB_ENV + echo "VERSION=devel" >> $GITHUB_ENV echo "IS_PREVIEW=1" >> $GITHUB_ENV echo "IS_BACKPORT=0" >> $GITHUB_ENV - - name: Set TAG env to ref tag - if: startsWith( github.event.ref, 'refs/tags/v' ) + - name: Set VERSION env from tag name + if: startsWith(github.ref, 'refs/tags/v') run: | - export TAG=$(echo ${{ github.event.ref }} | sed -e 's/^refs\/tags\/v//') - echo "TAG=${TAG}" >> $GITHUB_ENV - echo "IS_PREVIEW=$(node -p "Number('${TAG}'.includes('-'))")" >> $GITHUB_ENV - echo "IS_BACKPORT=$(node -p "Number(require('semver').lt('${TAG}','$(tail -n 1 gh-pages/VERSION.md)'))")" >> $GITHUB_ENV + export REF_NAME=${{github.ref_name}} + export VERSION=${REF_NAME:1} + echo "VERSION=${VERSION}" >> $GITHUB_ENV + echo "IS_PREVIEW=$(node -p "Number('${VERSION}'.includes('-'))")" >> $GITHUB_ENV + echo "IS_BACKPORT=$(node -p "Number(require('semver').lt('${VERSION}','$(tail -n 1 gh-pages/VERSION.md)'))")" >> $GITHUB_ENV - name: Update VERSION / latest - if: env.IS_PREVIEW != 1 + if: env.IS_BACKPORT != 1 && env.IS_PREVIEW != 1 run: | echo '---\npermalink: /VERSION\ntitle: "VERSION"\n---\n' > gh-pages/VERSION.md - echo $TAG >> gh-pages/VERSION + echo $VERSION >> gh-pages/VERSION unlink gh-pages/latest - ln -s $TAG gh-pages/latest + ln -s $VERSION gh-pages/latest - name: Update CHANGELOG / MIGRATING if: env.IS_BACKPORT != 1 @@ -65,24 +66,24 @@ jobs: - name: Remove old docs if present run: | - rm -rf gh-pages/${TAG} + rm -rf gh-pages/${VERSION} - name: Rebuild docs for tag - if: env.TAG != 'devel' + if: env.VERSION != 'devel' run: | - ./node_modules/.bin/typedoc --includeVersion --gitRevision ${TAG} --out gh-pages/${TAG} + ./node_modules/.bin/typedoc --includeVersion --gitRevision ${{ github.ref_name }} --out gh-pages/${VERSION} node -p 'var all=fs.readdirSync("gh-pages",{withFileTypes:true}).flatMap(f=>f.isDirectory()&&!isNaN(f.name.charAt(0))?[f.name]:[]).sort(require("semver").rcompare);JSON.stringify({all,stable:all.filter(s=>!s.includes("-"))})' > gh-pages/_data/versions.json - name: Rebuild docs for devel - if: env.TAG == 'devel' + if: env.VERSION == 'devel' run: | - ./node_modules/.bin/typedoc --out gh-pages/${TAG} + ./node_modules/.bin/typedoc --gitRevision ${{ github.sha }} --out gh-pages/${VERSION} - name: Commit to gh-pages uses: EndBug/add-and-commit@v9 with: cwd: ./gh-pages push: origin gh-pages --force - message: Update ${{ env.TAG }} docs via ${{ github.sha }} + message: Update ${{ env.VERSION }} docs via ${{ github.sha }} env: GITHUB_TOKEN: ${{ github.token }} diff --git a/typedoc.json b/typedoc.json index 9749391b2..8b61f5458 100644 --- a/typedoc.json +++ b/typedoc.json @@ -1,16 +1,13 @@ { "out": "tsdoc", + "cacheBust": true, "githubPages": true, "disableSources": false, "exclude": ["**/lib/*.ts", "**/test/*.ts"], "basePath": "./src", + "gitRemote": "origin", "visibilityFilters": {}, - "intentionallyNotExported": [ - "ArangojsError", - "ArangojsResponse", - "Blob", - "GeneratedAqlQuery" - ], + "intentionallyNotExported": ["Blob", "GeneratedAqlQuery"], "excludeInternal": true, "excludeProtected": true, "excludePrivate": true, From ed952f8d3c1f60afe211bf3ec08f2fbcb3bd1266 Mon Sep 17 00:00:00 2001 From: Alan Plum Date: Mon, 6 Jan 2025 14:50:05 +0100 Subject: [PATCH 11/25] Try to fix docs file links --- .github/workflows/docs.yml | 4 ++-- typedoc.json | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 8db544bf7..722072684 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -71,13 +71,13 @@ jobs: - name: Rebuild docs for tag if: env.VERSION != 'devel' run: | - ./node_modules/.bin/typedoc --includeVersion --gitRevision ${{ github.ref_name }} --out gh-pages/${VERSION} + ./node_modules/.bin/typedoc --gitRevision ${{ github.ref_name }} --out gh-pages/${VERSION} --sourceLinkTemplate https://github.com/${{ github.repository }}/blob/${{ github.ref_name }}/src/{path}:{line} node -p 'var all=fs.readdirSync("gh-pages",{withFileTypes:true}).flatMap(f=>f.isDirectory()&&!isNaN(f.name.charAt(0))?[f.name]:[]).sort(require("semver").rcompare);JSON.stringify({all,stable:all.filter(s=>!s.includes("-"))})' > gh-pages/_data/versions.json - name: Rebuild docs for devel if: env.VERSION == 'devel' run: | - ./node_modules/.bin/typedoc --gitRevision ${{ github.sha }} --out gh-pages/${VERSION} + ./node_modules/.bin/typedoc --gitRevision ${{ github.sha }} --out gh-pages/${VERSION} --sourceLinkTemplate https://github.com/${{ github.repository }}/blob/${{ github.sha }}/src/{path}:{line} - name: Commit to gh-pages uses: EndBug/add-and-commit@v9 diff --git a/typedoc.json b/typedoc.json index 8b61f5458..d303ec223 100644 --- a/typedoc.json +++ b/typedoc.json @@ -11,7 +11,7 @@ "excludeInternal": true, "excludeProtected": true, "excludePrivate": true, - "includeVersion": false, + "includeVersion": true, "entryPoints": ["src"], "entryPointStrategy": "expand", "validation": { From ced67cbff47733b85dfad1d21ff0dbbedb9a87c6 Mon Sep 17 00:00:00 2001 From: Alan Plum Date: Mon, 6 Jan 2025 18:58:52 +0100 Subject: [PATCH 12/25] Tweak docs --- .github/workflows/docs.yml | 4 +- CHANGELOG.md | 5 ++ src/analyzers.ts | 13 +-- src/databases.ts | 33 ++++---- src/graphs.ts | 168 ++++++++++++++++++------------------- src/indexes.ts | 9 +- src/queries.ts | 7 +- src/services.ts | 27 +++--- src/views.ts | 15 ++-- typedoc.json | 19 ++--- 10 files changed, 156 insertions(+), 144 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 722072684..6f0ea28d8 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -71,13 +71,13 @@ jobs: - name: Rebuild docs for tag if: env.VERSION != 'devel' run: | - ./node_modules/.bin/typedoc --gitRevision ${{ github.ref_name }} --out gh-pages/${VERSION} --sourceLinkTemplate https://github.com/${{ github.repository }}/blob/${{ github.ref_name }}/src/{path}:{line} + ./node_modules/.bin/typedoc --includeVersion --out gh-pages/${VERSION} --sourceLinkTemplate "https://github.com/${{ github.repository }}/blob/${{ github.ref_name }}/src/{path}:{line}" node -p 'var all=fs.readdirSync("gh-pages",{withFileTypes:true}).flatMap(f=>f.isDirectory()&&!isNaN(f.name.charAt(0))?[f.name]:[]).sort(require("semver").rcompare);JSON.stringify({all,stable:all.filter(s=>!s.includes("-"))})' > gh-pages/_data/versions.json - name: Rebuild docs for devel if: env.VERSION == 'devel' run: | - ./node_modules/.bin/typedoc --gitRevision ${{ github.sha }} --out gh-pages/${VERSION} --sourceLinkTemplate https://github.com/${{ github.repository }}/blob/${{ github.sha }}/src/{path}:{line} + ./node_modules/.bin/typedoc --out gh-pages/${VERSION} --sourceLinkTemplate https://github.com/${{ github.repository }}/blob/${{ github.sha }}/src/{path}:{line} - name: Commit to gh-pages uses: EndBug/add-and-commit@v9 diff --git a/CHANGELOG.md b/CHANGELOG.md index a9dff97b1..e2b877502 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -47,6 +47,11 @@ for upgrading your code to arangojs v10. The following options were moved: `credentials`, `headers` and `keepalive`. +- `db.setUserAccessLevel` now takes `grant` as a separate parameter + + The parameter was previously passed as an additional property in the + `options` parameter. + #### Error handling - Errors encountered before a request completes are now wrapped in a diff --git a/src/analyzers.ts b/src/analyzers.ts index 05a5f31a9..e99dbe9bf 100644 --- a/src/analyzers.ts +++ b/src/analyzers.ts @@ -8,8 +8,8 @@ * * @packageDocumentation */ -import * as databases from "./databases.js"; import * as connection from "./connection.js"; +import * as databases from "./databases.js"; import * as errors from "./errors.js"; import { ANALYZER_NOT_FOUND } from "./lib/codes.js"; @@ -75,7 +75,10 @@ export type CreateAnalyzerOptions = | CreateGeoPointAnalyzerOptions | CreateGeoS2AnalyzerOptions; -type CreateAnalyzerOptionsType< +/** + * Shared attributes of all Analyzer creation options. + */ +export type CreateAnalyzerOptionsType< Type extends AnalyzerType, Properties = void, > = Properties extends void @@ -580,7 +583,7 @@ export type AnalyzerDescription = /** * Shared attributes of all Analyzer descriptions. */ -type AnalyzerDescriptionType< +export type AnalyzerDescriptionType< Type extends string, Properties = Record, > = { @@ -931,7 +934,7 @@ export class Analyzer { * ``` */ create( - options: Options, + options: Options ): Promise< Options extends CreateIdentityAnalyzerOptions ? IdentityAnalyzerDescription @@ -991,7 +994,7 @@ export class Analyzer { * ``` */ drop( - force: boolean = false, + force: boolean = false ): Promise> { return this._db.request({ method: "DELETE", diff --git a/src/databases.ts b/src/databases.ts index 3e052a546..52d72333c 100644 --- a/src/databases.ts +++ b/src/databases.ts @@ -1855,8 +1855,7 @@ export class Database { * given collection in the given database. * * @param username - Name of the ArangoDB user to fetch the access level for. - * @param database - Database to fetch the access level for. - * @param collection - Collection to fetch the access level for. + * @param options - Collection and/or database to fetch the access level for. * * @example * ```js @@ -1921,8 +1920,9 @@ export class Database { */ getUserAccessLevel( username: string, - { database, collection }: users.UserAccessLevelOptions + options: users.UserAccessLevelOptions ): Promise { + const { database, collection } = options; const databaseName = isArangoDatabase(database) ? database.name : (database ?? @@ -1951,8 +1951,7 @@ export class Database { * given collection in the given database. * * @param username - Name of the ArangoDB user to set the access level for. - * @param database - Database to set the access level for. - * @param collection - Collection to set the access level for. + * @param options - Database and/or collection to set the access level for. * @param grant - Access level to set for the given user. * * @example @@ -2020,12 +2019,10 @@ export class Database { */ setUserAccessLevel( username: string, - { - database, - collection, - grant, - }: users.UserAccessLevelOptions & { grant: users.AccessLevel } + options: users.UserAccessLevelOptions, + grant: users.AccessLevel ): Promise>> { + const { database, collection } = options; const databaseName = isArangoDatabase(database) ? database.name : (database ?? @@ -2056,8 +2053,7 @@ export class Database { * given collection in the given database. * * @param username - Name of the ArangoDB user to clear the access level for. - * @param database - Database to clear the access level for. - * @param collection - Collection to clear the access level for. + * @param options - Database and/or collection to clear the access level for. * * @example * ```js @@ -2116,8 +2112,9 @@ export class Database { */ clearUserAccessLevel( username: string, - { database, collection }: users.UserAccessLevelOptions + options: users.UserAccessLevelOptions ): Promise>> { + const { database, collection } = options; const databaseName = isArangoDatabase(database) ? database.name : (database ?? @@ -2393,7 +2390,7 @@ export class Database { * * See also {@link Database#beginTransaction}. * - * @param id - The `id` of an existing stream transaction. + * @param transactionId - The `id` of an existing stream transaction. * * @example * ```js @@ -3875,7 +3872,7 @@ export class Database { * {@link Database#getServiceDependencies}. * * @param mount - The service's mount point, relative to the database. - * @param cfg - An object mapping dependency aliases to mount points. + * @param deps - An object mapping dependency aliases to mount points. * @param minimal - If set to `true`, the result will only include each * dependency's current mount point. Otherwise it will include the full * definition for each dependency. @@ -3911,7 +3908,7 @@ export class Database { * {@link Database#getServiceDependencies}. * * @param mount - The service's mount point, relative to the database. - * @param cfg - An object mapping dependency aliases to mount points. + * @param deps - An object mapping dependency aliases to mount points. * @param minimal - If set to `true`, the result will only include each * dependency's current mount point. Otherwise it will include the full * definition for each dependency. @@ -3960,7 +3957,7 @@ export class Database { * {@link Database#getServiceDependencies}. * * @param mount - The service's mount point, relative to the database. - * @param cfg - An object mapping dependency aliases to mount points. + * @param deps - An object mapping dependency aliases to mount points. * @param minimal - If set to `true`, the result will only include each * dependency's current mount point. Otherwise it will include the full * definition for each dependency. @@ -3996,7 +3993,7 @@ export class Database { * {@link Database#getServiceDependencies}. * * @param mount - The service's mount point, relative to the database. - * @param cfg - An object mapping dependency aliases to mount points. + * @param deps - An object mapping dependency aliases to mount points. * @param minimal - If set to `true`, the result will only include each * dependency's current mount point. Otherwise it will include the full * definition for each dependency. diff --git a/src/graphs.ts b/src/graphs.ts index f82eb9373..4399e389d 100644 --- a/src/graphs.ts +++ b/src/graphs.ts @@ -32,7 +32,7 @@ function mungeGharialResponse(body: any, prop: "vertex" | "edge" | "removed") { function coerceEdgeDefinition(options: EdgeDefinitionOptions): EdgeDefinition { const edgeDefinition = {} as EdgeDefinition; edgeDefinition.collection = collections.collectionToString( - options.collection, + options.collection ); edgeDefinition.from = Array.isArray(options.from) ? options.from.map(collections.collectionToString) @@ -480,10 +480,10 @@ export class GraphVertexCollection< { method: "HEAD", pathname: `/_api/gharial/${encodeURIComponent( - this.graph.name, + this.graph.name )}/vertex/${encodeURI(documents._documentHandle(selector, this._name))}`, }, - () => true, + () => true ); } catch (err: any) { if (err.code === 404) { @@ -529,7 +529,7 @@ export class GraphVertexCollection< */ async vertex( selector: documents.DocumentSelector, - options?: ReadGraphDocumentOptions, + options?: ReadGraphDocumentOptions ): Promise>; /** * Retrieves the vertex matching the given key or id. @@ -568,11 +568,11 @@ export class GraphVertexCollection< */ async vertex( selector: documents.DocumentSelector, - graceful: boolean, + graceful: boolean ): Promise>; async vertex( selector: documents.DocumentSelector, - options: boolean | ReadGraphDocumentOptions = {}, + options: boolean | ReadGraphDocumentOptions = {} ): Promise | null> { if (typeof options === "boolean") { options = { graceful: options }; @@ -588,13 +588,13 @@ export class GraphVertexCollection< const result = this._db.request( { pathname: `/_api/gharial/${encodeURIComponent( - this.graph.name, + this.graph.name )}/vertex/${encodeURI(documents._documentHandle(selector, this._name))}`, headers, search, allowDirtyRead, }, - (res) => res.parsedBody.vertex, + (res) => res.parsedBody.vertex ); if (!graceful) return result; try { @@ -626,24 +626,24 @@ export class GraphVertexCollection< */ save( data: documents.DocumentData, - options?: InsertGraphDocumentOptions, + options?: InsertGraphDocumentOptions ): Promise< documents.DocumentMetadata & { new?: documents.Document } >; save( data: documents.DocumentData, - options?: InsertGraphDocumentOptions, + options?: InsertGraphDocumentOptions ) { return this._db.request( { method: "POST", pathname: `/_api/gharial/${encodeURIComponent( - this.graph.name, + this.graph.name )}/vertex/${encodeURIComponent(this._name)}`, body: data, search: options, }, - (res) => mungeGharialResponse(res.parsedBody, "vertex"), + (res) => mungeGharialResponse(res.parsedBody, "vertex") ); } @@ -673,8 +673,8 @@ export class GraphVertexCollection< */ replace( selector: documents.DocumentSelector, - newValue: documents.DocumentData, - options?: ReplaceGraphDocumentOptions, + newData: documents.DocumentData, + options?: ReplaceGraphDocumentOptions ): Promise< documents.DocumentMetadata & { new?: documents.Document; @@ -683,8 +683,8 @@ export class GraphVertexCollection< >; replace( selector: documents.DocumentSelector, - newValue: documents.DocumentData, - options: ReplaceGraphDocumentOptions = {}, + newData: documents.DocumentData, + options: ReplaceGraphDocumentOptions = {} ) { if (typeof options === "string") { options = { rev: options }; @@ -696,13 +696,13 @@ export class GraphVertexCollection< { method: "PUT", pathname: `/_api/gharial/${encodeURIComponent( - this.graph.name, + this.graph.name )}/vertex/${encodeURI(documents._documentHandle(selector, this._name))}`, - body: newValue, + body: newData, search, headers, }, - (res) => mungeGharialResponse(res.parsedBody, "vertex"), + (res) => mungeGharialResponse(res.parsedBody, "vertex") ); } @@ -732,8 +732,8 @@ export class GraphVertexCollection< */ update( selector: documents.DocumentSelector, - newValue: documents.Patch>, - options?: ReplaceGraphDocumentOptions, + newData: documents.Patch>, + options?: ReplaceGraphDocumentOptions ): Promise< documents.DocumentMetadata & { new?: documents.Document; @@ -742,8 +742,8 @@ export class GraphVertexCollection< >; update( selector: documents.DocumentSelector, - newValue: documents.Patch>, - options: ReplaceGraphDocumentOptions = {}, + newData: documents.Patch>, + options: ReplaceGraphDocumentOptions = {} ) { if (typeof options === "string") { options = { rev: options }; @@ -755,13 +755,13 @@ export class GraphVertexCollection< { method: "PATCH", pathname: `/_api/gharial/${encodeURIComponent( - this.graph.name, + this.graph.name )}/vertex/${encodeURI(documents._documentHandle(selector, this._name))}`, - body: newValue, + body: newData, search, headers, }, - (res) => mungeGharialResponse(res.parsedBody, "vertex"), + (res) => mungeGharialResponse(res.parsedBody, "vertex") ); } @@ -794,13 +794,13 @@ export class GraphVertexCollection< */ remove( selector: documents.DocumentSelector, - options?: RemoveGraphDocumentOptions, + options?: RemoveGraphDocumentOptions ): Promise< documents.DocumentMetadata & { old?: documents.Document } >; remove( selector: documents.DocumentSelector, - options: RemoveGraphDocumentOptions = {}, + options: RemoveGraphDocumentOptions = {} ) { if (typeof options === "string") { options = { rev: options }; @@ -812,12 +812,12 @@ export class GraphVertexCollection< { method: "DELETE", pathname: `/_api/gharial/${encodeURIComponent( - this.graph.name, + this.graph.name )}/vertex/${encodeURI(documents._documentHandle(selector, this._name))}`, search, headers, }, - (res) => mungeGharialResponse(res.parsedBody, "removed"), + (res) => mungeGharialResponse(res.parsedBody, "removed") ); } } @@ -918,10 +918,10 @@ export class GraphEdgeCollection< { method: "HEAD", pathname: `/_api/gharial/${encodeURIComponent( - this.graph.name, + this.graph.name )}/edge/${encodeURI(documents._documentHandle(selector, this._name))}`, }, - () => true, + () => true ); } catch (err: any) { if (err.code === 404) { @@ -967,7 +967,7 @@ export class GraphEdgeCollection< */ async edge( selector: documents.DocumentSelector, - options?: ReadGraphDocumentOptions, + options?: ReadGraphDocumentOptions ): Promise>; /** * Retrieves the edge matching the given key or id. @@ -1006,11 +1006,11 @@ export class GraphEdgeCollection< */ async edge( selector: documents.DocumentSelector, - graceful: boolean, + graceful: boolean ): Promise>; async edge( selector: documents.DocumentSelector, - options: boolean | ReadGraphDocumentOptions = {}, + options: boolean | ReadGraphDocumentOptions = {} ): Promise | null> { if (typeof options === "boolean") { options = { graceful: options }; @@ -1026,12 +1026,12 @@ export class GraphEdgeCollection< const result = this._db.request( { pathname: `/_api/gharial/${encodeURIComponent( - this.graph.name, + this.graph.name )}/edge/${encodeURI(documents._documentHandle(selector, this._name))}`, search, allowDirtyRead, }, - (res) => res.parsedBody.edge, + (res) => res.parsedBody.edge ); if (!graceful) return result; try { @@ -1062,24 +1062,24 @@ export class GraphEdgeCollection< */ save( data: documents.EdgeData, - options?: InsertGraphDocumentOptions, + options?: InsertGraphDocumentOptions ): Promise< documents.DocumentMetadata & { new?: documents.Edge } >; save( data: documents.EdgeData, - options?: InsertGraphDocumentOptions, + options?: InsertGraphDocumentOptions ) { return this._db.request( { method: "POST", pathname: `/_api/gharial/${encodeURIComponent( - this.graph.name, + this.graph.name )}/edge/${encodeURIComponent(this._name)}`, body: data, search: options, }, - (res) => mungeGharialResponse(res.parsedBody, "edge"), + (res) => mungeGharialResponse(res.parsedBody, "edge") ); } @@ -1117,8 +1117,8 @@ export class GraphEdgeCollection< */ replace( selector: documents.DocumentSelector, - newValue: documents.EdgeData, - options?: ReplaceGraphDocumentOptions, + newData: documents.EdgeData, + options?: ReplaceGraphDocumentOptions ): Promise< documents.DocumentMetadata & { new?: documents.Edge; @@ -1127,8 +1127,8 @@ export class GraphEdgeCollection< >; replace( selector: documents.DocumentSelector, - newValue: documents.EdgeData, - options: ReplaceGraphDocumentOptions = {}, + newData: documents.EdgeData, + options: ReplaceGraphDocumentOptions = {} ) { if (typeof options === "string") { options = { rev: options }; @@ -1140,13 +1140,13 @@ export class GraphEdgeCollection< { method: "PUT", pathname: `/_api/gharial/${encodeURIComponent( - this.graph.name, + this.graph.name )}/edge/${encodeURI(documents._documentHandle(selector, this._name))}`, - body: newValue, + body: newData, search, headers, }, - (res) => mungeGharialResponse(res.parsedBody, "edge"), + (res) => mungeGharialResponse(res.parsedBody, "edge") ); } @@ -1184,8 +1184,8 @@ export class GraphEdgeCollection< */ update( selector: documents.DocumentSelector, - newValue: documents.Patch>, - options?: ReplaceGraphDocumentOptions, + newData: documents.Patch>, + options?: ReplaceGraphDocumentOptions ): Promise< documents.DocumentMetadata & { new?: documents.Edge; @@ -1194,8 +1194,8 @@ export class GraphEdgeCollection< >; update( selector: documents.DocumentSelector, - newValue: documents.Patch>, - options: ReplaceGraphDocumentOptions = {}, + newData: documents.Patch>, + options: ReplaceGraphDocumentOptions = {} ) { if (typeof options === "string") { options = { rev: options }; @@ -1207,13 +1207,13 @@ export class GraphEdgeCollection< { method: "PATCH", pathname: `/_api/gharial/${encodeURIComponent( - this.graph.name, + this.graph.name )}/edge/${encodeURI(documents._documentHandle(selector, this._name))}`, - body: newValue, + body: newData, search, headers, }, - (res) => mungeGharialResponse(res.parsedBody, "edge"), + (res) => mungeGharialResponse(res.parsedBody, "edge") ); } @@ -1238,13 +1238,13 @@ export class GraphEdgeCollection< */ remove( selector: documents.DocumentSelector, - options?: RemoveGraphDocumentOptions, + options?: RemoveGraphDocumentOptions ): Promise< documents.DocumentMetadata & { old?: documents.Edge } >; remove( selector: documents.DocumentSelector, - options: RemoveGraphDocumentOptions = {}, + options: RemoveGraphDocumentOptions = {} ) { if (typeof options === "string") { options = { rev: options }; @@ -1256,12 +1256,12 @@ export class GraphEdgeCollection< { method: "DELETE", pathname: `/_api/gharial/${encodeURIComponent( - this.graph.name, + this.graph.name )}/edge/${encodeURI(documents._documentHandle(selector, this._name))}`, search, headers, }, - (res) => mungeGharialResponse(res.parsedBody, "removed"), + (res) => mungeGharialResponse(res.parsedBody, "removed") ); } } @@ -1351,7 +1351,7 @@ export class Graph { get(): Promise { return this._db.request( { pathname: `/_api/gharial/${encodeURIComponent(this._name)}` }, - (res) => res.parsedBody.graph, + (res) => res.parsedBody.graph ); } @@ -1378,7 +1378,7 @@ export class Graph { */ create( edgeDefinitions: EdgeDefinitionOptions[], - options: CreateGraphOptions = {}, + options: CreateGraphOptions = {} ): Promise { const { orphanCollections, satellites, waitForSync, isSmart, ...opts } = options; @@ -1402,7 +1402,7 @@ export class Graph { }, search: { waitForSync }, }, - (res) => res.parsedBody.graph, + (res) => res.parsedBody.graph ); } @@ -1427,7 +1427,7 @@ export class Graph { pathname: `/_api/gharial/${encodeURIComponent(this._name)}`, search: { dropCollections }, }, - (res) => res.parsedBody.removed, + (res) => res.parsedBody.removed ); } @@ -1439,12 +1439,12 @@ export class Graph { * @param collection - Name of the vertex collection. */ vertexCollection = any>( - collection: string | collections.ArangoCollection, + collection: string | collections.ArangoCollection ): GraphVertexCollection { return new GraphVertexCollection( this._db, collections.collectionToString(collection), - this, + this ); } @@ -1472,7 +1472,7 @@ export class Graph { listVertexCollections(): Promise { return this._db.request( { pathname: `/_api/gharial/${encodeURIComponent(this._name)}/vertex` }, - (res) => res.parsedBody.collections, + (res) => res.parsedBody.collections ); } @@ -1524,7 +1524,7 @@ export class Graph { */ addVertexCollection( collection: string | collections.ArangoCollection, - options: AddVertexCollectionOptions = {}, + options: AddVertexCollectionOptions = {} ): Promise { const { satellites, ...opts } = options; return this._db.request( @@ -1539,7 +1539,7 @@ export class Graph { }, }, }, - (res) => res.parsedBody.graph, + (res) => res.parsedBody.graph ); } @@ -1567,19 +1567,19 @@ export class Graph { */ removeVertexCollection( collection: string | collections.ArangoCollection, - dropCollection: boolean = false, + dropCollection: boolean = false ): Promise { return this._db.request( { method: "DELETE", pathname: `/_api/gharial/${encodeURIComponent( - this._name, + this._name )}/vertex/${encodeURIComponent(collections.collectionToString(collection))}`, search: { dropCollection, }, }, - (res) => res.parsedBody.graph, + (res) => res.parsedBody.graph ); } @@ -1607,12 +1607,12 @@ export class Graph { * ``` */ edgeCollection = any>( - collection: string | collections.ArangoCollection, + collection: string | collections.ArangoCollection ): GraphEdgeCollection { return new GraphEdgeCollection( this._db, collections.collectionToString(collection), - this, + this ); } @@ -1640,7 +1640,7 @@ export class Graph { listEdgeCollections(): Promise { return this._db.request( { pathname: `/_api/gharial/${encodeURIComponent(this._name)}/edge` }, - (res) => res.parsedBody.collections, + (res) => res.parsedBody.collections ); } @@ -1692,7 +1692,7 @@ export class Graph { */ addEdgeDefinition( edgeDefinition: EdgeDefinitionOptions, - options: AddEdgeDefinitionOptions = {}, + options: AddEdgeDefinitionOptions = {} ): Promise { const { satellites, ...opts } = options; return this._db.request( @@ -1707,7 +1707,7 @@ export class Graph { }, }, }, - (res) => res.parsedBody.graph, + (res) => res.parsedBody.graph ); } @@ -1738,7 +1738,7 @@ export class Graph { */ replaceEdgeDefinition( edgeDefinition: EdgeDefinitionOptions, - options?: ReplaceEdgeDefinitionOptions, + options?: ReplaceEdgeDefinitionOptions ): Promise; /** * Replaces an edge definition in this graph. The existing edge definition @@ -1769,7 +1769,7 @@ export class Graph { replaceEdgeDefinition( collection: string | collections.ArangoCollection, edgeDefinition: EdgeDefinitionOptions, - options?: ReplaceEdgeDefinitionOptions, + options?: ReplaceEdgeDefinitionOptions ): Promise; replaceEdgeDefinition( collectionOrEdgeDefinitionOptions: @@ -1779,7 +1779,7 @@ export class Graph { edgeDefinitionOrOptions?: | EdgeDefinitionOptions | ReplaceEdgeDefinitionOptions, - options: ReplaceEdgeDefinitionOptions = {}, + options: ReplaceEdgeDefinitionOptions = {} ) { let collection = collectionOrEdgeDefinitionOptions as | string @@ -1802,7 +1802,7 @@ export class Graph { { method: "PUT", pathname: `/_api/gharial/${encodeURIComponent( - this._name, + this._name )}/edge/${encodeURIComponent(collections.collectionToString(collection))}`, body: { ...coerceEdgeDefinition(edgeDefinition), @@ -1812,7 +1812,7 @@ export class Graph { }, }, }, - (res) => res.parsedBody.graph, + (res) => res.parsedBody.graph ); } @@ -1840,19 +1840,19 @@ export class Graph { */ removeEdgeDefinition( collection: string | collections.ArangoCollection, - dropCollection: boolean = false, + dropCollection: boolean = false ): Promise { return this._db.request( { method: "DELETE", pathname: `/_api/gharial/${encodeURIComponent( - this._name, + this._name )}/edge/${encodeURIComponent(collections.collectionToString(collection))}`, search: { dropCollection, }, }, - (res) => res.parsedBody.graph, + (res) => res.parsedBody.graph ); } } diff --git a/src/indexes.ts b/src/indexes.ts index 3143594ee..ecd686a11 100644 --- a/src/indexes.ts +++ b/src/indexes.ts @@ -64,7 +64,10 @@ export type EnsureIndexOptions = | EnsureMdiPrefixedIndexOptions | EnsureInvertedIndexOptions; -type EnsureIndexOptionsType< +/** + * Shared attributes of all index creation options. + */ +export type EnsureIndexOptionsType< Type extends IndexType, Fields extends any[], Extra extends {} = {}, @@ -658,7 +661,7 @@ export type EdgeIndexDescription = IndexDescriptionType< * An object representing a fulltext index. * * @deprecated The `fulltext` index type was deprecated in ArangoDB 3.10. Use - * {@link views.ArangoSearchView} instead. + * {@link views.View}s instead. */ export type FulltextIndexDescription = IndexDescriptionType< "fulltext", @@ -683,7 +686,7 @@ export type EdgeIndex = IndexDescriptionType< * An object representing a fulltext index. * * @deprecated The `fulltext` index type was deprecated in ArangoDB 3.10. Use - * {@link views.ArangoSearchView} instead. + * {@link views.View} instead. */ export type FulltextIndex = IndexDescriptionType< "fulltext", diff --git a/src/queries.ts b/src/queries.ts index 8f9901787..470cd452a 100644 --- a/src/queries.ts +++ b/src/queries.ts @@ -7,6 +7,7 @@ * * @packageDocumentation */ +/** @import databases from "./databases.js" */ //#region Query operation options /** @@ -185,7 +186,7 @@ export type QueryOptions = { /** * Options for explaining a query. * - * See {@link Database#explain}. + * See {@link databases.Database#explain}. */ export type ExplainOptions = { /** @@ -213,7 +214,7 @@ export type ExplainOptions = { /** * Options for query tracking. * - * See {@link Database#queryTracking}. + * See {@link databases.Database#queryTracking}. */ export type QueryTrackingOptions = { /** @@ -608,7 +609,7 @@ export type UserFunctionDescription = { /** * Whether the function is deterministic. * - * See {@link Database#createFunction}. + * See {@link databases.Database#createFunction}. */ isDeterministic: boolean; }; diff --git a/src/services.ts b/src/services.ts index 0a646b332..0a280523c 100644 --- a/src/services.ts +++ b/src/services.ts @@ -8,30 +8,31 @@ * @packageDocumentation */ import { FoxxManifest } from "./foxx-manifest.js"; +/** @import databases from "./databases.js" */ //#region Service operation options /** * Options for installing the service. * - * See {@link Database#installService}. + * See {@link databases.Database#installService}. */ export type InstallServiceOptions = { /** * An object mapping configuration option names to values. * - * See also {@link Database#getServiceConfiguration}. + * See also {@link databases.Database#getServiceConfiguration}. */ configuration?: Record; /** * An object mapping dependency aliases to mount points. * - * See also {@link Database#getServiceDependencies}. + * See also {@link databases.Database#getServiceDependencies}. */ dependencies?: Record; /** * Whether the service should be installed in development mode. * - * See also {@link Database#setServiceDevelopmentMode}. + * See also {@link databases.Database#setServiceDevelopmentMode}. * * Default: `false` */ @@ -55,25 +56,25 @@ export type InstallServiceOptions = { /** * Options for replacing a service. * - * See {@link Database#replaceService}. + * See {@link databases.Database#replaceService}. */ export type ReplaceServiceOptions = { /** * An object mapping configuration option names to values. * - * See also {@link Database#getServiceConfiguration}. + * See also {@link databases.Database#getServiceConfiguration}. */ configuration?: Record; /** * An object mapping dependency aliases to mount points. * - * See also {@link Database#getServiceDependencies}. + * See also {@link databases.Database#getServiceDependencies}. */ dependencies?: Record; /** * Whether the service should be installed in development mode. * - * See also {@link Database#setServiceDevelopmentMode}. + * See also {@link databases.Database#setServiceDevelopmentMode}. * * Default: `false` */ @@ -111,25 +112,25 @@ export type ReplaceServiceOptions = { /** * Options for upgrading a service. * - * See {@link Database#upgradeService}. + * See {@link databases.Database#upgradeService}. */ export type UpgradeServiceOptions = { /** * An object mapping configuration option names to values. * - * See also {@link Database#getServiceConfiguration}. + * See also {@link databases.Database#getServiceConfiguration}. */ configuration?: Record; /** * An object mapping dependency aliases to mount points. * - * See also {@link Database#getServiceDependencies}. + * See also {@link databases.Database#getServiceDependencies}. */ dependencies?: Record; /** * Whether the service should be installed in development mode. * - * See also {@link Database#setServiceDevelopmentMode}. + * See also {@link databases.Database#setServiceDevelopmentMode}. * * Default: `false` */ @@ -167,7 +168,7 @@ export type UpgradeServiceOptions = { /** * Options for uninstalling a service. * - * See {@link Database#uninstallService}. + * See {@link databases.Database#uninstallService}. */ export type UninstallServiceOptions = { /** diff --git a/src/views.ts b/src/views.ts index 9b7f5fa67..6826221d8 100644 --- a/src/views.ts +++ b/src/views.ts @@ -100,7 +100,10 @@ export type CreateViewOptions = | CreateArangoSearchViewOptions | CreateSearchAliasViewOptions; -type CreateViewOptionsType = { +/** + * Shared attributes of all View creation options. + */ +export type CreateViewOptionsType = { /** * Type of the View. */ @@ -596,7 +599,7 @@ export class View { * ``` */ create( - options: CreateViewOptions, + options: CreateViewOptions ): Promise< typeof options extends CreateArangoSearchViewOptions ? ArangoSearchViewDescription @@ -637,7 +640,7 @@ export class View { * ``` */ async rename( - newName: string, + newName: string ): Promise> { const result = this._db.renameView(this._name, newName); this._name = newName; @@ -677,7 +680,7 @@ export class View { * ``` */ updateProperties( - properties?: Properties, + properties?: Properties ): Promise< Properties extends UpdateArangoSearchViewPropertiesOptions ? ArangoSearchViewProperties @@ -708,7 +711,7 @@ export class View { * ``` */ replaceProperties( - properties?: Properties, + properties?: Properties ): Promise< Properties extends ArangoSearchViewPropertiesOptions ? ArangoSearchViewProperties @@ -741,7 +744,7 @@ export class View { method: "DELETE", pathname: `/_api/view/${encodeURIComponent(this._name)}`, }, - (res) => res.parsedBody.result, + (res) => res.parsedBody.result ); } } diff --git a/typedoc.json b/typedoc.json index d303ec223..35dc46d23 100644 --- a/typedoc.json +++ b/typedoc.json @@ -1,19 +1,18 @@ { - "out": "tsdoc", + "basePath": "./src", "cacheBust": true, - "githubPages": true, + "disableGit": true, "disableSources": false, + "entryPoints": ["src"], + "entryPointStrategy": "expand", "exclude": ["**/lib/*.ts", "**/test/*.ts"], - "basePath": "./src", - "gitRemote": "origin", - "visibilityFilters": {}, - "intentionallyNotExported": ["Blob", "GeneratedAqlQuery"], "excludeInternal": true, - "excludeProtected": true, "excludePrivate": true, - "includeVersion": true, - "entryPoints": ["src"], - "entryPointStrategy": "expand", + "excludeProtected": true, + "githubPages": true, + "includeVersion": false, + "out": "tsdoc", + "visibilityFilters": {}, "validation": { "notExported": true, "invalidLink": true, From e172e69e77e4d89c504b9eb51d486ec1dbcb99ee Mon Sep 17 00:00:00 2001 From: Alan Plum Date: Mon, 6 Jan 2025 18:59:06 +0100 Subject: [PATCH 13/25] Update CHANGELOG.md --- CHANGELOG.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index e2b877502..5e4b9e709 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -33,6 +33,13 @@ for upgrading your code to arangojs v10. `withStats` option is set to `true` but the `figures` property is already included in the current return type. +- Removed Node.js 18 support + + Node.js 18 will reach its end of life in May 2025, so arangojs will no + longer support this version of Node.js going forward. + + For more information, see [the Node.js release schedule](https://nodejs.dev/en/about/releases/). + ### Changed - Closing a connection now closes all open requests From 4bc22cc6d437f94876cad5873beb2336756b7266 Mon Sep 17 00:00:00 2001 From: Alan Plum Date: Mon, 6 Jan 2025 19:05:52 +0100 Subject: [PATCH 14/25] Fix typedoc warnings --- src/aql.ts | 6 ++---- src/queries.ts | 2 +- 2 files changed, 3 insertions(+), 5 deletions(-) diff --git a/src/aql.ts b/src/aql.ts index 5229ce3e4..35e3841c1 100644 --- a/src/aql.ts +++ b/src/aql.ts @@ -40,8 +40,6 @@ export interface AqlQuery { * Derived type representing AQL query objects generated by the AQL helper * functions and the AQL template string handler. These objects can be fed * back into these helper functions to be inlined or merged in complex queries. - * - * @internal */ export interface GeneratedAqlQuery extends AqlQuery { /** @@ -224,7 +222,7 @@ export function aql( 2, strings[i] + src.strings[0], ...src.strings.slice(1, src.args.length), - src.strings[src.args.length] + strings[i + 1], + src.strings[src.args.length] + strings[i + 1] ); } else { query += rawValue.query + strings[i + 1]; @@ -319,7 +317,7 @@ export function aql( * ``` */ export function literal( - value: string | number | boolean | AqlLiteral | null | undefined, + value: string | number | boolean | AqlLiteral | null | undefined ): AqlLiteral { if (isAqlLiteral(value)) { return value; diff --git a/src/queries.ts b/src/queries.ts index 470cd452a..78fd336dd 100644 --- a/src/queries.ts +++ b/src/queries.ts @@ -609,7 +609,7 @@ export type UserFunctionDescription = { /** * Whether the function is deterministic. * - * See {@link databases.Database#createFunction}. + * See {@link databases.Database#createUserFunction}. */ isDeterministic: boolean; }; From 5d0fca750cfda9e8366ce12c45556bb5414a672f Mon Sep 17 00:00:00 2001 From: Alan Plum Date: Mon, 6 Jan 2025 19:10:22 +0100 Subject: [PATCH 15/25] Tweak typedoc args --- .github/workflows/docs.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 6f0ea28d8..dc2eb4130 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -71,13 +71,13 @@ jobs: - name: Rebuild docs for tag if: env.VERSION != 'devel' run: | - ./node_modules/.bin/typedoc --includeVersion --out gh-pages/${VERSION} --sourceLinkTemplate "https://github.com/${{ github.repository }}/blob/${{ github.ref_name }}/src/{path}:{line}" + ./node_modules/.bin/typedoc --includeVersion --sourceLinkTemplate "https://github.com/${{ github.repository }}/blob/${{ github.ref_name }}/src/{path}:{line}" --out gh-pages/${VERSION} node -p 'var all=fs.readdirSync("gh-pages",{withFileTypes:true}).flatMap(f=>f.isDirectory()&&!isNaN(f.name.charAt(0))?[f.name]:[]).sort(require("semver").rcompare);JSON.stringify({all,stable:all.filter(s=>!s.includes("-"))})' > gh-pages/_data/versions.json - name: Rebuild docs for devel if: env.VERSION == 'devel' run: | - ./node_modules/.bin/typedoc --out gh-pages/${VERSION} --sourceLinkTemplate https://github.com/${{ github.repository }}/blob/${{ github.sha }}/src/{path}:{line} + ./node_modules/.bin/typedoc --sourceLinkTemplate "https://github.com/${{ github.repository }}/blob/${{ github.sha }}/src/{path}:{line}" --out gh-pages/${VERSION} - name: Commit to gh-pages uses: EndBug/add-and-commit@v9 From 363c384f10bd5ecc15f8daeeb09bd21a653a674d Mon Sep 17 00:00:00 2001 From: Alan Plum Date: Mon, 6 Jan 2025 19:16:24 +0100 Subject: [PATCH 16/25] Fix line link --- .github/workflows/docs.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index dc2eb4130..8abd1e5d2 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -71,13 +71,13 @@ jobs: - name: Rebuild docs for tag if: env.VERSION != 'devel' run: | - ./node_modules/.bin/typedoc --includeVersion --sourceLinkTemplate "https://github.com/${{ github.repository }}/blob/${{ github.ref_name }}/src/{path}:{line}" --out gh-pages/${VERSION} + ./node_modules/.bin/typedoc --includeVersion --sourceLinkTemplate "https://github.com/${{ github.repository }}/blob/${{ github.ref_name }}/src/{path}#L{line}" --out gh-pages/${VERSION} node -p 'var all=fs.readdirSync("gh-pages",{withFileTypes:true}).flatMap(f=>f.isDirectory()&&!isNaN(f.name.charAt(0))?[f.name]:[]).sort(require("semver").rcompare);JSON.stringify({all,stable:all.filter(s=>!s.includes("-"))})' > gh-pages/_data/versions.json - name: Rebuild docs for devel if: env.VERSION == 'devel' run: | - ./node_modules/.bin/typedoc --sourceLinkTemplate "https://github.com/${{ github.repository }}/blob/${{ github.sha }}/src/{path}:{line}" --out gh-pages/${VERSION} + ./node_modules/.bin/typedoc --sourceLinkTemplate "https://github.com/${{ github.repository }}/blob/${{ github.sha }}/src/{path}#L{line}" --out gh-pages/${VERSION} - name: Commit to gh-pages uses: EndBug/add-and-commit@v9 From 46d4bc4283f29c7e430beeca3f3088ef643d2360 Mon Sep 17 00:00:00 2001 From: Alan Plum Date: Mon, 6 Jan 2025 19:22:41 +0100 Subject: [PATCH 17/25] 10.0.0 --- CHANGELOG.md | 4 ++-- README.md | 10 +++++----- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 5e4b9e709..538ac5a65 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -14,7 +14,7 @@ This driver uses semantic versioning: - A change in the major version (e.g. 1.Y.Z -> 2.0.0) indicates _breaking_ changes that require changes in your code to upgrade. -## [Unreleased] +## [10.0.0] - 2025-01-06 This is a major release and breaks backwards compatibility. @@ -2452,7 +2452,7 @@ For a detailed list of changes between pre-release versions of v7 see the Graph methods now only return the relevant part of the response body. -[unreleased]: https://github.com/arangodb/arangojs/compare/v9.3.0...HEAD +[10.0.0]: https://github.com/arangodb/arangojs/compare/v9.3.0...v10.0.0 [9.3.0]: https://github.com/arangodb/arangojs/compare/v9.2.0...v9.3.0 [9.2.0]: https://github.com/arangodb/arangojs/compare/v9.1.0...v9.2.0 [9.1.0]: https://github.com/arangodb/arangojs/compare/v9.0.0...v9.1.0 diff --git a/README.md b/README.md index 2f72ea4fc..5b45f80fc 100644 --- a/README.md +++ b/README.md @@ -36,7 +36,7 @@ You can also use [jsDelivr CDN](https://www.jsdelivr.com) during development: @@ -183,7 +183,7 @@ For more details on the errors thrown by `undici`, see the Please make sure you are using the latest version of this driver and that the version of the arangojs documentation you are reading matches that version. -Changes in the major version number of arangojs (e.g. 8.x.y -> 9.0.0) indicate +Changes in the major version number of arangojs (e.g. 9.x.y -> 10.0.0) indicate backwards-incompatible changes in the arangojs API that may require changes in your code when upgrading your version of arangojs. @@ -194,10 +194,10 @@ the [compatibility section](#compatibility) for additional information. You can install an older version of arangojs using `npm` or `yarn`: ```sh -# for version 8.x.x -yarn add arangojs@8 +# for version 9.x.x +yarn add arangojs@9 # - or - -npm install --save arangojs@8 +npm install --save arangojs@9 ``` ### No code intelligence when using require instead of import From 8bd3aadd2b776664979bbf1f751e3fadecd3a9d2 Mon Sep 17 00:00:00 2001 From: Alan Plum Date: Mon, 6 Jan 2025 19:28:42 +0100 Subject: [PATCH 18/25] Tweak docs bash --- .github/workflows/docs.yml | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 8abd1e5d2..40331d488 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -42,8 +42,7 @@ jobs: - name: Set VERSION env from tag name if: startsWith(github.ref, 'refs/tags/v') run: | - export REF_NAME=${{github.ref_name}} - export VERSION=${REF_NAME:1} + REF_NAME="${{ github.ref_name }}"; export VERSION="${REF_NAME:1}" echo "VERSION=${VERSION}" >> $GITHUB_ENV echo "IS_PREVIEW=$(node -p "Number('${VERSION}'.includes('-'))")" >> $GITHUB_ENV echo "IS_BACKPORT=$(node -p "Number(require('semver').lt('${VERSION}','$(tail -n 1 gh-pages/VERSION.md)'))")" >> $GITHUB_ENV From 11195285ea4515b7870c308a11b2d2984181a009 Mon Sep 17 00:00:00 2001 From: Alan Plum Date: Mon, 6 Jan 2025 19:33:41 +0100 Subject: [PATCH 19/25] GitHub Actions don't use bash --- .github/workflows/docs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 40331d488..c4fb49867 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -42,7 +42,7 @@ jobs: - name: Set VERSION env from tag name if: startsWith(github.ref, 'refs/tags/v') run: | - REF_NAME="${{ github.ref_name }}"; export VERSION="${REF_NAME:1}" + export VERSION=$(cut -c2- <<< ${{ github.ref_name }}) echo "VERSION=${VERSION}" >> $GITHUB_ENV echo "IS_PREVIEW=$(node -p "Number('${VERSION}'.includes('-'))")" >> $GITHUB_ENV echo "IS_BACKPORT=$(node -p "Number(require('semver').lt('${VERSION}','$(tail -n 1 gh-pages/VERSION.md)'))")" >> $GITHUB_ENV From dec02932a7f2fddccb44b6b1471bbe6e697c6d1d Mon Sep 17 00:00:00 2001 From: Alan Plum Date: Mon, 6 Jan 2025 19:37:58 +0100 Subject: [PATCH 20/25] Fix unexpected redirection --- .github/workflows/docs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index c4fb49867..ab3de9910 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -42,7 +42,7 @@ jobs: - name: Set VERSION env from tag name if: startsWith(github.ref, 'refs/tags/v') run: | - export VERSION=$(cut -c2- <<< ${{ github.ref_name }}) + export VERSION=$(echo "${{ github.ref_name }}" | cut -c2-) echo "VERSION=${VERSION}" >> $GITHUB_ENV echo "IS_PREVIEW=$(node -p "Number('${VERSION}'.includes('-'))")" >> $GITHUB_ENV echo "IS_BACKPORT=$(node -p "Number(require('semver').lt('${VERSION}','$(tail -n 1 gh-pages/VERSION.md)'))")" >> $GITHUB_ENV From 5ccfe4c7e6b28618effddaa46c52ac1b18c43af6 Mon Sep 17 00:00:00 2001 From: Alan Plum Date: Fri, 10 Jan 2025 18:01:44 +0100 Subject: [PATCH 21/25] Add ignoreRevs to RemoveDocumentOptions Fixes DE-947. --- CHANGELOG.md | 9 +++++++++ src/documents.ts | 13 ++++++++++--- 2 files changed, 19 insertions(+), 3 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 538ac5a65..c65a27e15 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -14,6 +14,14 @@ This driver uses semantic versioning: - A change in the major version (e.g. 1.Y.Z -> 2.0.0) indicates _breaking_ changes that require changes in your code to upgrade. +## [Unreleased] + +### Added + +- Added `ignoreRevs` option to `RemoveDocumentOptions` type (DE-947) + + This affects the `collection.remove` and `collection.removeAll` methods. + ## [10.0.0] - 2025-01-06 This is a major release and breaks backwards compatibility. @@ -2452,6 +2460,7 @@ For a detailed list of changes between pre-release versions of v7 see the Graph methods now only return the relevant part of the response body. +[unreleased]: https://github.com/arangodb/arangojs/compare/v10.0.0...HEAD [10.0.0]: https://github.com/arangodb/arangojs/compare/v9.3.0...v10.0.0 [9.3.0]: https://github.com/arangodb/arangojs/compare/v9.2.0...v9.3.0 [9.2.0]: https://github.com/arangodb/arangojs/compare/v9.1.0...v9.2.0 diff --git a/src/documents.ts b/src/documents.ts index 4f396e8d3..db70af0f9 100644 --- a/src/documents.ts +++ b/src/documents.ts @@ -372,6 +372,13 @@ export type RemoveDocumentOptions = { * Default: `false` */ waitForSync?: boolean; + /** + * If set to `false`, the existing document will only be modified if its + * `_rev` property matches the same property on the new data. + * + * Default: `true` + */ + ignoreRevs?: boolean; /** * If set to `true`, the complete old document will be returned as the `old` * property on the result object. Has no effect if `silent` is set to `true`. @@ -573,7 +580,7 @@ export type ObjectWithDocumentKey = { export function _documentHandle( selector: DocumentSelector, collectionName: string, - strict: boolean = true, + strict: boolean = true ): string { if (typeof selector !== "string") { if (selector._id) { @@ -583,14 +590,14 @@ export function _documentHandle( return _documentHandle(selector._key, collectionName); } throw new Error( - "Document handle must be a string or an object with a _key or _id attribute", + "Document handle must be a string or an object with a _key or _id attribute" ); } if (selector.includes("/")) { const [head] = selector.split("/"); if (strict && head !== collectionName) { throw new Error( - `Document ID "${selector}" does not match collection name "${collectionName}"`, + `Document ID "${selector}" does not match collection name "${collectionName}"` ); } return selector; From 6ded453ba7b9314b6fdf3d9c4b7359d20354cd49 Mon Sep 17 00:00:00 2001 From: Alan Plum Date: Mon, 13 Jan 2025 10:43:23 +0100 Subject: [PATCH 22/25] 10.1.0 --- CHANGELOG.md | 4 ++-- package.json | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index c65a27e15..6de865743 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -14,7 +14,7 @@ This driver uses semantic versioning: - A change in the major version (e.g. 1.Y.Z -> 2.0.0) indicates _breaking_ changes that require changes in your code to upgrade. -## [Unreleased] +## [10.1.0] - 2025-01-13 ### Added @@ -2460,7 +2460,7 @@ For a detailed list of changes between pre-release versions of v7 see the Graph methods now only return the relevant part of the response body. -[unreleased]: https://github.com/arangodb/arangojs/compare/v10.0.0...HEAD +[10.1.0]: https://github.com/arangodb/arangojs/compare/v10.0.0...v10.1.0 [10.0.0]: https://github.com/arangodb/arangojs/compare/v9.3.0...v10.0.0 [9.3.0]: https://github.com/arangodb/arangojs/compare/v9.2.0...v9.3.0 [9.2.0]: https://github.com/arangodb/arangojs/compare/v9.1.0...v9.2.0 diff --git a/package.json b/package.json index edf567413..a222c5acc 100644 --- a/package.json +++ b/package.json @@ -2,7 +2,7 @@ "private": true, "type": "module", "name": "arangojs", - "version": "10.0.0", + "version": "10.1.0", "engines": { "node": ">=20" }, From b49d8222562a98efe28a9361c2b0ce90587147f8 Mon Sep 17 00:00:00 2001 From: Alan Plum Date: Mon, 13 Jan 2025 11:03:59 +0100 Subject: [PATCH 23/25] Remove File type Fixes #818. --- CHANGELOG.md | 9 +++++++++ src/databases.ts | 6 +++--- 2 files changed, 12 insertions(+), 3 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 6de865743..3b0192514 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -14,6 +14,14 @@ This driver uses semantic versioning: - A change in the major version (e.g. 1.Y.Z -> 2.0.0) indicates _breaking_ changes that require changes in your code to upgrade. +## [Unreleased] + +### Changed + +- Removed `File` from `source` option types in Foxx CRUD methods ([#818](https://github.com/arangodb/arangojs/issues/818)) + + The `source` option type already includes `Blob`, which `File` extends. + ## [10.1.0] - 2025-01-13 ### Added @@ -2460,6 +2468,7 @@ For a detailed list of changes between pre-release versions of v7 see the Graph methods now only return the relevant part of the response body. +[unreleased]: https://github.com/arangodb/arangojs/compare/v10.1.0...HEAD [10.1.0]: https://github.com/arangodb/arangojs/compare/v10.0.0...v10.1.0 [10.0.0]: https://github.com/arangodb/arangojs/compare/v9.3.0...v10.0.0 [9.3.0]: https://github.com/arangodb/arangojs/compare/v9.2.0...v9.3.0 diff --git a/src/databases.ts b/src/databases.ts index 52d72333c..4ed4e2d9f 100644 --- a/src/databases.ts +++ b/src/databases.ts @@ -3409,7 +3409,7 @@ export class Database { */ async installService( mount: string, - source: File | Blob | string, + source: Blob | string, options: services.InstallServiceOptions = {} ): Promise { const { configuration, dependencies, ...search } = options; @@ -3467,7 +3467,7 @@ export class Database { */ async replaceService( mount: string, - source: File | Blob | string, + source: Blob | string, options: services.ReplaceServiceOptions = {} ): Promise { const { configuration, dependencies, ...search } = options; @@ -3525,7 +3525,7 @@ export class Database { */ async upgradeService( mount: string, - source: File | Blob | string, + source: Blob | string, options: services.UpgradeServiceOptions = {} ): Promise { const { configuration, dependencies, ...search } = options; From c13259a05ee55554136b905db3375d223cbbd365 Mon Sep 17 00:00:00 2001 From: Alan Plum Date: Mon, 13 Jan 2025 11:05:23 +0100 Subject: [PATCH 24/25] 10.1.1 --- CHANGELOG.md | 4 ++-- package.json | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 3b0192514..2eebaf86d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -14,7 +14,7 @@ This driver uses semantic versioning: - A change in the major version (e.g. 1.Y.Z -> 2.0.0) indicates _breaking_ changes that require changes in your code to upgrade. -## [Unreleased] +## [10.1.1] - 2025-01-13 ### Changed @@ -2468,7 +2468,7 @@ For a detailed list of changes between pre-release versions of v7 see the Graph methods now only return the relevant part of the response body. -[unreleased]: https://github.com/arangodb/arangojs/compare/v10.1.0...HEAD +[10.1.1]: https://github.com/arangodb/arangojs/compare/v10.1.0...v10.1.1 [10.1.0]: https://github.com/arangodb/arangojs/compare/v10.0.0...v10.1.0 [10.0.0]: https://github.com/arangodb/arangojs/compare/v9.3.0...v10.0.0 [9.3.0]: https://github.com/arangodb/arangojs/compare/v9.2.0...v9.3.0 diff --git a/package.json b/package.json index a222c5acc..2b5579500 100644 --- a/package.json +++ b/package.json @@ -2,7 +2,7 @@ "private": true, "type": "module", "name": "arangojs", - "version": "10.1.0", + "version": "10.1.1", "engines": { "node": ">=20" }, From 7bfca376b746284fbbd5eb3f77a3ac2bbc7e95e7 Mon Sep 17 00:00:00 2001 From: "adria (cmyk47)" Date: Thu, 27 Mar 2025 14:55:00 +0100 Subject: [PATCH 25/25] Update MIGRATING.md (#823) * chore: add v6 to v7 migration steps * fix: typo in route example --- MIGRATING.md | 353 ++++++++++++++++++++++++++++++++++++++++++++++++++ src/routes.ts | 2 +- 2 files changed, 354 insertions(+), 1 deletion(-) diff --git a/MIGRATING.md b/MIGRATING.md index f9df2657b..3637d97d5 100644 --- a/MIGRATING.md +++ b/MIGRATING.md @@ -618,3 +618,356 @@ using the `db.collections` and `collection.truncate` methods: + db.collections().map((collection) => collection.truncate()) +); ``` + + +## v6 to v7 + +### Configuration changes + +The `db.useDatabase` method has been deprecated in v7. + +Previously the primary use of this method was to set the database name of the +arangojs instance. The database name can now be specified using the +`databaseName` option in the arangojs configuration: + +```diff + const db = new Database({ + url: "http://localhost:8529", ++ databaseName: "my_database", + }); +-db.useDatabase("my_database"); +``` + +### Shared connection pool + +It is now possible to have multiple `Database` objects using the same +underlying connection pool: + +```diff +-const db1 = new Database(); +-db1.useDatabase("database1"); +-const db2 = new Database(); +-db2.useDatabase("database2"); ++const db1 = new Database({ databaseName: "database1" }); ++const db2 = db1.database("database2"); +``` + +### Indexes + +The helper methods for creating specific index types, e.g. `createHashIndex`, +have been removed and replaced with the generic `ensureIndex` method (which +was previously called `createIndex`): + +```diff +-await collection.createGeoIndex(["lat", "lng"]); ++await collection.createIndex({ type: "geo", fields: ["lat", "lng"] }); +``` + +### Document and edge collections + +Version 7 no longer provides different methods for accessing document and edge +collections as both types are now implemented using the same underlying class: + +```diff + const myDocumentCollection = db.collection("documents"); +-const myEdgeCollection = db.edgeCollection("edges"); ++const myEdgeCollection = db.collection("edges"); +``` + +When using TypeScript the collection instances can still be cast to the more +specific `DocumentCollection` and `EdgeCollection` interfaces: + +```ts +interface EdgeType { + color: string; +} +const myEdgeCollection = db.collection("edges") as EdgeCollection; +``` + +### Saving edge documents + +The `save` method no longer supports positional arguments for `_from` and `_to` +values. These now need to be supplied as part of the document data: + +```diff + await edges.save( +- "vertices/start", +- "vertices/end", +- { color: "red" } ++ { _from: "vertices/start", _to: "vertices/end", color: "red" } + ); +``` + +### Accessing documents + +The `edge` method has been removed from the low-level collection API as it was +an alias for the `document` method, which still exists: + +```diff +-const edges = db.edgeCollection("edges"); ++const edges = db.collection("edges"); + +-const edge = await edges.edge("my-edge"); ++const edge = await edges.document("my-edge"); +``` + +Graph vertex and edge collections instead only retain their specific `vertex` +and `edge` methods which access the collection using the high-level graph API: + +```diff + const vertices = graph.vertexCollection("vertices"); +-const vertex = await vertices.document("my-vertex"); ++const vertex = await vertices.vertex("my-vertex"); + + const edges = graph.edgeCollection("edges"); +-const edge = await edges.document("my-edge"); ++const edge = await edges.edge("my-edge"); +``` + +### Graph collections + +Graph vertex and edge collections no longer implement the generic collection +API methods to avoid confusion between operations that are aware of the graph +definition (and can trigger graph-related side-effects) and those that directly +access low-level operations. + +As a convenience both graph collection types still provide access to the +low-level collection interface via the `collection` property: + +```diff + const graphEdges = graph.edgeCollection("edges"); +-const outEdges = graphEdges.outEdges("vertices/start"); ++const outEdges = graphEdges.collection.outEdges("vertices/start"); +``` + +### Cursor methods + +The method `each` is now called `forEach`. The method `hasNext` has been +replaced with a getter. + +The methods `some` and `every` have been removed. These methods previously +allowed iterating over cursor results in order to derive a boolean value by +applying a callback function to each value in the result. + +In most cases these methods can be avoided by writing a more efficient AQL +query: + +```diff +-const cursor = await db.query(aql` +- FOR bowl IN porridges +- RETURN bowl +-`); +-const someJustRight = await cursor.some( +- (bowl) => bowl.temperature < TOO_HOT && bowl.temperature > TOO_COLD +-); ++const cursor = await db.query(aql` ++ FOR bowl IN porridges ++ FILTER bowl.temperature < ${TOO_HOT} ++ FILTER bowl.temperature > ${TOO_COLD} ++ LIMIT 1 ++ RETURN 1 ++`); ++const someJustRight = Boolean(await cursor.next()); +``` + +If this is not an option, the old behavior can be emulated using the `forEach` +method (previously called `each`) instead: + +```diff +-const someJustRight = await cursor.some( +- (bowl) => bowl.temperature < TOO_HOT && bowl.temperature > TOO_COLD +-); ++const someJustRight = !(await cursor.forEach( ++ (bowl) => bowl.temperature === TOO_HOT || bowl.temperature === TOO_COLD ++)); +``` + +### Batch cursor API + +Cursors now provide a low-level API for iterating over the result batches +instead of individual items, which is exposed via the `batches` property. + +The methods `hasMore` and `nextBatch` have been replaced with the getter +`batches.hasMore` and the method `batches.next`: + +```diff +-if (cursor.hasMore()) { +- return await cursor.nextBatch(); ++if (cursor.batches.hasMore) { ++ return await cursor.batches.next(); + } +``` + +### Simple queries + +Collection methods for using simple queries (e.g. `all`, `any` and `list`) +have been deprecated in ArangoDB 3.0 and are now also deprecated in arangojs. + +See the documentation of each method for an example for how to perform the same +query using an AQL query instead. + +Additionally the `list` method now returns a cursor instead of an array. + +### ArangoSearch Views + +The database methods `arangoSearchView` and `createArangoSearchView` have been +renamed to `view` and `createView` respectively as there currently is no other +view type available in ArangoDB: + +```diff +-await db.createArangoSearchView("my-view"); +-const view = db.arangoSearchView("my-view"); ++await db.createView("my-view"); ++const view = db.view("my-view"); +``` + +### Query options + +The `options` argument of `db.query` has been flattened. Options that were +previously nested in an `options` property of that argument are now specified +directly on the argument itself: + +```diff + const cursor = await db.query( + aql` + FOR doc IN ${collection} + RETURN doc + `, + { + cache: false, +- options: { fullCount: true }, ++ fullCount: true, + } + ); +``` + +### Bulk imports + +The default value of the `type` option now depends on the input type instead +of always defaulting to `"auto"`. If you previously relied on the default +value being set to `"auto"`, you may now need to explicitly set this option: + +```diff +-await collection.import(data); ++await collection.import(data, { type: "auto" }); +``` + +### Bulk operations + +The collection method `bulkUpdate` has been removed and the methods +`save`, `update`, `replace` and `remove` no longer accept arrays as input. + +Bulk operations can now be performed using the dedicated methods +`saveAll`, `updateAll`, `replaceAll` and `removeAll`: + +```diff +-await collection.save([{ _key: "a" }, { _key: "b" }]); ++await collection.saveAll([{ _key: "a" }, { _key: "b" }]); +``` + +### Cross-collection operations + +Collection methods no longer accept document IDs from other collections. +Previously passing a document ID referring to a different collection would +result in the collection performing a request to that collection instead. Now +mismatching IDs will result in an error instead: + +```js +const collection1 = db.collection("collection1"); +const doc = await collection1.document("collection2/xyz"); // ERROR +``` + +### Creating graphs + +The signatures of `db.createGraph` and `graph.create` have changed to always +take an array of edge definitions as the first argument instead of taking the +edge definitions as a property of the `properties` argument. + +Additionally the `properties` and `options` arguments have been merged: + +```diff + await graph.create( ++ [{ collection: "edges", from: ["a"], to: ["b"] }], + { +- edgeDefinitions: [{ collection: "edges", from: ["a"], to: ["b"] }], + isSmart: true, +- }, +- { + waitForSync: true, + } + ); +``` + +### Transactions + +The transaction method `run` has been renamed to `step` to make it more obvious +that it is intended to only perform a single "step" of the transaction. + +See the method's documentation for examples of how to use the method correctly. + +Additionally the method `transaction` no longer acts as an alias for +`executeTransaction`: + +```diff +-const result = await db.transaction(collections, action); ++const result = await db.executeTransaction(collections, action); +``` + +### Service development mode + +The methods `enableServiceDevelopmentMode` and `disableServiceDevelopmentMode` +have been replaced with the method `setServiceDevelopmentMode`: + +```diff +-await db.enableServiceDevelopmentMode("/my-foxx"); ++await db.setServiceDevelopmentMode("/my-foxx", true); +``` + +### System services + +The default value of the method `listServices` option `excludeSystem` has been +changed from `false` to `true`: + +```diff +-const services = await db.listServices(true); ++const services = await db.listServices(); +``` + +### Query tracking + +The method `setQueryTracking` has been merged into `queryTracking`: + +```diff +-await db.setQueryTracking({ enabled: true }); ++await db.queryTracking({ enabled: true }); +``` + +### Collection properties + +The method `setProperties` has been merged into `properties`: + +```diff +-await collection.setProperties({ waitForSync: true }); ++await collection.properties({ waitForSync: true }); +``` + +### View properties + +The View method `setProperties` has been renamed to `updateProperties`: + +```diff +-await view.setProperties({ consolidationIntervalMsec: 234 }); ++await view.updateProperties({ consolidationIntervalMsec: 234 }); +``` + +### Truncating collections + +The `db.truncate` method has been removed. The behavior can still be mimicked +using the `db.collections` and `collection.truncate` methods: + +```diff +-await db.truncate(); ++await Promise.all( ++ db.collections().map((collection) => collection.truncate()) ++); +``` \ No newline at end of file diff --git a/src/routes.ts b/src/routes.ts index c63f62c47..d7e77fd27 100644 --- a/src/routes.ts +++ b/src/routes.ts @@ -142,7 +142,7 @@ export class Route { * ```js * const db = new Database(); * const foxx = db.route("/my-foxx-service"); - * const user = foxx.roue("/users/admin"); + * const user = foxx.route("/users/admin"); * const res = await user.delete(); * ``` */