Skip to content

Latest commit

 

History

History
503 lines (307 loc) · 14.9 KB

api.md

File metadata and controls

503 lines (307 loc) · 14.9 KB

Classes

Workspace
Collection
Fs

File system for a collection.

Workspace

new Workspace([opts])

A Sonar workspace. Provides methods to open collection under this endpoint.

Params

  • opts object - Optional options.
    • url string = "http://localhost:9191/api/v1/default" - The API endpoint to talk to.
    • accessCode string - An access code to login at the endpoint.
    • token string - A JSON web token to authorize to the endpoint.
    • name string - The name of this client.

workspace.close() ⇒ Promise.<void>

Closes the client.

workspace.listCollections() ⇒ Promise.<Array.<object>>

Get a list of all collections available on this endpoint.

Returns: Promise.<Array.<object>> - Promise that resolves to an array of collection info objects.

workspace.createCollection(name, [opts]) ⇒ Promise.<Collection>

Creates a collection with name name on the Sonar server. The name may not contain whitespaces. opts is an optional object with:

Returns: Promise.<Collection> - The created collection.
Params

  • name string - Name of the new collection, may not contain whitespaces.
  • opts object - Optional options object.
    • key string - Hex string of an existing collection. Will then sync this collection instead of creating a new, empty collection.
    • alias string - When setting key, alias is required and is your nick name within this collection.

workspace.updateCollection(name, info) ⇒ Promise.<void>

Updates the config of a collection.

Params

  • name string - Name of the collection.
  • info object - [TODO:description]
    • share boolean - Controls whether a collection is shared via p2p.

workspace.openCollection(keyOrName) ⇒ Promise.<Collection>

Returns a Collection object for a given key or name of a collection.

Params

  • keyOrName string - Key or name of the collection to open/return.

workspace.fetch() ⇒ Promise.<object>

Fetch a resource.

This is a wrapper around the fetch web API. It should be API compatible to fetch, with the following changes:

Returns: Promise.<object> - If the response has a JSON content type header, the decoded JSON will be returned. if opts.responseType is 'binary' or 'text', the response will be returned as a buffer or text.

TODO: Rethink the default responseType cascade.
Params

- *requestType* <code>string</code> <code> = &quot;&#x27;json&#x27;&quot;</code> - Request encoding and content type.

Supported values are 'json' and 'binary' - responseType string = "'text'" - Response encoding. If the response has a JSON content type, will always be set to 'json'. Supported values are 'text', 'binary' and 'stream'. - params object - Query string parameters (will be encoded correctly).

Collection

new Collection(workspace, nameOrKey)

Remote collection

Params

  • workspace Workspace - Remote workspace
  • nameOrKey string - Name or key of the collection

collection.open() ⇒ Promise.<void>

Populate info and schemas for this collection from server.

Throws:

  • Will throw if this collection does not exist or cannot be accessed.

collection.close()

Close the collection.

Properly closes open HTTP requests.

collection.putFeed(key, [info])

Put a new feed to the collection.

Params

  • key string - The hex-encoded key of the feed to add.
  • info object - Optional information about the feed. TODO: Document

collection.query(name, args, [opts]) ⇒ Promise.<Array.<Record>>

Query the collection.

Returns an array of matching records.

Records may have a meta property that includes query-specific metadata (e.g. the score for search queries).

Returns: Promise.<Array.<Record>> - A promise that resolves to an array of record objects.
Params

  • name string - The name of a supported query. Supported queries that ship with @arsonar/core are: records, search, relations, history and indexes.
  • args object - The arguments for the query. Depends on the query being used. For records: { schema, name, id } For history: { from: timestamp, to: timestamp } For search: Either a "string" for a simple full-text search, or a tantivy query object. For indexes: { schema, prop, value, from, to, reverse, limit } (to be documented) For relations: { subject, object, predicate } where subject and object are ids and predicate is type#field
  • opts object - Optional options
    • sync boolean = false - Wait for all pending indexing operations to be finished.

collection.put(record) ⇒ Promise.<object>

Put a new record into the collection.

Returns: Promise.<object> - An object with an { id } property.
Throws:

  • Throws if the record is invalid.

Params

  • record object - The record.
    • schema string - The schema of the record.
    • id string - The entity id of the record. If empoty an id will be created.
    • value object - Value of the record.

collection.get(req, [opts]) ⇒ Promise.<Array.<object>>

Get records by their semantic address (type and id) or by their storage address (key and seq).

Returns: Promise.<Array.<object>> - A promise that resolves to an array of record objects.
Params

  • req object - The get request. Either { type, id } or { key, seq }.
  • opts object - Optional options.
    • sync boolean = false - Wait for all pending indexing operations to be finished.

collection.getVersion(address)

Get a specific version of a record.

Params

  • address string - The block address of the record version feedkey@seq where feedkey is the hex-encoded public key of a feed and seq is a sequence number (uint).

collection.del(record) ⇒ Promise.<object>

Deletes a record.

Returns: Promise.<object> - - An object with { id, type } properties of the deleted record.
Params

  • record object - The record to delete. Has to have { id, type } properties set.

collection.putType(schema) ⇒ Promise.<object>

Add a new type to the collection.

Returns: Promise.<object> - A promise that resolves to the saved schema object.
Throws:

  • Throws if the schema object is invalid or cannot be saved.

Params

  • schema object - A schema object.

collection.createBatchStream() ⇒ Writable.<Record>

Create a writable stream to put records into the collection.

Example:

const batchStream = collection.createBatchStream()
batch.write(record)
batch.close()

Returns: Writable.<Record> - A writable stream

collection.sync() ⇒ Promise.<void>

Wait for all pending indexing operations to be finished.

collection.createEventStream() ⇒ Readable.<object>

Subscribe to events on this collection.

Returns a readable stream that emits event objects. They look like this: { event: string, data: object }

Events are:

  • update: with data { lseq }
  • feed: with data { key }
  • schema-update

collection.pullLiveUpdates()

Pull live updates from the server as they happen.

After calling this method once, all new records and record versions are pulled from the server once available. The update event is emitted when new records are about to arrive.

collection.subscribe(Subscription, Async)

Subscribe to this collection.

This will fetch all records from the first to the last and then waits for new records. Currently only intended for usage in bots (not in short-running Browser clients).

Todo:: Prefix client ID to subscription name.
Todo:: Allow to subscribe from now instead of from the beginning.
Params

  • Subscription string - name. Has to be unique per running Sonar instance
  • Async function - callback function that will be called for each incoming record

collection.reindex(Optional)

Reindex the secondary indexes (views) in this collection.

Use with care, this can be expensive.

Params

  • Optional Array.<string> - array of view names to reindex. If unset all views will be reindexed.

Fs

File system for a collection.

new Fs(collection)

File system for a collection.

Params

fs.listDrives() ⇒ Promise.<Array.<object>>

List the drives that are part of this collection.

Returns: Promise.<Array.<object>> - Array of drive objects with keys { alias, key, writable }

fs.createFile(stream, [metadata], [opts]) ⇒ Record

Create a new file

Returns: Record - - The created file record
Params

  • stream Stream | Buffer - File content as stream or buffer
  • metadata object - File record metadata (see file record schema)
  • opts object - Options.
  • onUploadProgress: Callback to invoke with upload progress information

fs.updateFile(id, stream, [metadata], [opts]) ⇒ Record

Update a file

Returns: Record - - The created file record
Params

  • id string - The file record id
  • stream Stream | Buffer - File content as stream or buffer
  • metadata object - File record metadata (see file record schema)
  • opts object - Options.
  • onUploadProgress: Callback to invoke with upload progress information

fs.readFile(id, [opts]) ⇒ Promise.<(ArrayBuffer|Buffer)>

Read a file into a buffer.

Returns: Promise.<(ArrayBuffer|Buffer)> - The file content. A Buffer object in Node.js, a ArrayBuffer object in the browser.
Throws:

  • Will throw if the path is not found.

Params

  • id string - A file ID
  • opts object - Options. TODO: document.

fs.getFileMetadata(id) ⇒ Promise.<object>

Get the metadata for a file

Returns: Promise.<object> - The file record value (metadata)
Throws:

  • Will throw if the path is not found.

Params

  • id string - A file ID