/** * GitDocumentDB * Copyright (c) Hidekazu Kubota * * This source code is licensed under the Mozilla Public License Version 2.0 * found in the LICENSE file in the root directory of this source tree. */ import { CollectionOptions, CollectionPath, DeleteOptions, DeleteResult, DeleteResultJsonDoc, Doc, DocType, FatDoc, FindOptions, GetOptions, HistoryOptions, JsonDoc, PutOptions, PutResult, PutResultJsonDoc, SyncCallback, SyncEvent } from './types'; import { GitDDBInterface } from './types_gitddb'; import { SyncInterface } from './types_sync'; import { ICollection } from './types_collection'; /** * Documents under a collectionPath are gathered together in a collection. * * @remarks * In a collection API, shortId (shortName) is used instead of _id (name). * * - shortId is a file path whose collectionPath and extension are omitted. (_id = collectionPath + shortId) * * - shortName is a file path whose collectionPath is omitted. (name = collectionPath + shortName) * * @example * ``` * const gitDDB = new GitDocumentDB({ db_name: 'db01' }); * * // Both put git_documentdb/db01/Nara/flower.json: { _id: 'Nara/flower', name: 'cherry blossoms' }. * gitDDB.put({ _id: 'Nara/flower', name: 'cherry blossoms' }); * gitDDB.collection('Nara').put({ _id: 'flower', name: 'cherry blossoms' }) * * // Notice that APIs return different _id values despite the same source file. * gitDDB.get({ _id: 'Nara/flower' }); // returns { _id: 'Nara/flower', name: 'cherry blossoms' }. * gitDDB.collection('Nara').get({ _id: 'flower' }); // returns { _id: 'flower', name: 'cherry blossoms' }. * ``` * @public */ export declare class Collection implements ICollection { private _gitDDB; private _monoID; /*********************************************** * Public properties (readonly) ***********************************************/ private _options; /** * Get a clone of collection options * * @readonly * @public */ get options(): CollectionOptions; private _collectionPath; /** * Normalized path of a collection * * @remarks * collectionPath is '' or path strings that have a trailing slash and no heading slash. '/' is not allowed. Backslash \\ or yen ¥ is replaced with slash /. * @public */ get collectionPath(): string; private _parent; /** * Parent collection * * @remarks * Child collection inherits Parent's CollectionOptions. * * @public */ get parent(): ICollection | undefined; /** * Constructor * * @param collectionPathFromParent - A relative collectionPath from a parent collection. * @param parent - A parent collection of this collection. * * @throws {@link Err.InvalidCollectionPathCharacterError} * @throws {@link Err.InvalidCollectionPathLengthError} * * @public */ constructor(gitDDB: GitDDBInterface, collectionPathFromParent?: CollectionPath, parent?: ICollection, options?: CollectionOptions); /*********************************************** * Public methods ***********************************************/ /** * Generate new _id as monotonic ULID * * @remarks * See https://github.com/ulid/javascript * * @returns 26 Base32 alphabets * * @public */ generateId(seedTime?: number): string; /** * Get a collection * * @param collectionPath - relative path from this.collectionPath. Sub-directories are also permitted. e.g. 'pages', 'pages/works'. * * @remarks * - Notice that this function just read an existing directory. It does not make a new sub-directory. * * @returns A child collection of this collection * * @public */ collection(collectionPath: CollectionPath, options?: CollectionOptions): ICollection; /** * Get collections directly under the specified dirPath. * * @param dirPath - dirPath is a relative path from collectionPath. Default is ''. * @returns Array of Collections which does not include ''. * * @public */ getCollections(dirPath?: string): Promise; /*********************************************** * Public method (Implementation of CRUDInterface) ***********************************************/ /** * Insert a JSON document if not exists. Otherwise, update it. * * @param jsonDoc - JsonDoc whose _id is shortId. shortId is a file path whose collectionPath and extension are omitted. * * @remarks * - The saved file path is `${GitDocumentDB#workingDir}/${Collection#collectionPath}${jsonDoc._id}${extension}`. * * - If _id is undefined, it is automatically generated. * * @throws {@link Err.InvalidJsonObjectError} * * @privateRemarks # Errors from putImpl * @throws {@link Err.DatabaseClosingError} * @throws {@link Err.TaskCancelError} * * @throws # Errors from validateDocument, validateId * @throws - {@link Err.InvalidIdCharacterError} * @throws - {@link Err.InvalidIdLengthError} * * @throws # Errors from putWorker * @throws - {@link Err.UndefinedDBError} * @throws - {@link Err.CannotCreateDirectoryError} * @throws - {@link Err.CannotWriteDataError} * * @public */ put(jsonDoc: JsonDoc, options?: PutOptions): Promise; /** * Insert a JSON document if not exists. Otherwise, update it. * * @param shortId - shortId is a file path whose collectionPath and extension are omitted. * * @remarks * - The saved file path is `${GitDocumentDB#workingDir}/${Collection#collectionPath}/${shortId}${extension}`. * * - If shortId is undefined, it is automatically generated. * * - _id property of a JsonDoc is automatically set or overwritten by a shortId parameter. * * - An update operation is not skipped even if no change occurred on a specified document. * * @throws {@link Err.InvalidJsonObjectError} * * @privateRemarks # Errors from putImpl * @throws {@link Err.DatabaseClosingError} * @throws {@link Err.TaskCancelError} * * @throws # Errors from validateDocument, validateId * @throws - {@link Err.InvalidIdCharacterError} * @throws - {@link Err.InvalidIdLengthError} * * @throws # Errors from putWorker * @throws - {@link Err.UndefinedDBError} * @throws - {@link Err.CannotCreateDirectoryError} * @throws - {@link Err.CannotWriteDataError} * * @public */ put(shortId: string | undefined | null, jsonDoc: JsonDoc, options?: PutOptions): Promise; /** * Overload only for internal call * * @internal */ put(shortIdOrDoc: string | undefined | null | JsonDoc, jsonDocOrOptions?: JsonDoc | PutOptions, options?: PutOptions): Promise; /** * Insert a JSON document * * @param jsonDoc - JsonDoc whose _id is shortId. shortId is a file path whose collectionPath and extension are omitted. * * @remarks * - Throws SameIdExistsError when a document that has the same _id exists. It might be better to use put() instead of insert(). * * - If _id is undefined, it is automatically generated. * * - The saved file path is `${GitDocumentDB#workingDir}/${Collection#collectionPath}/${jsonDoc._id}${extension}`. * * @param jsonDoc - See {@link JsonDoc} for restriction. * * @param jsonDoc - See {@link JsonDoc} for restriction. * * @throws {@link Err.InvalidJsonObjectError} * * @privateRemarks # Errors from putImpl * @throws {@link Err.DatabaseClosingError} * @throws {@link Err.TaskCancelError} * * @throws # Errors from validateDocument, validateId * @throws - {@link Err.InvalidIdCharacterError} * @throws - {@link Err.InvalidIdLengthError} * * @throws # Errors from putWorker * @throws - {@link Err.UndefinedDBError} * @throws - {@link Err.CannotCreateDirectoryError} * @throws - {@link Err.CannotWriteDataError} * * @throws - {@link Err.SameIdExistsError} * * @public */ insert(jsonDoc: JsonDoc, options?: PutOptions): Promise; /** * Insert a JSON document * * @param shortId - shortId is a file path whose collectionPath and extension are omitted. * * @remarks * - Throws SameIdExistsError when a document that has the same _id exists. It might be better to use put() instead of insert(). * * - The saved file path is `${GitDocumentDB#workingDir}/${Collection#collectionPath}/${shortId}${extension}`. * * - If shortId is undefined, it is automatically generated. * * - _id property of a JsonDoc is automatically set or overwritten by shortId parameter. * * @throws {@link Err.InvalidJsonObjectError} * * @privateRemarks # Errors from putImpl * @throws {@link Err.DatabaseClosingError} * @throws {@link Err.TaskCancelError} * * @throws # Errors from validateDocument, validateId * @throws - {@link Err.InvalidIdCharacterError} * @throws - {@link Err.InvalidIdLengthError} * * @throws # Errors from putWorker * @throws - {@link Err.UndefinedDBError} * @throws - {@link Err.CannotCreateDirectoryError} * @throws - {@link Err.CannotWriteDataError} * * @throws - {@link Err.SameIdExistsError} * * @public */ insert(shortId: string | undefined | null, jsonDoc: JsonDoc, options?: PutOptions): Promise; /** * @internal */ insert(shortIdOrDoc: string | undefined | null | JsonDoc, jsonDocOrOptions?: JsonDoc | PutOptions, options?: PutOptions): Promise; /** * Update a JSON document * * @param jsonDoc - JsonDoc whose _id is shortId. shortId is a file path whose collectionPath and extension are omitted. * * @remarks * - Throws DocumentNotFoundError if a specified document does not exist. It might be better to use put() instead of update(). * * - The saved file path is `${GitDocumentDB#workingDir}/${Collection#collectionPath}/${jsonDoc._id}${extension}`. * * - If _id is undefined, it is automatically generated. * * - An update operation is not skipped even if no change occurred on a specified document. * * @throws {@link Err.InvalidJsonObjectError} * * @privateRemarks # Errors from putImpl * @throws {@link Err.DatabaseClosingError} * @throws {@link Err.TaskCancelError} * * @throws # Errors from validateDocument, validateId * @throws - {@link Err.InvalidIdCharacterError} * @throws - {@link Err.InvalidIdLengthError} * * @throws # Errors from putWorker * @throws - {@link Err.UndefinedDBError} * @throws - {@link Err.CannotCreateDirectoryError} * @throws - {@link Err.CannotWriteDataError} * * @throws - {@link Err.DocumentNotFoundError} * * @public */ update(jsonDoc: JsonDoc, options?: PutOptions): Promise; /** * Update a JSON document * * @param shortId - shortId is a file path whose collectionPath and extension are omitted. * * @remarks * - Throws DocumentNotFoundError if a specified data does not exist. It might be better to use put() instead of update(). * * - The saved file path is `${GitDocumentDB#workingDir}/${Collection#collectionPath}/${shortId}${extension}`. * * - An update operation is not skipped even if no change occurred on a specified data. * * @throws {@link Err.InvalidJsonObjectError} * * @privateRemarks # Errors from putImpl * @throws {@link Err.DatabaseClosingError} * @throws {@link Err.TaskCancelError} * * @throws # Errors from validateDocument, validateId * @throws - {@link Err.InvalidIdCharacterError} * @throws - {@link Err.InvalidIdLengthError} * * @throws # Errors from putWorker * @throws - {@link Err.UndefinedDBError} * @throws - {@link Err.CannotCreateDirectoryError} * @throws - {@link Err.CannotWriteDataError} * * @throws - {@link Err.DocumentNotFoundError} * * @public */ update(_id: string | undefined | null, jsonDoc: JsonDoc, options?: PutOptions): Promise; /** * @internal */ update(shortIdOrDoc: string | undefined | null | JsonDoc, jsonDocOrOptions?: JsonDoc | PutOptions, options?: PutOptions): Promise; /** * Insert data if not exists. Otherwise, update it. * * @param shortName - shortName is a file path whose collectionPath is omitted. shortName of JsonDoc must ends with extension. * * @remarks * - The saved file path is `${GitDocumentDB#workingDir}/${Collection#collectionPath}/${shortName}${extension}`. * * - If shortName is undefined, it is automatically generated. * * - _id property of a JsonDoc is automatically set or overwritten by shortName parameter whose extension is omitted. * * - An update operation is not skipped even if no change occurred on a specified data. * * @throws {@link Err.InvalidJsonFileExtensionError} * @throws {@link Err.InvalidJsonObjectError} * * @privateRemarks # Errors from putImpl * @throws {@link Err.DatabaseClosingError} * @throws {@link Err.TaskCancelError} * * @throws # Errors from validateDocument, validateId * @throws - {@link Err.InvalidIdCharacterError} * @throws - {@link Err.InvalidIdLengthError} * * @throws # Errors from putWorker * @throws - {@link Err.UndefinedDBError} * @throws - {@link Err.CannotCreateDirectoryError} * @throws - {@link Err.CannotWriteDataError} * * @public */ putFatDoc(shortName: string | undefined | null, doc: JsonDoc | Uint8Array | string, options?: PutOptions): Promise; /** * Insert a data * * @param shortName - shortName is a file path whose collectionPath is omitted. shortName of JsonDoc must ends with extension. * * @remarks * - Throws SameIdExistsError when data that has the same _id exists. It might be better to use put() instead of insert(). * * - The saved file path is `${GitDocumentDB#workingDir}/${Collection#collectionPath}/${shortName}${extension}`. * * - If shortName is undefined, it is automatically generated. * * - _id property of a JsonDoc is automatically set or overwritten by shortName parameter whose extension is omitted. * * @throws {@link Err.InvalidJsonObjectError} * * @privateRemarks # Errors from putImpl * @throws {@link Err.DatabaseClosingError} * @throws {@link Err.TaskCancelError} * * @throws # Errors from validateDocument, validateId * @throws - {@link Err.InvalidIdCharacterError} * @throws - {@link Err.InvalidIdLengthError} * * @throws # Errors from putWorker * @throws - {@link Err.UndefinedDBError} * @throws - {@link Err.CannotCreateDirectoryError} * @throws - {@link Err.CannotWriteDataError} * * @throws - {@link Err.SameIdExistsError} * * @public */ insertFatDoc(shortName: string | undefined | null, doc: JsonDoc | string | Uint8Array, options?: PutOptions): Promise; /** * Update a data * * @param shortName - shortName is a file path whose collectionPath is omitted. shortName of JsonDoc must ends with extension. * * @remarks * - Throws DocumentNotFoundError if a specified data does not exist. It might be better to use put() instead of update(). * * - The saved file path is `${GitDocumentDB#workingDir}/${Collection#collectionPath}/${shortName}${extension}`. * * - _id property of a JsonDoc is automatically set or overwritten by shortName parameter whose extension is omitted. * * - An update operation is not skipped even if no change occurred on a specified data. * * @throws {@link Err.InvalidJsonObjectError} * * @privateRemarks # Errors from putImpl * @throws {@link Err.DatabaseClosingError} * @throws {@link Err.TaskCancelError} * * @throws # Errors from validateDocument, validateId * @throws - {@link Err.InvalidIdCharacterError} * @throws - {@link Err.InvalidIdLengthError} * * @throws # Errors from putWorker * @throws - {@link Err.UndefinedDBError} * @throws - {@link Err.CannotCreateDirectoryError} * @throws - {@link Err.CannotWriteDataError} * * @throws - {@link Err.DocumentNotFoundError} * * @public */ updateFatDoc(shortName: string | undefined | null, doc: JsonDoc | string | Uint8Array, options?: PutOptions): Promise; /** * Get a JSON document * * @param shortId - shortId is a file path whose collectionPath and extension are omitted. * * @returns * - undefined if a specified document does not exist. * * - JsonDoc may not have _id property when an app other than GitDocumentDB creates it. * * @throws {@link Err.DatabaseClosingError} * @throws {@link Err.InvalidJsonObjectError} * * @public */ get(_id: string): Promise; /** * Get a FatDoc data * * @param shortName - shortName is a file path whose collectionPath is omitted. * * @returns * - undefined if a specified data does not exist. * * - FatJsonDoc if the file extension is SerializeFormat.extension. Be careful that JsonDoc may not have _id property when an app other than GitDocumentDB creates it. * * - FatBinaryDoc if described in .gitattribtues, otherwise FatTextDoc. * * - getOptions.forceDocType always overwrite return type. * * @throws {@link Err.DatabaseClosingError} * @throws {@link Err.InvalidJsonObjectError} * * @public */ getFatDoc(shortName: string, getOptions?: GetOptions): Promise; /** * Get a Doc which has specified oid * * @param fileOid - Object ID (SHA-1 hash) that represents a Git object. (See https://git-scm.com/docs/git-hash-object ) * * @remarks * - undefined if a specified oid does not exist. * * @throws {@link Err.DatabaseClosingError} * @throws {@link Err.InvalidJsonObjectError} * * @public */ getDocByOid(fileOid: string, docType?: DocType): Promise; /** * Get an old revision of a JSON document * * @param shortId - shortId is a file path whose collectionPath and extension are omitted. * @param revision - Specify a number to go back to old revision. Default is 0. * See {@link git-documentdb#Collection.getHistory} for the array of revisions. * @param historyOptions - The array of revisions is filtered by HistoryOptions.filter. * * @remarks * - undefined if a specified document does not exist or it is deleted. * * - If serializeFormat is front-matter, this function can't correctly distinguish files that has the same _id but different extension. Use getFatDocOldRevision() instead. e.g.) foo.md and foo.yml * * @example * ``` * collection.getOldRevision(_shortId, 0); // returns the latest document. * collection.getOldRevision(_shortId, 2); // returns a document two revisions older than the latest. * ``` * * @throws {@link Err.DatabaseClosingError} * @throws {@link Err.InvalidJsonObjectError} * * @public */ getOldRevision(shortId: string, revision: number, historyOptions?: HistoryOptions): Promise; /** * Get an old revision of a FatDoc data * * @param shortName - shortName is a file path whose collectionPath is omitted. * @param revision - Specify a number to go back to old revision. Default is 0. * See {@link git-documentdb#Collection.getHistory} for the array of revisions. * @param historyOptions - The array of revisions is filtered by HistoryOptions.filter. * * @remarks * - undefined if a specified data does not exist or it is deleted. * * - JsonDoc if the file extension is SerializedFormat.extension. Be careful that JsonDoc may not have _id property when an app other than GitDocumentDB creates it. * * - FatBinaryDoc if described in .gitattribtues, otherwise FatTextDoc. * * - getOptions.forceDocType always overwrite return type. * * @example * ``` * collection.getFatDocOldRevision(shortName, 0); // returns the latest FatDoc. * collection.getFatDocOldRevision(shortName, 2); // returns a FatDoc two revisions older than the latest. * ``` * * @throws {@link Err.DatabaseClosingError} * @throws {@link Err.InvalidJsonObjectError} * * @public */ getFatDocOldRevision(shortName: string, revision: number, historyOptions?: HistoryOptions, getOptions?: GetOptions): Promise; /** * Get revision history of a JSON document * * @remarks * - By default, revisions are sorted by reverse chronological order. However, keep in mind that Git dates may not be consistent across repositories. * * - If serializeFormat is front-matter, this function can't work for .yml files. Use getFatDocHistory() instead. e.g.) foo.yml * * @param shortId - shortId is a file path whose collectionPath and extension is omitted. * @param historyOptions - The array of revisions is filtered by HistoryOptions.filter. * * @returns Array of JsonDoc or undefined if a specified document does not exist or it is deleted. * * @example * ``` * Commit-01 to 08 were committed in order. file_v1 and file_v2 are two revisions of a file. * * - Commit-08: Not exists * - Commit-07: deleted * - Commit-06: file_v2 * - Commit-05: deleted * - Commit-04: file_v2 * - Commit-03: file_v1 * - Commit-02: file_v1 * - Commit-01: Not exists * * Commit-02 newly inserted a file (file_v1). * Commit-03 did not change about the file. * Commit-04 updated the file from file_v1 to file_v2. * Commit-05 deleted the file. * Commit-06 inserted the deleted file (file_v2) again. * Commit-07 deleted the file again. * Commit-08 did not change about the file. * * Here, getHistory() will return [undefined, file_v2, undefined, file_v2, file_v1] as a history. * * NOTE: * - Consecutive same values (commit-02 and commit-03) are combined into one. * - getHistory() ignores commit-01 because it was committed before the first insert. * Thus, a history is not [undefined, undefined, file_v2, undefined, file_v2, file_v1, file_v1, undefined]. * ``` * * @throws {@link Err.DatabaseClosingError} * @throws {@link Err.InvalidJsonObjectError} * * @public */ getHistory(_id: string, historyOptions?: HistoryOptions): Promise<(JsonDoc | undefined)[]>; /** * Get revision history of a FatDoc data * * @param shortName - shortName is a file path whose collectionPath is omitted. * * @remarks * See {@link git-documentdb#GitDocumentDB.getHistory} for detailed examples. * * @returns Array of FatDoc or undefined. * - undefined if a specified data does not exist or it is deleted. * * - Array of FatJsonDoc if isJsonDocCollection is true or the file extension is SerializeFormat.extension. Be careful that JsonDoc may not have _id property when an app other than GitDocumentDB creates it. * * - Array of FatBinaryDoc if described in .gitattribtues, otherwise array of FatTextDoc. * * - getOptions.forceDocType always overwrite return type. * * @throws {@link Err.DatabaseClosingError} * @throws {@link Err.InvalidJsonObjectError} * * @public */ getFatDocHistory(shortName: string, historyOptions?: HistoryOptions, getOptions?: GetOptions): Promise<(FatDoc | undefined)[]>; /** * Delete a JSON document * * @param shortId - shortId is a file path whose collectionPath and extension is omitted. * * @throws {@link Err.UndefinedDocumentIdError} * * @privateRemarks # Errors from deleteImpl * @throws {@link Err.DatabaseClosingError} * @throws {@link Err.TaskCancelError} * * @throws # Errors from deleteWorker * @throws - {@link Err.UndefinedDBError} * @throws - {@link Err.DocumentNotFoundError} * @throws - {@link Err.CannotDeleteDataError} * * @public */ delete(_id: string, options?: DeleteOptions): Promise; /** * Delete a document by _id property in JsonDoc * * @param jsonDoc - JsonDoc whose _id is shortId. Only the _id property is referenced. shortId is a file path whose collectionPath and extension are omitted. * * @throws {@link Err.UndefinedDocumentIdError} * * @privateRemarks # Errors from deleteImpl * @throws {@link Err.DatabaseClosingError} * @throws {@link Err.TaskCancelError} * * @throws # Errors from deleteWorker * @throws - {@link Err.UndefinedDBError} * @throws - {@link Err.DocumentNotFoundError} * @throws - {@link Err.CannotDeleteDataError} * * @public */ delete(jsonDoc: JsonDoc, options?: DeleteOptions): Promise; /** * @internal */ delete(shortIdOrDoc: string | JsonDoc, options?: DeleteOptions): Promise; /** * Delete a data * * @param shortName - shortName is a file path whose collectionPath is omitted. * * @throws {@link Err.UndefinedDocumentIdError} * * @privateRemarks # Errors from deleteImpl * @throws {@link Err.DatabaseClosingError} * @throws {@link Err.TaskCancelError} * * @throws # Errors from deleteWorker * @throws - {@link Err.UndefinedDBError} * @throws - {@link Err.DocumentNotFoundError} * @throws - {@link Err.CannotDeleteDataError} * * @public */ deleteFatDoc(shortName: string, options?: DeleteOptions): Promise; /** * Get all the JSON documents * * @throws {@link Err.DatabaseClosingError} * @throws {@link Err.InvalidJsonObjectError} * * @public */ find(options?: FindOptions): Promise; /** * Get all the FatDoc data * * @throws {@link Err.DatabaseClosingError} * @throws {@link Err.InvalidJsonObjectError} * * @public */ findFatDoc(options?: FindOptions): Promise; /*********************************************** * Public method (Implementation of SyncEventInterface) ***********************************************/ /** * Add SyncEvent handler * * @eventProperty * @public */ onSyncEvent(remoteURL: string, event: SyncEvent, callback: SyncCallback): SyncInterface; /** * Add SyncEvent handler * * @eventProperty * @public */ onSyncEvent(sync: SyncInterface, event: SyncEvent, callback: SyncCallback): SyncInterface; /** * @internal */ onSyncEvent(remoteURLorSync: string | SyncInterface, event: SyncEvent, callback: SyncCallback): SyncInterface; /** * Remove SyncEvent handler * * @eventProperty * @public */ offSyncEvent(remoteURL: string, event: SyncEvent, callback: SyncCallback): void; /** * Remove SyncEvent handler * * @eventProperty * @public */ offSyncEvent(sync: SyncInterface, event: SyncEvent, callback: SyncCallback): void; /** * @internal */ offSyncEvent(remoteURLorSync: string | SyncInterface, event: SyncEvent, callback: SyncCallback): void; } //# sourceMappingURL=collection.d.ts.map