{"id":16595,"library":"acebase-client","title":"AceBase Realtime Database Client","description":"AceBase Client is a JavaScript/TypeScript library designed to connect to and interact with a remote AceBase realtime database server. It provides functionalities for reading, writing, querying, and subscribing to real-time data changes within an AceBase database. The current stable version is 1.22.3, with an active release cadence that frequently addresses bug fixes and introduces minor features, often preceded by release candidates. This client acts as the bridge for applications to leverage AceBase's NoSQL, schemaless, object-tree data model, supporting complex queries and robust authentication mechanisms. Its primary differentiator is its tight integration with the AceBase server ecosystem, enabling efficient data synchronization and real-time event handling for connected applications, both in Node.js and browser environments.","status":"active","version":"1.22.3","language":"javascript","source_language":"en","source_url":"https://github.com/appy-one/acebase-client","tags":["javascript","database","db","json","binary","object","tree","nosql","embedded","typescript"],"install":[{"cmd":"npm install acebase-client","lang":"bash","label":"npm"},{"cmd":"yarn add acebase-client","lang":"bash","label":"yarn"},{"cmd":"pnpm add acebase-client","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Provides core AceBase logic and data manipulation utilities, essential for client operations.","package":"acebase-core","optional":false}],"imports":[{"note":"The primary class for connecting to an AceBase server. Works with both ESM and CJS environments, but ensure correct import syntax.","wrong":"const AceBaseClient = require('acebase-client'); // CommonJS import in an ESM project, or vice-versa.\nimport AceBaseClient from 'acebase-client'; // Incorrect default import, it's a named export.","symbol":"AceBaseClient","correct":"import { AceBaseClient } from 'acebase-client';"},{"note":"Exported since v1.22.1, this class allows for specific error handling of API request failures.","wrong":"const { AceBaseRequestError } = require('acebase-client'); // Works, but ESM import is preferred in TypeScript/modern JS.","symbol":"AceBaseRequestError","correct":"import { AceBaseRequestError } from 'acebase-client';"},{"note":"For direct browser use without a bundler, include the `browser.min.js` script. The `AceBaseClient` class will be exposed globally.","wrong":"import { AceBaseClient } from 'acebase-client'; // Will fail in browser environments without a module bundler.","symbol":"Browser Global (AceBaseClient)","correct":"<script type=\"text/javascript\" src=\"https://cdn.jsdelivr.net/npm/acebase-client@latest/dist/browser.min.js\"></script>\n// AceBaseClient is then available globally"}],"quickstart":{"code":"import { AceBaseClient } from 'acebase-client';\n\n// Replace with your actual AceBase server details\nconst host = process.env.ACEBASE_HOST ?? 'localhost';\nconst port = parseInt(process.env.ACEBASE_PORT ?? '5757', 10);\nconst dbname = process.env.ACEBASE_DBNAME ?? 'mydb';\nconst https = (process.env.ACEBASE_HTTPS ?? 'false') === 'true';\n\nconst db = new AceBaseClient({ host, port, dbname, https });\n\ndb.ready(async () => {\n    console.log('Connected to AceBase server.');\n\n    // 1. Log an event to the database\n    const logRef = db.ref('log');\n    await logRef.push({\n        user: 'guest_user',\n        type: 'quickstart_connect',\n        datetime: new Date().toISOString()\n    });\n    console.log('Logged connection event.');\n\n    // 2. Write and read user data\n    const userId = 'quickstart_user';\n    const userRef = db.ref(`users/${userId}`);\n    await userRef.set({ name: 'Jane Doe', email: 'jane@example.com', createdAt: new Date().toISOString() });\n    console.log(`User '${userId}' created.`);\n\n    const snapshot = await userRef.get();\n    console.log(`Read user data: ${JSON.stringify(snapshot.val())}`);\n\n    // 3. Subscribe to real-time changes on a 'todo' list\n    const todoRef = userRef.child('todo');\n    todoRef.on('child_added', (snapshot) => {\n        const item = snapshot.val();\n        console.log(`[REALTIME] Todo item added: ${item.text} (ID: ${snapshot.key})`);\n    });\n\n    // Add an item after a short delay to trigger the subscription\n    setTimeout(async () => {\n        await todoRef.push({ text: 'Learn AceBase', completed: false });\n        console.log('Added a todo item.');\n    }, 1000);\n\n    // Optional: Sign in if authentication is enabled on the server\n    // try {\n    //     const authResult = await db.auth.signInWithEmail('admin@example.com', 'yourpassword');\n    //     console.log(`Signed in as ${authResult.user.email}`);\n    // } catch (error) {\n    //     console.warn('Authentication failed (if server requires it):', error.message);\n    // }\n\n});\n\ndb.on('error', (error) => {\n    console.error('AceBase Client Error:', error);\n});","lang":"typescript","description":"Demonstrates connecting to an AceBase server, logging an event, performing a read/write operation, and setting up a real-time subscription for data changes. Includes environment variable usage for configuration."},"warnings":[{"fix":"Review usage of `db.ref().sync()` and adapt code to the new return format. Consult the AceBase documentation for specific details on the updated structure.","message":"The return format for `uncached sync()` operations changed in v1.22.0. Applications using `sync()` without caching might need adjustments.","severity":"breaking","affected_versions":">=1.22.0"},{"fix":"Update error handling code to specifically check for `isServerError` in addition to `isNetworkError` where applicable, or use `instanceof AceBaseRequestError` for broader catching.","message":"The `isNetworkError` getter was split into `isNetworkError` and `isServerError` in v1.22.2. If you relied on `isNetworkError` to catch all server-related errors, your error handling logic might need to be updated.","severity":"breaking","affected_versions":">=1.22.2"},{"fix":"Upgrade to v1.8.0 or newer to use `db.auth.setAccessToken(accessToken)` for seamless sign-in on reconnection. For older versions, implement custom logic to re-authenticate manually upon `connect` event.","message":"The `setAccessToken` method for automatic sign-in with a stored token was introduced in v1.8.0. For older client versions, handling offline sign-in requires different manual logic or reconnect strategies.","severity":"gotcha","affected_versions":"<1.8.0"},{"fix":"For browser-only applications without bundlers, use `<script type=\"text/javascript\" src=\"https://cdn.jsdelivr.net/npm/acebase-client@latest/dist/browser.min.js\"></script>`. For modern web development, use a module bundler like Webpack or Rollup to utilize `import` statements.","message":"When using AceBase Client directly in the browser without a module bundler, you must include the `browser.min.js` script via a `<script>` tag. Standard `import` or `require` syntax will not work in this context.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"For browsers, ensure `<script src=\"...\">` is loaded. For Node.js, verify `import { AceBaseClient } from 'acebase-client';` for ESM or `const { AceBaseClient } = require('acebase-client');` for CommonJS is used correctly based on your project's module type.","cause":"Attempting to use `AceBaseClient` in a browser environment without loading the `browser.min.js` script, or using ESM import in a CommonJS-only context (or vice versa) without proper transpilation.","error":"ReferenceError: AceBaseClient is not defined"},{"fix":"Verify that the AceBase server is running, listening on the specified host and port, and that no firewall is blocking the connection. Double-check `host`, `port`, and `https` options in the `AceBaseClient` constructor.","cause":"The AceBase server is not running, is inaccessible, or the provided host and port configuration is incorrect, preventing the client from establishing a connection.","error":"Error: connect ECONNREFUSED <host>:<port>"},{"fix":"Ensure correct credentials are provided to `db.auth.signIn`, `signInWithEmail`, or `signInWithToken`. If using tokens, ensure they are still valid. Check server-side authentication rules.","cause":"The client attempted to access a protected resource without valid authentication credentials, or the provided credentials (username/password, email/password, or access token) are incorrect or expired.","error":"Error: Access denied (401) or Error: Authentication failed (403)"}],"ecosystem":"npm"}