@romedb/client 0.0.0-stage → 0.2.14

package/LICENSE.md

@@ -0,0 +1,20 @@
+MIT License
+
+Copyright 2024 the Turso authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -1,3 +1,141 @@
-# Temporary Holding Version
+# RomeDB client
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+`@romedb/client` connects to a RomeDB database by URL, behind `romedb serve`, `romedb
+serve --directory` or RomeDB Cloud. It runs in Node.js, Cloudflare Workers, browsers
+and any other runtime with `fetch`.
+
+The package is about 30 KB to download, has no dependencies and has no native addon. It holds the
+same code as `@romedb/node/client` and `@romedb/node/values`, byte for byte, at the same
+version. To open a local database file, use [`@romedb/node`](https://www.npmjs.com/package/@romedb/node).
+
+## Install
+
+```sh
+npm install @romedb/client
+```
+
+## A first request
+
+```js
+import { connect, Float64 } from '@romedb/client';
+
+const rql = await connect({ url: process.env.ROMEDB_URL, token: process.env.ROMEDB_TOKEN });
+const snapshot = await rql.read([{ sql: 'SELECT * FROM posts LIMIT 20' }]);
+await rql.writeAtomic([
+  { sql: 'UPDATE posts:p1 MERGE {score: $score}', params: { $score: new Float64(1) } },
+]);
+await rql.close();
+```
+
+`require('@romedb/client')` works the same way in Node.js.
+
+## In a Cloudflare Worker
+
+Workers need no `nodejs_compat`.
+
+```js
+import { connect } from '@romedb/client';
+
+export default {
+  async fetch(request, env) {
+    const rql = await connect({ url: env.ROMEDB_URL, token: env.ROMEDB_TOKEN });
+    const { results } = await rql.read([{ sql: "SELECT title FROM posts WHERE array::contains(tags, 'news')" }]);
+    return Response.json({ posts: results[0].rows.length });
+  },
+};
+```
+
+## Value types only
+
+`@romedb/client/values` exports `Float64`, `Record`, `Vector`, `encodeValue` and
+`decodeValue`. Use it for code that never connects, such as a browser bundle.
+
+## Using it with `@romedb/node`
+
+Each package has its own value classes. A `Record` from `@romedb/client` is not an
+instance of the `Record` from `@romedb/node/client`, so a client refuses a value from
+the other package. Use one package for all your client code, or convert values at the
+boundary.
+
+## Saved requests
+
+`saveRequest` and `loadRequest` keep a prepared write in a private file, so a write with
+an unknown outcome can be recovered. They need Node.js file access and reject in other
+runtimes. There, store the `PreparedWrite` object yourself, for example in a Durable
+Object.
+
+## URLs and tokens
+
+A local service URL is `http://127.0.0.1:4321`. A Cloud URL names the organization
+and database by stable UUIDs, and a dashboard URL that ends in `/query` also works.
+Use HTTPS for every host that is not local.
+
+`romedb://` is another name for `https://`. The client replaces the scheme and applies
+the same rules, so `romedb://cloud.romedb.com/v1/organizations/{org}/databases/{db}`
+and the `https://` form are the same database. Requests use `redirect: 'manual'`, and
+any redirect fails with `RDB_PROTOCOL`, so the token never goes to another URL. Pass
+the bearer token separately. The client refuses a token in the URL.
+
+## Cloud URLs
+
+For a Cloud URL, `connect()` returns without a network round trip. The database ID
+comes from the URL, and the Cloud capabilities are documented. Reads start from
+sequence 0 as their lower bound and update the sequence from each reply.
+
+A write needs a current sequence. If none is known yet, `writeAtomic` first fetches
+the database details, and `prepareWrite` throws `RDB_SEQUENCE_UNKNOWN` (outcome
+`not-sent`) until a read, `info()` or an explicit `afterSequence` supplies one. To
+fetch the details at connect, pass `deferInfo: false`. Other URLs always fetch the
+details at connect and refuse `deferInfo: true`.
+
+`connect()` on a Cloud URL also sends a warm request in the background and does not
+wait for it. Cloud then starts the container of the database and opens it, so a query
+a second or more later does not wait for that start. Errors of the background request
+are ignored. To skip it, pass `warm: false`.
+
+`await rql.warm()` sends the same request and returns `{ state }`. The state is
+`ready` when the database is already open, `starting` when Cloud began to open it, or
+`skipped` when Cloud declined because another database is busy. Call it when your
+application knows that a query is coming, for example when a page or a function
+starts. Local URLs refuse `warm()`.
+
+## Local directories
+
+An organization URL on a loopback host, such as a database of `romedb serve
+--directory` (`http://127.0.0.1:4321/v1/organizations/{org}/databases/{db}`), always
+fetches the details at connect. A reply with `serviceVersion: 1` is a local service.
+The client then negotiates its capabilities and uses the 64 KiB service request
+format, with no warm request. Any other reply is Cloud running locally, which keeps
+the Cloud request format. So an application can use the same organization URLs for a
+local directory and for Cloud.
+
+## Values and results
+
+Results use positional rows and keep duplicate columns. Integer results are `bigint`.
+Number results are `Float64` instances with a `.value` number. They keep their exact
+float type when you bind them again, integral floats and negative zero included.
+
+Encoded vectors and the dense float32, float64 and sparse-entry factories
+work without native code. `null` is a present field. `undefined` and array holes are
+refused, so no data disappears without an error.
+
+## Errors and timeouts
+
+Requests and responses have finite byte and row limits. Each call times out after 20
+seconds by default and accepts `signal` and `timeoutMs`. An HTTP error reply with a
+`Retry-After` header sets `ClientError.retryAfterMs`. A transport or response failure
+without a database reply keeps the underlying error as `ClientError.cause`, for
+example a `fetch failed` TypeError with `ECONNREFUSED`.
+
+`rql.sequenceKnown` is `true` once a reply has given the current sequence. `rql.cloud`
+tells a Cloud database from a local service. A write cancelled after it was sent stays
+unknown until a receipt confirms it. Cloud capabilities are marked as documented,
+because its API does not negotiate the local capability object. See the
+[service contract](https://github.com/romedb/romedb/blob/main/romedb/docs/service-protocol.md) for limits, receipt rules and
+compatibility gaps.
+
+## More
+
+The [Node.js guide](https://github.com/romedb/romedb/blob/main/romedb/bindings/node/README.md#url-client)
+has the full client reference, including saved requests, query versions and file
+exports. The client methods are the same in both packages.

package/client-internal.cjs

@@ -0,0 +1,2 @@
+'use strict';
+module.exports = {};