tinybase 5.0.0-beta.2 → 5.0.0-beta.21

package/lib/types/with-schemas/persisters/persister-partykit-server.d.ts

@@ -1,652 +0,0 @@
-/**
- * The persister-partykit-server module of the TinyBase project contains the
- * server portion of the PartyKit integration.
- *
- * It contains a class which, when run in a PartyKit server environment, lets
- * you save and load Store data from a client (that is using the complementary
- * persister-partykit-client module) to durable PartyKit cloud storage.
- *
- * This enables synchronization of the same Store across multiple clients in a
- * PartyKit party room.
- *
- * Note that both the client and server parts of this Persister are currently
- * experimental as PartyKit is new and still maturing.
- * @see Persisting Data guide
- * @see Todo App v6 (collaboration) demo
- * @packageDocumentation
- * @module persister-partykit-server
- * @since 4.3.0
- */
-
-import {
-  Cell,
-  CellOrUndefined,
-  NoTablesSchema,
-  NoValuesSchema,
-  OptionalSchemas,
-  Tables,
-  TransactionChanges,
-  Value,
-  ValueOrUndefined,
-  Values,
-} from '../store';
-import {Connection, Party, Request, Server} from 'partykit/server';
-import {Id} from '../common';
-
-/**
- * The TinyBasePartyKitServerConfig type describes the configuration of a
- * PartyKit Persister on the server side.
- *
- * The defaults (if used on both the server and client) will work fine, but if
- * you are building more complex PartyKit apps and you need to configure path
- * names, for example, then this is the type to use.
- * @example
- * When set as the config in a TinyBasePartyKitServer, this
- * TinyBasePartyKitServerConfig will expect clients to load and save their JSON
- * serialization from and to an end point in the room called `/my_tinybase`.
- * Note that this would require you to also add the matching storePath setting
- * to the PartyKitPersisterConfig on the client side.
- *
- * It will also store the data in the durable storage with a prefix of
- * 'tinybase_' in case you are worried about colliding with other data stored
- * in the room.
- *
- * ```js
- * class MyServer extends TinyBasePartyKitServer {
- *   readonly config = {
- *     storePath: '/my_tinybase',
- *     storagePrefix: 'tinybase_',
- *   };
- * }
- * ```
- * @category Configuration
- * @since v4.3.9
- */
-export type TinyBasePartyKitServerConfig = {
-  /**
-   * The path used to set and get the whole Store over HTTP(S) on the server.
-   * This must match the storePath property of the PartyKitPersisterConfig used
-   * on the client. Both default to '/store'.
-   */
-  storePath?: string;
-  /**
-   * The prefix at the beginning of the web socket messages between the client
-   * and the server when synchronizing the Store. Use this to make sure they do
-   * not collide with any other message syntax that your room is using. This
-   * must match the messagePrefix property of the PartyKitPersisterConfig object
-   * used on the client. Both default to an empty string.
-   */
-  messagePrefix?: string;
-  /**
-   * The prefix used before all the keys in the server's durable storage. Use
-   * this in case you are worried about the Store data colliding with other data
-   * stored in the room. Defaults to an empty string.
-   */
-  storagePrefix?: string;
-  /**
-   * An object containing the extra HTTP(S) headers returned to the client from
-   * this server. This defaults to the following three headers to allow CORS:
-   *
-   * ```
-   * Access-Control-Allow-Origin: *
-   * Access-Control-Allow-Methods: *
-   * Access-Control-Allow-Headers: *
-   * ```
-   *
-   * If you set this field, it will override the default completely. So, for
-   * example, if you add another header but still want the CORS defaults, you
-   * will need to explicitly set the Access-Control-Allow headers above again.
-   */
-  responseHeaders?: HeadersInit;
-};
-
-/**
- * A TinyBasePartyKitServer is the server component for persisting the Store to
- * durable PartyKit storage, enabling synchronization of the same Store across
- * multiple clients.
- *
- * This extends the PartyKit Server class, which provides a selection of methods
- * you are expected to implement. The TinyBasePartyKitServer implements only two
- * of them, the onMessage method and the onRequest method, as well as the
- * constructor.
- *
- * If you wish to use TinyBasePartyKitServer as a general PartyKit server, you
- * can implement other methods. But you must remember to call the super
- * implementations of those methods to ensure the TinyBase synchronization stays
- * supported in addition to your own custom functionality. The same applies to
- * the constructor if you choose to implement that.
- *
- * ```js
- * // This is your PartyKit server entry point.
- *
- * class MyServer extends TinyBasePartyKitServer {
- *   constructor(party) {
- *     super(party);
- *     // custom constructor code
- *   }
- *
- *   async onStart() {
- *     // no need to call super.onStart()
- *     console.log('Server started');
- *   }
- *
- *   async onMessage(message, connection) {
- *     await super.onMessage(message, connection);
- *     // custom onMessage code
- *   }
- *
- *   async onRequest(request) {
- *     // custom onRequest code, else:
- *     return await super.onRequest(request);
- *   }
- * }
- * ```
- *
- * See the [PartyKit server API
- * documentation](https://docs.partykit.io/reference/partyserver-api/) for
- * more details.
- * @category Creation
- * @since v4.3.0
- */
-export class TinyBasePartyKitServer implements Server {
-  /**
-   * The constructor is used to create the server.
-   * @category Creation
-   * @since v4.3.9
-   */
-  constructor(party: Party);
-  /**
-   * The config property is used to optionally configure the server, using an
-   * object of the TinyBasePartyKitServerConfig type.
-   *
-   * See the documentation for that type for more details.
-   * @category Configuration
-   * @since v4.3.9
-   */
-  readonly config: TinyBasePartyKitServerConfig;
-  /**
-   * The onRequest method is called when a HTTP request is made to the party
-   * URL.
-   *
-   * If you choose to implement additional functionality in this method, you
-   * must remember to call the super implementation to ensure the TinyBase
-   * synchronization stays supported:
-   *
-   * ```js
-   * class MyServer extends TinyBasePartyKitServer {
-   *   async onRequest(request) {
-   *     // custom onRequest code, else:
-   *     return await super.onRequest(request);
-   *   }
-   * }
-   * ```
-   *
-   * See the [PartyKit server API
-   * documentation](https://docs.partykit.io/reference/partyserver-api/) for
-   * more details.
-   * @category Connection
-   * @since v4.3.0
-   */
-  onRequest(request: Request): Promise<Response>;
-  /**
-   * The onMessage method is called when the server receives a message from a
-   * client.
-   *
-   * If you choose to implement additional functionality in this method, you
-   * must remember to call the super implementation to ensure the TinyBase
-   * synchronization stays supported:
-   *
-   * ```js
-   * class MyServer extends TinyBasePartyKitServer {
-   *   async onMessage(message, connection) {
-   *     await super.onMessage(message, connection);
-   *     // custom onMessage code
-   *   }
-   * }
-   * ```
-   *
-   * See the [PartyKit server API
-   * documentation](https://docs.partykit.io/reference/partyserver-api/) for
-   * more details.
-   * @category Connection
-   * @since v4.3.0
-   */
-  onMessage(message: string, connection: Connection): Promise<void>;
-  /**
-   * The canSetTable method lets you allow or disallow any changes to a Table
-   * stored on the server, as sent from a client.
-   *
-   * This is one of the functions use to sanitize the data that is being sent
-   * from a client. Perhaps you might want to make sure the server-stored data
-   * adheres to a particular schema, or you might want to make certain data
-   * read-only. Remember that you cannot trust the client to only send data that
-   * the server considers valid or safe.
-   *
-   * This method is passed the Table Id that the client is trying to change. The
-   * `initialSave` parameter distinguishes between the first bulk save of the
-   * Store to the PartyKit room over HTTP (`true`), and subsequent incremental
-   * updates over a web sockets (`false`).
-   *
-   * The `requestOrConnection` parameter will either be the HTTP(S) request or
-   * the web socket connection, in those two cases respectively. You can, for
-   * instance, use this to distinguish between different users.
-   *
-   * Since v4.3.13, the final parameter is the Cell previously stored on the
-   * server, if any. Use this to distinguish between the addition of a new Cell
-   * (in which case it will be undefined) and the updating of an existing one.
-   *
-   * Return `false` from this method to disallow changes to this Table on the
-   * server, or `true` to allow them (subject to subsequent canSetRow method,
-   * canDelRow method, canSetCell method, and canSetCell method checks). The
-   * default implementation returns `true` to allow all changes.
-   * @example
-   * The following implementation will strip out any attempts by the client to
-   * update any 'user' tabular data after the initial save:
-   *
-   * ```js
-   * class MyServer extends TinyBasePartyKitServer {
-   *   canSetTable(tableId, initialSave) {
-   *     return initialSave || tableId != 'user';
-   *   }
-   * }
-   * ```
-   * @category Sanitization
-   * @since v4.3.12
-   */
-  canSetTable(
-    tableId: Id,
-    initialSave: boolean,
-    requestOrConnection: Request | Connection,
-  ): Promise<boolean>;
-  /**
-   * The canDelTable method lets you allow or disallow deletions of a Table
-   * stored on the server, as sent from a client.
-   *
-   * This is one of the functions use to sanitize the data that is being sent
-   * from a client. Perhaps you might want to make sure the server-stored data
-   * adheres to a particular schema, or you might want to make certain data
-   * read-only. Remember that you cannot trust the client to only send data that
-   * the server considers valid or safe.
-   *
-   * This method is passed the Table Id that the client is trying to delete. The
-   * `connection` parameter will be the web socket connection of that client.
-   * You can, for instance, use this to distinguish between different users.
-   *
-   * Return `false` from this method to disallow this Table from being deleted
-   * on the server, or `true` to allow it. The default implementation returns
-   * `true` to allow deletion.
-   * @example
-   * The following implementation will strip out any attempts by the client to
-   * delete the 'user' Table:
-   *
-   * ```js
-   * class MyServer extends TinyBasePartyKitServer {
-   *   canDelTable(tableId) {
-   *     return tableId != 'user';
-   *   }
-   * }
-   * ```
-   * @category Sanitization
-   * @since v4.3.12
-   */
-  canDelTable(tableId: Id, connection: Connection): Promise<boolean>;
-  /**
-   * The canSetRow method lets you allow or disallow any changes to a Row stored
-   * on the server, as sent from a client.
-   *
-   * This is one of the functions use to sanitize the data that is being sent
-   * from a client. Perhaps you might want to make sure the server-stored data
-   * adheres to a particular schema, or you might want to make certain data
-   * read-only. Remember that you cannot trust the client to only send data that
-   * the server considers valid or safe.
-   *
-   * This method is passed the Table Id and Row Id that the client is trying to
-   * change. The `initialSave` parameter distinguishes between the first bulk
-   * save of the Store to the PartyKit room over HTTP (`true`), and subsequent
-   * incremental updates over a web sockets (`false`).
-   *
-   * The final `requestOrConnection` parameter will either be the HTTP(S)
-   * request or the web socket connection, in those two cases respectively. You
-   * can, for instance, use this to distinguish between different users.
-   *
-   * Return `false` from this method to disallow changes to this Row on the
-   * server, or `true` to allow them (subject to subsequent canSetCell method
-   * and canSetCell method checks). The default implementation returns `true` to
-   * allow all changes.
-   * @example
-   * The following implementation will strip out any attempts by the client to
-   * update the 'me' Row of the 'user' Table after the initial save:
-   *
-   * ```js
-   * class MyServer extends TinyBasePartyKitServer {
-   *   canSetRow(tableId, rowId, initialSave) {
-   *     return initialSave || tableId != 'user' || rowId != 'me';
-   *   }
-   * }
-   * ```
-   * @category Sanitization
-   * @since v4.3.12
-   */
-  canSetRow(
-    tableId: Id,
-    rowId: Id,
-    initialSave: boolean,
-    requestOrConnection: Request | Connection,
-  ): Promise<boolean>;
-  /**
-   * The canDelRow method lets you allow or disallow deletions of a Row stored
-   * on the server, as sent from a client.
-   *
-   * This is one of the functions use to sanitize the data that is being sent
-   * from a client. Perhaps you might want to make sure the server-stored data
-   * adheres to a particular schema, or you might want to make certain data
-   * read-only. Remember that you cannot trust the client to only send data that
-   * the server considers valid or safe.
-   *
-   * This method is passed the Table Id and Row Id that the client is trying to
-   * delete. The `connection` parameter will be the web socket connection of
-   * that client. You can, for instance, use this to distinguish between
-   * different users.
-   *
-   * Return `false` from this method to disallow this Row from being deleted
-   * on the server, or `true` to allow it. The default implementation returns
-   * `true` to allow deletion.
-   * @example
-   * The following implementation will strip out any attempts by the client to
-   * delete the 'me' Row of the 'user' Table:
-   *
-   * ```js
-   * class MyServer extends TinyBasePartyKitServer {
-   *   canDelRow(tableId, rowId) {
-   *     return tableId != 'user' || rowId != 'me';
-   *   }
-   * }
-   * ```
-   * @category Sanitization
-   * @since v4.3.12
-   */
-  canDelRow(tableId: Id, rowId: Id, connection: Connection): Promise<boolean>;
-  /**
-   * The canSetCell method lets you allow or disallow any changes to a Cell
-   * stored on the server, as sent from a client.
-   *
-   * This has schema-based typing. The following is a simplified representation:
-   *
-   * ```ts override
-   * canSetCell(
-   *   tableId: Id,
-   *   rowId: Id,
-   *   cellId: Id,
-   *   cell: Cell,
-   *   initialSave: boolean,
-   *   requestOrConnection: Request | Connection,
-   *   oldCell: CellOrUndefined,
-   * ): Promise<boolean>;
-   * ```
-   *
-   * This is one of the functions use to sanitize the data that is being sent
-   * from a client. Perhaps you might want to make sure the server-stored data
-   * adheres to a particular schema, or you might want to make certain data
-   * read-only. Remember that you cannot trust the client to only send data that
-   * the server considers valid or safe.
-   *
-   * This method is passed the Table Id, Row Id, and Cell Id that the client is
-   * trying to change - as well as the Cell value itself. The `initialSave`
-   * parameter distinguishes between the first bulk save of the Store to the
-   * PartyKit room over HTTP (`true`), and subsequent incremental updates over a
-   * web sockets (`false`).
-   *
-   * The final `requestOrConnection` parameter will either be the HTTP(S)
-   * request or the web socket connection, in those two cases respectively. You
-   * can, for instance, use this to distinguish between different users.
-   *
-   * Return `false` from this method to disallow changes to this Cell on the
-   * server, or `true` to allow them. The default implementation returns `true`
-   * to allow all changes.
-   * @example
-   * The following implementation will strip out any attempts by the client to
-   * update the 'name' Cell of the 'me' Row of the 'user' Table after the
-   * initial save:
-   *
-   * ```js
-   * class MyServer extends TinyBasePartyKitServer {
-   *   canSetCell(tableId, rowId, cellId, cell, initialSave) {
-   *     return (
-   *       initialSave || tableId != 'user' || rowId != 'me' || cellId != 'name'
-   *     );
-   *   }
-   * }
-   * ```
-   * @category Sanitization
-   * @since v4.3.12
-   */
-  canSetCell(
-    tableId: Id,
-    rowId: Id,
-    cellId: Id,
-    cell: Cell<NoTablesSchema, Id, Id>,
-    initialSave: boolean,
-    requestOrConnection: Request | Connection,
-    oldCell: CellOrUndefined<NoTablesSchema, Id, Id>,
-  ): Promise<boolean>;
-  /**
-   * The canDelCell method lets you allow or disallow deletions of a Cell stored
-   * on the server, as sent from a client.
-   *
-   * This is one of the functions use to sanitize the data that is being sent
-   * from a client. Perhaps you might want to make sure the server-stored data
-   * adheres to a particular schema, or you might want to make certain data
-   * read-only. Remember that you cannot trust the client to only send data that
-   * the server considers valid or safe.
-   *
-   * This method is passed the Table Id, Row Id, and Cell Id that the client is
-   * trying to delete. The `connection` parameter will be the web socket
-   * connection of that client. You can, for instance, use this to distinguish
-   * between different users.
-   *
-   * Return `false` from this method to disallow this Cell from being deleted on
-   * the server, or `true` to allow it. The default implementation returns
-   * `true` to allow deletion.
-   * @example
-   * The following implementation will strip out any attempts by the client to
-   * delete the 'name' Cell of the 'me' Row of the 'user' Table:
-   *
-   * ```js
-   * class MyServer extends TinyBasePartyKitServer {
-   *   canDelCell(tableId, rowId, cellId) {
-   *     return tableId != 'user' || rowId != 'me' || cellId != 'name';
-   *   }
-   * }
-   * ```
-   * @category Sanitization
-   * @since v4.3.12
-   */
-  canDelCell(
-    tableId: Id,
-    rowId: Id,
-    cellId: Id,
-    connection: Connection,
-  ): Promise<boolean>;
-  /**
-   * The canSetValue method lets you allow or disallow any changes to a Value
-   * stored on the server, as sent from a client.
-   *
-   * This has schema-based typing. The following is a simplified representation:
-   *
-   * ```ts override
-   * canSetValue(
-   *   valueId: Id,
-   *   value: Value,
-   *   initialSave: boolean,
-   *   requestOrConnection: Request | Connection,
-   *   oldValue: ValueOrUndefined,
-   * ): Promise<boolean>;
-   * ```
-   *
-   * This is one of the functions use to sanitize the data that is being sent
-   * from a client. Perhaps you might want to make sure the server-stored data
-   * adheres to a particular schema, or you might want to make certain data
-   * read-only. Remember that you cannot trust the client to only send data that
-   * the server considers valid or safe.
-   *
-   * This method is passed the Value Id that the client is trying to change - as
-   * well as the Value itself. The `initialSave` parameter distinguishes between
-   * the first bulk save of the Store to the PartyKit room over HTTP (`true`),
-   * and subsequent incremental updates over a web sockets (`false`).
-   *
-   * The `requestOrConnection` parameter will either be the HTTP(S) request or
-   * the web socket connection, in those two cases respectively. You can, for
-   * instance, use this to distinguish between different users.
-   *
-   * Since v4.3.13, the final parameter is the Value previously stored on the
-   * server, if any. Use this to distinguish between the addition of a new Value
-   * (in which case it will be undefined) and the updating of an existing one.
-   *
-   * Return `false` from this method to disallow changes to this Value on the
-   * server, or `true` to allow them. The default implementation returns `true`
-   * to allow all changes.
-   * @example
-   * The following implementation will strip out any attempts by the client to
-   * update the 'userId' Value after the initial save:
-   *
-   * ```js
-   * class MyServer extends TinyBasePartyKitServer {
-   *   canSetValue(valueId, value, initialSave) {
-   *     return initialSave || userId != 'userId';
-   *   }
-   * }
-   * ```
-   * @category Sanitization
-   * @since v4.3.12
-   */
-  canSetValue(
-    valueId: Id,
-    value: Value<NoValuesSchema, Id>,
-    initialSave: boolean,
-    requestOrConnection: Request | Connection,
-    oldValue: ValueOrUndefined<NoValuesSchema, Id>,
-  ): Promise<boolean>;
-  /**
-   * The canDelValue method lets you allow or disallow deletions of a Value
-   * stored on the server, as sent from a client.
-   *
-   * This is one of the functions use to sanitize the data that is being sent
-   * from a client. Perhaps you might want to make sure the server-stored data
-   * adheres to a particular schema, or you might want to make certain data
-   * read-only. Remember that you cannot trust the client to only send data that
-   * the server considers valid or safe.
-   *
-   * This method is passed the Value Id that the client is trying to delete. The
-   * `connection` parameter will be the web socket connection of that client.
-   * You can, for instance, use this to distinguish between different users.
-   *
-   * Return `false` from this method to disallow this Value from being deleted
-   * on the server, or `true` to allow it. The default implementation returns
-   * `true` to allow deletion.
-   * @example
-   * The following implementation will strip out any attempts by the client to
-   * delete the 'userId' Value:
-   *
-   * ```js
-   * class MyServer extends TinyBasePartyKitServer {
-   *   canDelValue(valueId) {
-   *     return valueId != 'userId';
-   *   }
-   * }
-   * ```
-   * @category Sanitization
-   * @since v4.3.12
-   */
-  canDelValue(valueId: Id, connection: Connection): Promise<boolean>;
-}
-
-/**
- * The hasStoreInStorage function returns a boolean indicating whether durable
- * PartyKit storage contains a serialized Store.
- *
- * This is intended for specialist applications that require the ability to
- * inspect or load a TinyBase Store from a server's storage outside of the
- * normal context of a TinyBasePartyKitServer.
- *
- * The function is asynchronous, so you should use the `await` keyword or handle
- * the result as a promise.
- * @param storage A reference to the storage object, as would normally be
- * accessible from the `TinyBasePartyKitServer.party` object.
- * @param storagePrefix An optional prefix used before all the keys in the
- * server's durable storage, to match the equivalent property in the server's
- * TinyBasePartyKitServerConfig.
- * @returns A promised boolean indicating whether a Store is present in the
- * storage.
- * @category Storage
- * @since v4.4.1
- */
-export function hasStoreInStorage(
-  storage: Storage,
-  storagePrefix?: string,
-): Promise<boolean>;
-
-/**
- * The loadStoreFromStorage function returns the content of a Store from durable
- * PartyKit storage.
- *
- * This has schema-based typing. The following is a simplified representation:
- *
- * ```ts override
- * loadStoreFromStorage(
- *   storage: Storage,
- *   storagePrefix?: string,
- * ): Promise<[Tables, Values]>;
- * ```
- *
- * This is intended for specialist applications that require the ability to
- * inspect or load a TinyBase Store from a server's storage outside of the
- * normal context of a TinyBasePartyKitServer.
- *
- * The function is asynchronous, so you should use the `await` keyword or handle
- * the result as a promise.
- * @param storage A reference to the storage object, as would normally be
- * accessible from the `TinyBasePartyKitServer.party` object.
- * @param storagePrefix An optional prefix used before all the keys in the
- * server's durable storage, to match the equivalent property in the server's
- * TinyBasePartyKitServerConfig.
- * @returns A promised array of a Tables object and a Values object.
- * @category Storage
- * @since v4.4.1
- */
-export function loadStoreFromStorage<Schemas extends OptionalSchemas>(
-  storage: Storage,
-  storagePrefix?: string,
-): Promise<[Tables<Schemas[0]>, Values<Schemas[1]>]>;
-
-/**
- * The broadcastTransactionChanges function allows you to broadcast Store
- * changes to all the client connections of a TinyBasePartyKitServer.
- *
- * This has schema-based typing. The following is a simplified representation:
- *
- * ```ts override
- * broadcastTransactionChanges(
- *   server: TinyBasePartyKitServer,
- *   transactionChanges: TransactionChanges,
- *   without?: string[],
- * ): Promise<void>;
- * ```
- *
- * This is intended for specialist applications that require the ability to
- * update clients of a TinyBasePartyKitServer in their own custom ways.
- *
- * The function is asynchronous, so you should use the `await` keyword or handle
- * its completion as a promise.
- * @param server A reference to the TinyBasePartyKitServer object.
- * @param transactionChanges The Store changes to broadcast to the server's
- * clients.
- * @param without An optional array of client connection Ids to exclude from the
- * broadcast.
- * @category Connection
- * @since v4.5.1
- */
-export function broadcastTransactionChanges<Schemas extends OptionalSchemas>(
-  server: TinyBasePartyKitServer,
-  transactionChanges: TransactionChanges<Schemas>,
-  without?: string[],
-): Promise<void>;