Beef up the API docs.
git-svn-id: https://www.unprompted.com/svn/projects/tildefriends/trunk@4453 ed5197a5-7fde-0310-b194-c3ffbd925b24
This commit is contained in:
parent
2d82dad806
commit
7c130dda56
File diff suppressed because one or more lines are too long
241
apps/api/docs.js
Normal file
241
apps/api/docs.js
Normal file
@ -0,0 +1,241 @@
|
||||
export const docs = {};
|
||||
|
||||
docs.global = `# <span style="color: #aaf">App Globals</span>
|
||||
The following are functions and values exposed to all apps in their \`app.js\` or \`handler.js\`. Most
|
||||
of these are asynchronous, returning a \`Promise\` that will be resolved when the call completes, unless
|
||||
noted otherwise.
|
||||
|
||||
This is all a work in progess. These are liable to change without warning. Feedback is welcome.
|
||||
|
||||
The exposed functions in this API balance multiple competing needs:
|
||||
* The surface area of the exposed API ought to be fairlyl minimal. If something can be implemented entirely app-side, that is
|
||||
generally preferred over building it into the core.
|
||||
* Everything is built on this API. Ideally the admin app, the SSB app, and the editor all use standard API exposed to all
|
||||
apps, with appropriate permission guards in place making it so that only trusted apps do potentially destructive operations.
|
||||
There will be some things here that aren't necessarily general use to support what's required.
|
||||
`;
|
||||
|
||||
docs['core.user.credentials.session.name'] = `
|
||||
*String* The name of the authenticated user.
|
||||
`;
|
||||
|
||||
docs['app.setDocument()'] = `
|
||||
Set the contents of the client <iframe/>.
|
||||
### Parameters
|
||||
* *String* **html** The HTML contents.
|
||||
`;
|
||||
|
||||
docs['ssb.sqlAsync()'] = `
|
||||
Run an SQL query against the sqlite database.
|
||||
### Parameters
|
||||
* *String* **query** The sqlite query.
|
||||
* *Array* **args** The query arguments to bind.
|
||||
* *Function* **callback** Callback called for each row result.
|
||||
`;
|
||||
|
||||
docs['ssb.appendMessageWithIdentity()'] = `
|
||||
Signs and stores a message in the SSB database.
|
||||
### Parameters
|
||||
* *String* **id** The public key of an SSB identity owned by the authenticated user.
|
||||
* *Object* **message** The unsigned message.
|
||||
`;
|
||||
|
||||
docs['ssb.storeMessage()'] = `
|
||||
Verifies and stores a signed message in the SSB database.
|
||||
### Parameters
|
||||
* *Object* **message** The valid, signed message to store.
|
||||
`;
|
||||
|
||||
docs['ssb.blobStore()'] = `
|
||||
Store a blob in the SSB database.
|
||||
### Parameters
|
||||
* *String*/*Uint8Array* **blob** The blob contents to store
|
||||
### Returns
|
||||
*String* The stored blob ID.
|
||||
`;
|
||||
|
||||
docs['print()'] = `
|
||||
Log debug information both to the server's console and to the visiting user's browser console when possible.
|
||||
### Parameters
|
||||
* **...** Whatever you want to log. Will be joined with spaces.
|
||||
`;
|
||||
|
||||
docs['database()'] = `
|
||||
Returns a database instance that is specific to the authenticated user and the given key.
|
||||
### Parameters
|
||||
* *String* **key** The database key.
|
||||
### Returns
|
||||
*Database* A database.
|
||||
`;
|
||||
|
||||
docs['my_shared_database()'] = `
|
||||
Returns a database instance that is specific to the authenticated user and the given key.
|
||||
### Parameters
|
||||
* *String* **package_name** The database package name.
|
||||
* *String* **key** The database key.
|
||||
### Returns
|
||||
*Database* A database.
|
||||
`;
|
||||
|
||||
docs['shared_database()'] = `
|
||||
Returns a database instance that is shared between all users of the app, determined by its owner and app name.
|
||||
### Parameters
|
||||
* *String* **key** The database key.
|
||||
### Returns
|
||||
*Database* A database.
|
||||
`;
|
||||
|
||||
docs['utf8Decode()'] =`
|
||||
Decode UTF-8 bytes to a string.
|
||||
|
||||
Completes synchronously.
|
||||
### Parameters
|
||||
* *Uint8Array* **value** The value to decode.
|
||||
### Returns
|
||||
*String* The value as a string.
|
||||
`;
|
||||
|
||||
docs['utf8Encode()'] =`
|
||||
Encodes a string to UTF-8 bytes.
|
||||
|
||||
Completes synchronously.
|
||||
### Parameters
|
||||
* *String* **value** The value to encode.
|
||||
### Returns
|
||||
*Uint8Array* The encoded \`value\`.
|
||||
`;
|
||||
|
||||
docs['sha1Digest()'] =`
|
||||
Calculates a SHA1 digest.
|
||||
|
||||
Completes synchronously.
|
||||
### Parameters
|
||||
* *String* **value** The value for which to calculate the digest.
|
||||
### Returns
|
||||
*String* The SHA1 digest of UTF-8 encoded \`value\`.
|
||||
`;
|
||||
|
||||
docs['maskBytes()'] = `
|
||||
Masks bytes for WebSocket communication.
|
||||
|
||||
Completes synchronously.
|
||||
### Parameters
|
||||
* *Uint8Array* **bytes** The byte array of data to mask.
|
||||
* *Uint32* **mask** The mask to apply.
|
||||
### Returns
|
||||
*Uint32Array* The masked bytes.
|
||||
`;
|
||||
|
||||
docs['exit()'] = `
|
||||
Exits the app. But why would you want to do that?
|
||||
|
||||
Completes synchronously.
|
||||
### Parameters
|
||||
* *Integer* **exit_code** System exit code.
|
||||
`;
|
||||
|
||||
docs['version()'] = `
|
||||
Gets version information for the running server.
|
||||
### Returns
|
||||
*Object* Keys are things like \`name\` and \`number\` for the server itself and \`libuv\` and \`openssl\` for
|
||||
dependencies. Values are *String* version numbers.
|
||||
`;
|
||||
|
||||
docs['platform()'] = `
|
||||
Gets the host operating system platform of the running server.
|
||||
### Returns
|
||||
*String* The platform, one of \`windows\`, \`android\`, \`linux\`, or \`other\`.
|
||||
`;
|
||||
|
||||
docs['getFile()'] = `
|
||||
Gets a file from the running app.
|
||||
### Parameters
|
||||
* *String* **name** Name of the file to retrieve.
|
||||
### Returns
|
||||
*Uint8Array* The contents of a file from the app with the given name, or *undefined*.
|
||||
`;
|
||||
|
||||
docs.database = `
|
||||
# <span style="color: #aaf">Database</span>
|
||||
Local-only storage is provided by a \`Database\` type representing a key-value store.
|
||||
`;
|
||||
|
||||
docs['database.get()'] = `
|
||||
Gets a value from the database.
|
||||
### Parameters
|
||||
* *String* **key** The key.
|
||||
### Returns
|
||||
*String* The value from the database or undefined if not found.
|
||||
`;
|
||||
|
||||
docs['database.getAll()'] = `
|
||||
Gets all keys from the database.
|
||||
### Returns
|
||||
*Array* An array of *String* key names for all keys in the given database.
|
||||
`;
|
||||
|
||||
docs['database.getLike()'] = `
|
||||
Gets all keys and values from the database matching a pattern.
|
||||
### Parameters
|
||||
* *String* **pattern** An sqlite \`LIKE\` pattern to match keys against.
|
||||
### Returns
|
||||
*Object* An object whose keys are the database keys and values are the database values that match the given pattern.
|
||||
`;
|
||||
|
||||
docs['database.set()'] = `
|
||||
Sets a value in the database, creating a new entry or replacing an existing entry.
|
||||
### Parameters
|
||||
* *String* **key** The key.
|
||||
* *String* **value** The value.
|
||||
`;
|
||||
|
||||
docs['database.exchange()'] = `
|
||||
Performs an atomic compare and exchange operation, setting a value in the database only if its current value matches what is expected.
|
||||
### Parameters
|
||||
* *String* **key** The key.
|
||||
* *String* **expected** The expected value.
|
||||
* *String* **value** The new value.
|
||||
### Returns
|
||||
*Boolean* true if the value is now the given value.
|
||||
`;
|
||||
|
||||
docs['database.remove()'] = `
|
||||
Removes an entry from the database if it exists.
|
||||
### Parameters
|
||||
* *String* **key** The key.
|
||||
`;
|
||||
|
||||
docs.tfrpc = `
|
||||
# <span style="color: #aaf">tfrpc</span>
|
||||
\`tfrpc.js\` is a small helper script that is available to be used to facilitate communication between parts of an application.
|
||||
|
||||
\`tfrpc.js\` can be used to asynchronously make calls between the app in the browser and the app process on the server.
|
||||
|
||||
From \`app.js\`:
|
||||
\`\`\`
|
||||
import * as tfrpc from '/tfrpc.js';
|
||||
\`\`\`
|
||||
|
||||
|
||||
From script running in the browser:
|
||||
\`\`\`
|
||||
import * as tfrpc from '/static/tfrpc.js';
|
||||
\`\`\`
|
||||
|
||||
Either side can register or call functions, though they must be registered before they can be called. Arguments and return
|
||||
values are ultimately serialized by means that attempt to preserve most JSON-serializable values as well as functions themselves.
|
||||
`;
|
||||
|
||||
docs['tfrpc.register()'] = `
|
||||
Register a function, allowing it to be called remotely.
|
||||
### Parameters
|
||||
* *Function* **function** The function to register. Its name will be how it will be called.
|
||||
`;
|
||||
|
||||
docs['tfrpc.rpc.*()'] = `
|
||||
Call a remote function.
|
||||
### Parameters
|
||||
* **...** Parameters to pass to the function.
|
||||
### Returns
|
||||
The return value of the called function.
|
||||
`;
|
||||
Loading…
Reference in New Issue
Block a user