API reference
SinterDB driver API
88 exports · 6 classes · 14 errors · 26 interfaces · 36 type aliases · 6 variables · hierarchy
Classes#
- AggregateCursorA lazy, batched cursor over the results of an aggregation. It reads like a FindCursor: nothing is sent until the first read, documents arrive in batches, and
toArray()andfor awaitclose the cursor for you. - CustomId
- FindCursorA lazy, batched cursor over the results of a find.
- SinterClientA connection to a SinterDB server.
- SinterCollectionA collection of documents, typed by
TDocument. - SinterDatabaseA handle to a database on a server.
Errors#
- SinterClientOptionsErrorA client option or a database or collection name is invalid. Code
INVALID_CLIENT_OPTIONS. - SinterClientStateErrorA command was used in the wrong client state:
CLIENT_NOT_CONNECTEDbeforeconnect(), orCLIENT_CLOSEDafterclose(). - SinterCompatibilityErrorThe server does not speak a compatible protocol version. Code
INCOMPATIBLE_PROTOCOL. - SinterConnectionErrorThe connection could not be established or was lost. Code
CONNECTION_FAILED. - SinterConnectionStringErrorThe connection string is malformed. Code
INVALID_CONNECTION_STRING. - SinterConnectionTimeoutErrorConnecting took longer than
connectTimeoutMS. - SinterDocumentErrorA request could not be encoded, so nothing was sent and the connection is unaffected. The usual causes are a value the database cannot store (such as
undefined, a function, or a class instance likeMap), a document nested more than 100 levels deep, or a request larger than 16 MiB. Thecausesays which. CodeINVALID_DOCUMENT. - SinterErrorThe base class of every error the driver throws on its own. Check
codeto tell them apart. - SinterInsertManyError
insertManyfailed partway. The documents beforefailedIndexwere inserted and stay committed. - SinterNamespaceErrorA database or collection name is invalid: empty, or containing forbidden characters. Code
INVALID_CLIENT_OPTIONS. - SinterProtocolErrorThe server sent something the driver cannot interpret. Code
PROTOCOL_VIOLATION. - SinterRequestTimeoutErrorA request got no response within
requestTimeoutMS. The request may still have run on the server. CodeREQUEST_TIMEOUT. - SinterServerErrorThe server rejected a request. Code
SERVER_ERROR. - SinterSocketTimeoutErrorThe connection was idle for longer than
socketTimeoutMS.
Interfaces#
- AggregateOptionsOptions for SinterCollection.aggregate.
- CreateIndexResultThe result of SinterCollection.createIndex.
- DeleteResultThe result of a delete.
- Document
- ExplainResultThe query plan the server reports for a find. The shape is experimental and may change in any release; see docs/compatibility.md.
- FindOneOptionsOptions for SinterCollection.findOne.
- FindOptionsOptions for SinterCollection.find.
- FindQueryOptionsThe query parts of a find that are sent with the first request.
- GroupSpecificationThe argument of
$group: an_idthat says how to group, plus any number of output fields, each computed by an accumulator. - IndexBoundInfoOne end of an index range in an ExplainResult.
- IndexDefinitionOptionsThe options every index definition accepts.
- IndexInfoA description of an index, as returned by SinterCollection.indexes.
- IndexIssueOne difference found by SinterCollection.validateIndexes.
- IndexKeyInfoOne field of an index and the order it is kept in.
- IndexValidationResultThe result of SinterCollection.validateIndexes.
- InsertManyResultThe result of SinterCollection.insertMany.
- InsertOneResultThe result of SinterCollection.insertOne.
- ParsedSinterConnectionStringA parsed
sinterdb://connection string, available as SinterClient.target. - QueryBudgetOptionsLimits on what one server request may cost. Both are optional, and a request that passes a limit fails with a SinterServerError named
OperationTimeLimitExceededorScanLimitExceeded. - SinterClientEventsThe events a SinterClient emits.
- SinterClientOptionsOptions for SinterClient. Every timeout is a whole number of milliseconds no greater than 2,147,483,647. An invalid value throws a SinterClientOptionsError.
- SinterPingResultThe result of SinterClient.ping.
- SinterServerErrorOptionsDetails a server error response can carry.
- SinterServerInfoWhat the server reported during the protocol handshake. Available from SinterClient.serverInfo once the client is connected.
- UpdateOptionsOptions for updates and replacements.
- UpdateResultThe result of an update or replace.
Type Aliases#
- AggregationStageOne stage of an aggregation pipeline. Each stage is an object with a single
$key. Documents flow through the stages in order. - ArrayOperatorsWhat a filter can say about the elements of an array:
$sizeand$elemMatch. They are available only when the value type is an array. - ArrayPathsUpdatable paths that hold an array, the targets of
$push,$addToSetand$pull. - AtomicValueValues that can be matched by equality: comparable values, booleans and
null. - ComparablePathsUpdatable paths that hold a comparable value, the targets of
$minand$max. - ComparableValueValues that can be compared with
$gt,$gte,$ltand$lte. - ComparisonOperatorsThe range operators
$gt,$gte,$ltand$lte. They are available only when the value type includes a comparable type. - CursorExecutorThe function a FindCursor uses to reach the server. Cursors are created by SinterCollection.find; do not construct them directly.
- DistinctValueThe type of one value returned by SinterCollection.distinct for a field: the element type when the field holds an array.
- ElementMatchWhat
$elemMatchaccepts for an array whose elements have this type. - ElementOfThe element type of an array type, or the type itself when it is not an array.
- EqualityFilterA shorthand filter that matches fields by equality only.
- FieldPathsEvery dotted field path that names a single field: like FilterPaths, but a path never runs through an array. Sorting, updates, and indexes use these paths, because they treat a path through an array as missing or do not support it.
- FilterA query filter: field paths mapped to a value or to operators, combined with
$and,$orand$nor. An empty filter matches every document. - FilterOperatorsThe operators that can be applied to a single field:
$eq,$ne,$in,$nin,$exists,$not, plus the range operators for comparable values and$sizeand$elemMatchfor arrays. - FilterPathsEvery dotted field path of a document type, such as
profile.name, oritems.skufor an array of documents. Atomic values and arrays of atomic values end a path. - FilterPathValueThe type of the value at a dotted field path. A path through an array reads the type of the elements.
- GroupAccumulatorWhat a
$groupstage computes for each group. Each is an object with one key. - GroupValueA value in a
$groupstage: a field reference or a literal. A string that starts with$names a field of the incoming document ("$age", or"$address.city"for a nested one). A document without the field givesnullin a key. Any other value is a literal. There is no way to write a literal string that starts with$. - IndexablePathField paths that can be indexed: every known path except
_id, which always has its own unique index. - IndexDefinitionHow to build an index, passed to SinterCollection.createIndex.
- MaxPathDepthHow many levels of nesting the compiler follows when it builds field paths. Deeper paths still work at runtime but are not suggested or type-checked.
- NumericPathsUpdatable paths that hold a number or bigint, the targets of
$inc. - OptionalIdA document as accepted for insertion:
_idis optional, and the server generates one when it is missing. - PathChildWhat a dotted path steps into: the value itself, or the elements of an array.
items.skuis a valid path whenitemsis an array of documents. - PathsMatchingThe updatable paths whose value type is assignable to
TKind. - ProjectedDocumentThe type of the documents a query returns for a projection.
- ProjectionWhich fields a query returns, as field paths mapped to a flag.
- ProjectionFlag
1ortruekeeps a field;0orfalseremoves it. - SinterClientStateA value of SinterClientState.
- SinterErrorCodeA value of SinterErrorCode.
- SortA sort order:
[path, direction]pairs, where earlier pairs take priority. - SortDirection
1for ascending or-1for descending. - UpdateFilterAn update document built from operators:
$set,$unset,$inc,$min,$max,$push,$addToSetand$pull. Each operator accepts only paths of a matching type. - UpdatePathsThe field paths an update can change: every path except
_id, which is immutable. - WithIdA document as stored and returned:
_idis always present.
Variables#
- DEFAULT_CONNECT_TIMEOUT_MSThe default
connectTimeoutMS: 10 seconds. - DEFAULT_REQUEST_TIMEOUT_MSThe default
requestTimeoutMS: 10 seconds. - DEFAULT_SINTERDB_PORTThe port used when a connection string does not name one: 4721.
- DEFAULT_SOCKET_TIMEOUT_MSThe default
socketTimeoutMS: 0, which disables the idle timeout. - SinterClientStateThe lifecycle states of a SinterClient.
- SinterErrorCodeThe stable string codes carried by SinterError.code. Branch on these rather than on message text.