This is the official Fluree client SDK for TypeScript/JavaScript. It is a wrapper around the Fluree API, providing a more convenient way to interact with Fluree v3 databases.
Tested against the following
fluree/server
Docker Hub images:
fluree/server:0d411e4b2c4f1269dc538c65072fd479db9e2e64
: Current stable version / March 12 2025fluree/server:7ca39f4b5c5c31602b44873cc19d313d33a99382
: January 22 2025fluree/server:1ffefe432db25a3c8df29f1e01e79ab02abc86cf
: December 5 2024fluree/server:5839ffe273062b8da972b120deb54dd62e7c3d1f
: November 5 2024fluree/server:c452631c50b8f8e595d486240dab503bbaad6033
: October 30 2024
npm install @fluree/fluree-client
const { FlureeClient } = require('@fluree/fluree-client');
// Create a new FlureeClient instance
const client = await new FlureeClient({
host: 'localhost',
port: 8090,
});
// Perform a query
const result = await client
.query({
from: 'my/ledger',
select: { '?s': ['*'] },
where: {
'@id': '?s',
},
})
.send();
import { FlureeClient } from '@fluree/fluree-client';
// Create a new FlureeClient instance
const client = await new FlureeClient({
host: 'localhost',
port: 8090,
});
// Perform a query
const result = await client
.query({
from: 'my/ledger',
select: { '?s': ['*'] },
where: {
'@id': '?s',
},
})
.send();
The FlureeClient
constructor takes an optional config
object with the following properties:
{
isFlureeHosted, // [boolean] If true, the client will use the Fluree hosted service
apiKey, // [string] The API key to use for the Fluree hosted service
ledger, // [string] The ledger/db name on the Fluree instance
// Do not set "host" and "port" if "isFlureeHosted" is true
host, // [string] The host where your instance is running (e.g. localhost)
port, // [number] The port where your instance is running (e.g. 58090)
create, // [boolean] If true, the ledger will be created if it does not exist
privateKey, // [string] The private key to use for signing messages
signMessages, // [boolean] If true, messages will be signed by default
defaultContext, // [object] The default context to use for queries/txns
}
For example:
const client = new FlureeClient({
ledger: 'fluree-client/client',
host: 'localhost',
port: 58090,
create: true,
privateKey: 'XXX...XXX',
signMessages: true,
defaultContext: {
schema: 'http://schema.org/',
name: 'schema:name',
// ...
},
});
You can also update the configuration of an existing client by using the configure()
method:
const client = new FlureeClient({
isFlureeHosted: true,
apiKey: process.env.FLUREE_API_KEY,
ledger: 'fluree-jld/387028092978173',
});
client.configure({
ledger: 'fluree-jld/387028092978174',
});
Note: As of version 1.2.0, the
FlureeClient
class does not require configuring a value onledger
, nor does it require that theconnect()
method be called before generating and sending queries/transactions.If you wish to call
connect()
, it is an option that simply allows you to validate the existence of a ledger, or to easily create it if using thecreate: true
configuration option.
- connect()
- create()
- query()
- transact()
- delete()
- upsert()
- history()
- generateKeyPair()
- setKey()
- getPrivateKey()
- getPublicKey()
- getDid()
- setContext()
- addToContext()
- getContext()
It is optional but not required to call connect()
after creating a new FlureeClient
instance. If used, this will test the connection and (if config.create === true
) create the ledger if it does not exist.
It will also throw an error if the connection fails (e.g. invalid host, ledger does not exist, etc.)
const connectedClient = await new FlureeClient({
isFlureeHosted: true,
apiKey: process.env.FLUREE_API_KEY,
ledger: 'fluree-jld/387028092978173',
}).connect();
You can optionally provide a ledger
param to the connect()
method to override the ledger in the client configuration (or to set it, if it had not previously been provided):
const connectedClient = await new FlureeClient({
isFlureeHosted: true,
apiKey: process.env.FLUREE_API_KEY,
}).connect('fluree-jld/387028092978173');
The create()
method can be used to create a new ledger on the Fluree instance. This will throw an error if the ledger already exists.
The returned FlureeClient will be configured to use the new ledger.
const client = new FlureeClient({
host: 'localhost',
port: 8080,
ledger: 'fluree-client/client',
});
const createdClient = await client.create('new-ledger');
Optionally, you can provide a particular "initial commit" transaction to be used when creating the ledger:
const client = new FlureeClient({
host: 'localhost',
port: 8080,
});
const createdClient = await client.create('new-ledger', {
insert: { '@id': 'freddy', name: 'Freddy' },
});
The query()
method creates a new QueryInstance
for querying the Fluree database. The QueryInstance
can be used & re-used to build, sign, and send queries to the Fluree instance.
See the QueryInstance section for more information.
const client = await new FlureeClient({
isFlureeHosted: true,
apiKey: process.env.FLUREE_API_KEY,
});
const queryInstance = client.query({
from: 'test/query',
select: { freddy: ['*'] },
});
const response = await queryInstance.send();
The transact()
method creates a new TransactionInstance
for transacting with the Fluree database. The TransactionInstance
can be used & re-used to build, sign, and send transactions to the Fluree instance.
See the TransactionInstance section for more information.
const client = await new FlureeClient({
isFlureeHosted: true,
apiKey: process.env.FLUREE_API_KEY,
});
const transactionInstance = client.transact({
ledger: 'test/transaction',
insert: { '@id': 'freddy', name: 'Freddy' },
});
const response = await transactionInstance.send();
The delete()
method creates a new TransactionInstance
for deleting subjects by @id
in the Fluree database. The TransactionInstance
can then be used to sign and send delete transactions to the Fluree instance.
If your flureeClient
instance does not have a ledger
configured, or, if you would like to specify a different ledger for the delete transaction, you can provide a ledger
parameter to the delete()
method.
Delete is not an API endpoint in Fluree. This method helps to transform a single or list of subject identifiers (@id) into a where/delete transaction that deletes the subject(s) and all facts about the subject(s).
// Existing data:
// [
// { "@id": "freddy", "name": "Freddy" },
// { "@id": "alice", "name": "Alice" }
// ]
const txnInstance = client.delete(['freddy']);
const txnObject = txnInstance.getTransaction();
console.log(txnObject);
// {
// where: [{ '@id': 'freddy', ?p0: '?o0' }],
// delete: [{ '@id': 'freddy', ?p0: '?o0' }],
// ledger: ...
// }
const response = await txnInstance.send();
// New data state after txn:
// [
// { "@id": "alice", "name": "Alice" }
// ]
The upsert()
method creates a new TransactionInstance
for upserting with the Fluree database. The TransactionInstance
can be used & re-used to build, sign, and send upsert transactions to the Fluree instance.
If your flureeClient
instance does not have a ledger
configured, or, if you would like to specify a different ledger for the upsert transaction, you can provide a ledger
parameter to the upsert()
method.
Upsert is not an API endpoint in Fluree. This method helps to transform an upsert transaction into an insert/where/delete transaction.
Upsert assumes that the facts provided in the transaction should be treated as the true & accurate state of the data after the transaction is processed.
This means that facts in your transaction should be inserted (if new) and should replace existing facts (if they exist on those subjects & properties).
// Existing data:
// [
// { "@id": "freddy", "name": "Freddy" },
// { "@id": "alice", "name": "Alice" }
// ]
const txnInstance = client.upsert([
{ '@id': 'freddy', name: 'Freddy the Yeti' },
{ '@id': 'alice', age: 25 },
]);
const txnObject = txnInstance.getTransaction();
console.log(txnObject);
// {
// where: [ { '@id': 'freddy', name: '?1' }, { '@id': 'alice', age: '?2' } ],
// delete: [ { '@id': 'freddy', name: '?1' }, { '@id': 'alice', age: '?2' } ],
// insert: [
// { '@id': 'freddy', name: 'Freddy the Yeti' },
// { '@id': 'alice', age: 25 }
// ],
// ledger: ...
// }
const response = await txnInstance.send();
// New data state after txn:
// [
// { "@id": "freddy", "name": "Freddy the Yeti" },
// { "@id": "alice", "name": "Alice", "age": 25 }
// ]
// Note that if this had been an "insert" freddy would now have two names.
// Note also that if this had been handled by deleting/insert, alice might have lost her name.
The history()
method creates a new HistoryQueryInstance
for querying the history of the Fluree database. The HistoryQueryInstance
can be used & re-used to build, sign, and send history queries to the Fluree instance.
See the HistoryQueryInstance section for more information.
const client = await new FlureeClient({
isFlureeHosted: true,
apiKey: process.env.FLUREE_API_KEY,
});
const historyQuery = client.history({
from: 'test/history',
'commit-details': true,
t: { at: 'latest' },
});
const response = await historyQuery.send();
Automatically generates a new key pair and adds it to the FlureeClient instance. The public key and DID will be derived from the private key and added to the FlureeClient instance.
const client = new FlureeClient({
isFlureeHosted: true,
apiKey: process.env.FLUREE_API_KEY,
});
client.generateKeyPair();
const privateKey = client.getPrivateKey();
This adds a private key to the FlureeClient instance. This key will be used to sign messages by default when using the sign() method on a query or transaction.
The public key and DID will be derived from the private key and added to the FlureeClient instance.
const client = await new FlureeClient({
isFlureeHosted: true,
apiKey: process.env.FLUREE_API_KEY,
}).connect();
const privateKey = 'XXX...XXX';
client.setKey(privateKey);
const publicKey = client.getPublicKey();
const did = client.getDid();
The getPrivateKey()
method returns the private key of the FlureeClient instance (if one has been set).
NOTE: Be careful with this method. It is not recommended to log or expose private keys.
const client = new FlureeClient({
isFlureeHosted: true,
apiKey: process.env.FLUREE_API_KEY,
});
client.generateKeyPair();
const privateKey = client.getPrivateKey();
The getPublicKey()
method returns the public key of the FlureeClient instance (if one has been set).
const client = new FlureeClient({
isFlureeHosted: true,
apiKey: process.env.FLUREE_API_KEY,
});
client.generateKeyPair();
const publicKey = client.getPublicKey();
The getDid()
method returns the DID of the FlureeClient instance (if one has been set).
const client = new FlureeClient({
isFlureeHosted: true,
apiKey: process.env.FLUREE_API_KEY,
});
client.generateKeyPair();
const did = client.getDid();
The setContext()
method sets the default context for the FlureeClient instance. This context will be used for all queries and transactions by default.
Unlike addToContext()
, which merges new context elements into any existing context for the client, this method will replace the existing default context entirely.
const client = new FlureeClient({
isFlureeHosted: true,
apiKey: process.env.FLUREE_API_KEY,
defaultContext: { schema: 'http://schema.org/' },
});
client.setContext({ ex: 'http://example.org/' });
// client.getContext() === { "ex": "http://example.org/" }
The addToContext()
method adds to the default context for the FlureeClient instance. This context will be used for all queries and transactions by default.
If a default context already exists, the new context will be merged with the existing context.
const client = new FlureeClient({
isFlureeHosted: true,
apiKey: process.env.FLUREE_API_KEY,
defaultContext: { schema: 'http://schema.org/' },
});
client.addToContext({ ex: 'http://example.org/' });
// client.getContext() === {
// "schema": "http://schema.org/",
// "ex": "http://example.org/"
// }
The getContext()
method returns the default context for the FlureeClient instance (if one has been set).
const client = new FlureeClient({
isFlureeHosted: true,
apiKey: process.env.FLUREE_API_KEY,
defaultContext: { schema: 'http://schema.org/' },
});
const context = client.getContext();
// context === { "schema": "http://schema.org/" }
The QueryInstance
class is used to build, sign, and send queries to the Fluree instance.
const client = await new FlureeClient({
isFlureeHosted: true,
apiKey: process.env.FLUREE_API_KEY,
}).connect();
const queryInstance = client.query({
from: 'test/query',
select: { freddy: ['*'] },
});
const signedQueryInstance = queryInstance.sign('XXX...XXX');
const response = await signedQueryInstance.send();
Additional Methods:
The send()
method sends the query to the Fluree instance and returns the response.
const client = await new FlureeClient({
isFlureeHosted: true,
apiKey: process.env.FLUREE_API_KEY,
});
const queryInstance = client.query({
from: 'test/query',
select: { freddy: ['*'] },
});
const response = await queryInstance.send();
The sign()
method signs the query with the private key of the FlureeClient instance. If no private key has been set, or if no privateKey parameter is passed to sign()
, it will throw an error.
const client = await new FlureeClient({
isFlureeHosted: true,
apiKey: process.env.FLUREE_API_KEY,
});
let signedQueryInstance = client
.query({
from: 'test/query',
select: { freddy: ['*'] },
})
.sign('XXX...XXX');
// or
client.generateKeyPair();
signedQueryInstance = client
.query({
from: 'test/query',
select: { freddy: ['*'] },
})
.sign();
const response = await signedQueryInstance.send();
The getQuery()
method returns the query object of the QueryInstance.
const client = await new FlureeClient({
isFlureeHosted: true,
apiKey: process.env.FLUREE_API_KEY,
defaultContext: { ex: 'http://example.org/' },
});
const queryInstance = client.query({
from: 'test/query',
select: { 'ex:freddy': ['*'] },
});
const query = queryInstance.getQuery();
console.log(query);
// {
// "@context": { "ex": "http://example.org/" },
// from: 'test/query',
// select: { "ex:freddy": ['*'] }
// }
The getSignedQuery()
method returns the signed query of the QueryInstance in the form of a JWS string.
const client = await new FlureeClient({
isFlureeHosted: true,
apiKey: process.env.FLUREE_API_KEY,
});
client.generateKeyPair();
const queryInstance = client.query({
from: 'fluree-client/client',
select: { freddy: ['*'] },
});
const signedQueryInstance = queryInstance.sign();
const signedQuery = signedQueryInstance.getSignedQuery();
console.log(signedQuery);
// eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzZWxlY3QiOnsiZnJlZGR5IjpbIioiXX0sImZyb20iOiJmbHVyZWUtY2xpZW50L2NsaWVudCJ9.QNTXpZCQXsbO9zoOtMHT4yH-OqAaNq8ezhV5k7C_BuI
The TransactionInstance
class is used to build, sign, and send transactions to the Fluree instance.
const client = await new FlureeClient({
isFlureeHosted: true,
apiKey: process.env.FLUREE_API_KEY,
});
const transaction = client.transact({
ledger: 'fluree-client/client',
insert: { '@id': 'freddy', name: 'Freddy' },
});
const signedTransaction = transaction.sign('XXX...XXX');
const response = await signedTransaction.send();
Additional Methods:
The send()
method sends the transaction to the Fluree instance and returns the response.
const client = await new FlureeClient({
isFlureeHosted: true,
apiKey: process.env.FLUREE_API_KEY,
});
const transaction = client.transact({
ledger: 'fluree-client/client',
insert: { '@id': 'freddy', name: 'Freddy' },
});
const response = await transaction.send();
The sign()
method signs the transaction with the private key of the FlureeClient instance. If no private key has been set, or if no privateKey parameter is passed to sign()
, it will throw an error.
const client = await new FlureeClient({
isFlureeHosted: true,
apiKey: process.env.FLUREE_API_KEY,
});
let signedTransaction = client
.transact({
ledger: 'fluree-client/client',
insert: { '@id': 'freddy', name: 'Freddy' },
})
.sign('XXX...XXX');
// or
client.generateKeyPair();
signedTransaction = client
.transact({
ledger: 'fluree-client/client',
insert: { '@id': 'freddy', name: 'Freddy' },
})
.sign();
const response = await signedTransaction.send();
The getTransaction()
method returns the transaction object of the TransactionInstance.
const client = await new FlureeClient({
isFlureeHosted: true,
apiKey: process.env.FLUREE_API_KEY,
});
const transaction = client.transact({
ledger: 'fluree-client/client',
insert: { '@id': 'freddy', name: 'Freddy' },
});
const txn = transaction.getTransaction();
console.log(txn);
// {
// ledger: 'fluree-client/client',
// insert: { '@id': 'freddy', name: 'Freddy' }
// }
The getSignedTransaction()
method returns the signed transaction of the TransactionInstance in the form of a JWS string.
const client = await new FlureeClient({
isFlureeHosted: true,
apiKey: process.env.FLUREE_API_KEY,
});
client.generateKeyPair();
const transaction = client.transact({
ledger: 'fluree-client/client',
insert: { '@id': 'freddy', name: 'Freddy' },
});
const signedTransaction = transaction.sign();
const signedTxn = signedTransaction.getSignedTransaction();
console.log(signedTxn);
// eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpbnNlcnQiOnsiQGlkIjoiZnJlZGR5IiwibmFtZSI6IkZyZWRkeSJ9LCJsZWRnZXIiOiJmbHVyZWUtY2xpZW50L2NsaWVudCJ9.SNHjlNricJbATF06mbrvnqunfV7l2gZHyvj7zYFTby0
The HistoryQueryInstance
class is used to build, sign, and send history queries to the Fluree instance.
const client = await new FlureeClient({
isFlureeHosted: true,
apiKey: process.env.FLUREE_API_KEY,
});
const historyQuery = client.history({
from: 'test/history',
'commit-details': true,
t: { at: 'latest' },
});
const response = await historyQuery.send();
The send()
method sends the history query to the Fluree instance and returns the response.
const client = await new FlureeClient({
isFlureeHosted: true,
apiKey: process.env.FLUREE_API_KEY,
});
const historyQuery = client.history({
from: 'test/history',
'commit-details': true,
t: { at: 'latest' },
});
const response = await historyQuery.send();
Before running tests, you'll need a .env.local
file in the root of the project.
This file needs to contain the following:
TEST_NEXUS_LEDGER="fluree-jld/387028092978318"
TEST_API_KEY="_DPu2OWxmJ-zRwnzNr8uL...5mfV1OsfOXcRmb35t02rp1gMxxSw"
In the root of the project, run:
yarn test
The repository includes complete example projects demonstrating usage in both Node.js and browser environments.
# Navigate to the Node.js example directory
cd examples/nodejs-example
# Install dependencies (including local fluree-client)
npm install
# Run the example
npm start
# Navigate to the browser example directory
cd examples/browser-example
# Install dependencies (including local fluree-client)
npm install
# Start the development server
npm start
This will open your default browser to the example page. Click the "Run Query" button to execute the example operations.