Fliplet.DataSources

`Fliplet.DataSources`

Fliplet.DataSources connects app code to data sources. The references below describe supported arguments, result shapes, errors and the differences between online operations, native storage and source management.

Before you start

Load the fliplet-datasources library in your app and create a data source in Studio. Configure access rules for the intended app users before exposing private data. Calls use the current app/page context and identity; a connection does not supply an independent login.

Connection and network methods return Promises. Subscription registration and cursor navigation return synchronous handles; their references identify which calls need await. Use the plural namespace Fliplet.DataSources.

Read records

This example needs a source named Directory with Name and Department columns and permission to query it. It uses an online connection and handles failed requests.

async function readDirectory() {
  try {
    const connection = await Fliplet.DataSources.connectByName('Directory', {
      offline: false
    });
    const entries = await connection.find({
      where: { Department: 'Operations' },
      attributes: ['Name', 'Department'],
      order: [['data.Name', 'ASC']],
      limit: 25
    }, { cache: false });
    return entries.map(entry => ({ id: entry.id, name: entry.data.Name }));
  } catch (error) {
    console.error('Directory query failed', error);
    throw error;
  }
}

The default read result is an array of entries. Each entry has metadata such as id, createdAt and updatedAt, with column values under data:

{
  "id": 101,
  "data": { "Name": "Ada Patel", "Department": "Operations" },
  "createdAt": "2026-01-10T09:00:00.000Z",
  "updatedAt": "2026-01-10T09:00:00.000Z"
}

A query’s where filters column values under data; entry metadata filters use top-level query parameters. Pagination, aggregation and request options can change the result shape. See reading data before combining them.

Task	Reference and methods
Read, filter and paginate	Reading data: `find`, `query`, `findOne`, `findById`, `findWithCursor`, cursor methods, `getIndex`, `getIndexes` and aggregation
Query operators	Query operators: JSON-safe filters and separate server rule lookup semantics
Related records	Joins: named joins, reductions and pagination limits
Session-bound filters	Views: definitions, requested views and security boundaries
Write records	Writing data: `insert`, `update`, `removeById`, query writes, `append`, `replaceWith` and `commit`
Attach files or import	File attachments: attachment inputs, limits and `import` capability boundaries
Listen for changes	Subscriptions: `subscribe` and subscription handle methods
Native local storage	Offline database: `Database`, handles and collections
Manage source settings	Managing data sources: `get`, `getById`, `create`, namespace `update`, `delete` and source roles
Authenticate app users	App authentication: `sendValidation` and `validate`
Secure and verify access	Security entry, rule reference, policy examples and preview testing
Server hooks	Data source hooks

Connect to a source

Fliplet.DataSources.connect(id, connectionOptions?) and Fliplet.DataSources.connectByName(name, connectionOptions?) return Promise<Connection>. The options-object overload connect({ name, offline }) also selects a named source.

Argument	Type and behavior
`id`	Required source identifier for the ID form. A missing/falsy identifier rejects.
`name`	Required source name for the named form. Name lookup uses the current request context; it does not grant cross-app access.
`connectionOptions.offline`	Optional Boolean. `false` forces online operations. When omitted, native apps can use bundled storage if the Database API is available. `true` does not enable native storage in a browser.

const online = await Fliplet.DataSources.connectByName('Directory', { offline: false });
const byId = await Fliplet.DataSources.connect(123, { offline: false });

The SDK may reuse a connection for the same identifier and offline setting. Connecting establishes a handle; it does not prove a successful server query or authorized access. Native bundle loading is lazy and failed local loading can cause later reads to use the server. There is no public connection close, disconnect or destroy method. Unsubscribe each listener when its owner is disposed.

Security and verification

Query reads and record reads evaluate different requirement targets. Object update requirements inspect stored rows, not proposed values. Field restrictions vary across single and bulk writes. Views, projections and client hooks do not replace server access rules.

For authorization tests, use an online connection, the intended app identity and confirmed preview enforcement. Check denied operations, returned data and persisted effects. Administrative calls, local results and preview with enforcement disabled cannot establish app-user authorization. A resolved write may be queued or pending; use the write reference’s persistence checks.

SDK helper boundaries

These exposed helpers have narrower purposes than record CRUD. They are not additional authorization or synchronization APIs.

Helper	Signature and outcome
Temporary IDs	`isTempId(id)` returns a Boolean synchronously; true for strings starting with `temp_`. A false result alone does not prove server persistence.
Connection lookup	`clearActiveConnections()` returns `undefined` and resets the reuse lookup. It does not unsubscribe existing listeners.
Client hook registration	`bindHooks(id, hooks)` registers an object synchronously and rejects duplicate bindings or nonobject inputs by throwing. These run in the client, separately from server hooks.
Client hook lookup	`hasHook(id)` returns a Boolean synchronously.
Client hook application	`applyHooks(id, method, entries)` invokes the bound callback. Array input returns `Promise.all` of callback results; a single item returns the callback’s value/Promise. Without a callback it resolves `undefined`.
Mapped-row convenience	`fetchWithOptions(options)` returns a Promise. See mapped rows for its different result shape and options.

Underscore-prefixed tracking/reconciliation helpers and core queue-storage helpers are internal implementation surfaces. Use the documented insert/update outcomes rather than manipulating the queue. Native applyDiff belongs to the update pipeline, not a custom app synchronization recipe.