@instantdb/core/dist/commonjs/index.d.ts

Instant's core local abstraction

import Reactor from './Reactor.js';
import { tx, txInit, lookup, getOps, type TxChunk, type TransactionChunk } from './instatx.js';
import weakHash from './utils/weakHash.js';
import id from './utils/uuid.js';
import IndexedDBStorage from './IndexedDBStorage.js';
import WindowNetworkListener from './WindowNetworkListener.js';
import { i } from './schema.js';
import version from './version.js';
import type { PresenceOpts, PresenceResponse, PresenceSlice, RoomSchemaShape } from './presence.ts';
import type { DevtoolConfig, IDatabase, IInstantDatabase } from './coreTypes.ts';
import type { Query, QueryResponse, InstaQLResponse, PageInfoResponse, Exactly, InstantObject, InstaQLParams, InstaQLOptions, InstaQLQueryParams, InstaQLEntity, InstaQLResult, InstaQLFields } from './queryTypes.ts';
import type { AuthState, User, AuthResult, ConnectionStatus } from './clientTypes.ts';
import type { InstantQuery, InstantQueryResult, InstantSchema, InstantEntity, InstantSchemaDatabase } from './helperTypes.ts';
import type { InstantDBAttr, InstantDBAttrOnDelete, InstantDBCheckedDataType, InstantDBIdent, InstantDBInferredType } from './attrTypes.ts';
import type { AttrsDefs, CardinalityKind, DataAttrDef, EntitiesDef, EntitiesWithLinks, EntityDef, RoomsDef, InstantSchemaDef, InstantGraph, LinkAttrDef, LinkDef, LinksDef, PresenceOf, ResolveAttrs, RoomsOf, TopicsOf, ValueTypes, InstantUnknownSchema, BackwardsCompatibleSchema, UpdateParams, LinkParams, RuleParams } from './schemaTypes.ts';
import type { InstantRules } from './rulesTypes.ts';
import type { UploadFileResponse, DeleteFileResponse } from './StorageAPI.ts';
import type { ExchangeCodeForTokenParams, SendMagicCodeParams, SendMagicCodeResponse, SignInWithIdTokenParams, VerifyMagicCodeParams, VerifyResponse } from './authAPI.ts';
import { InstantAPIError, type InstantIssue } from './utils/fetch.js';
export type Config = {
    appId: string;
    websocketURI?: string;
    apiURI?: string;
    devtool?: boolean | DevtoolConfig;
    verbose?: boolean;
    queryCacheLimit?: number;
};
export type InstantConfig<S extends InstantSchemaDef<any, any, any>> = {
    appId: string;
    schema?: S;
    websocketURI?: string;
    apiURI?: string;
    devtool?: boolean | DevtoolConfig;
    verbose?: boolean;
    queryCacheLimit?: number;
};
export type ConfigWithSchema<S extends InstantGraph<any, any>> = Config & {
    schema: S;
};
export type TransactionResult = {
    status: 'synced' | 'enqueued';
    clientId: string;
};
export type PublishTopic<TopicsByKey> = <Key extends keyof TopicsByKey>(topic: Key, data: TopicsByKey[Key]) => void;
export type SubscribeTopic<PresenceShape, TopicsByKey> = <Key extends keyof TopicsByKey>(topic: Key, onEvent: (event: TopicsByKey[Key], peer: PresenceShape) => void) => () => void;
export type GetPresence<PresenceShape> = <Keys extends keyof PresenceShape>(opts: PresenceOpts<PresenceShape, Keys>) => PresenceResponse<PresenceShape, Keys>;
export type SubscribePresence<PresenceShape> = <Keys extends keyof PresenceShape>(opts: PresenceOpts<PresenceShape, Keys>, onChange: (slice: PresenceResponse<PresenceShape, Keys>) => void) => () => void;
export type RoomHandle<PresenceShape, TopicsByKey> = {
    leaveRoom: () => void;
    publishTopic: PublishTopic<TopicsByKey>;
    subscribeTopic: SubscribeTopic<PresenceShape, TopicsByKey>;
    publishPresence: (data: Partial<PresenceShape>) => void;
    getPresence: GetPresence<PresenceShape>;
    subscribePresence: SubscribePresence<PresenceShape>;
};
type AuthToken = string;
type SubscriptionState<Q, Schema, WithCardinalityInference extends boolean> = {
    error: {
        message: string;
    };
    data: undefined;
    pageInfo: undefined;
} | {
    error: undefined;
    data: QueryResponse<Q, Schema, WithCardinalityInference>;
    pageInfo: PageInfoResponse<Q>;
};
type InstaQLSubscriptionState<Schema, Q> = {
    error: {
        message: string;
    };
    data: undefined;
    pageInfo: undefined;
} | {
    error: undefined;
    data: InstaQLResponse<Schema, Q>;
    pageInfo: PageInfoResponse<Q>;
};
type LifecycleSubscriptionState<Q, Schema, WithCardinalityInference extends boolean> = SubscriptionState<Q, Schema, WithCardinalityInference> & {
    isLoading: boolean;
};
type InstaQLLifecycleState<Schema, Q> = InstaQLSubscriptionState<Schema, Q> & {
    isLoading: boolean;
};
type UnsubscribeFn = () => void;
type SignoutOpts = {
    invalidateToken?: boolean;
};
/**
 * Functions to log users in and out.
 *
 * @see https://instantdb.com/docs/auth
 */
declare class Auth {
    private db;
    constructor(db: Reactor);
    /**
     * Sends a magic code to the user's email address.
     *
     * Once you send the magic code, see {@link auth.signInWithMagicCode} to let the
     * user verify.
     *
     * @see https://instantdb.com/docs/auth
     * @example
     *  db.auth.sendMagicCode({email: "example@gmail.com"})
     *    .catch((err) => console.error(err.body?.message))
     */
    sendMagicCode: (params: SendMagicCodeParams) => Promise<SendMagicCodeResponse>;
    /**
     * Verify a magic code that was sent to the user's email address.
     *
     * @see https://instantdb.com/docs/auth
     *
     * @example
     *  db.auth.signInWithMagicCode({email: "example@gmail.com", code: "123456"})
     *       .catch((err) => console.error(err.body?.message))
     */
    signInWithMagicCode: (params: VerifyMagicCodeParams) => Promise<VerifyResponse>;
    /**
     * Sign in a user with a refresh token
     *
     * @see https://instantdb.com/docs/backend#frontend-auth-sign-in-with-token
     *
     * @example
     *   // Get the token from your backend
     *   const token = await fetch('/signin', ...);
     *   //Sign in
     *   db.auth.signInWithToken(token);
     */
    signInWithToken: (token: AuthToken) => Promise<VerifyResponse>;
    /**
     * Create an authorization url to sign in with an external provider
     *
     * @see https://instantdb.com/docs/auth
     *
     * @example
     *   // Get the authorization url from your backend
     *   const url = db.auth.createAuthorizationUrl({
     *     clientName: "google",
     *     redirectURL: window.location.href,
     *   });
     *
     *   // Put it in a sign in link
     *   <a href={url}>Log in with Google</a>
     */
    createAuthorizationURL: (params: {
        clientName: string;
        redirectURL: string;
    }) => string;
    /**
     * Sign in with the id_token from an external provider like Google
     *
     * @see https://instantdb.com/docs/auth
     * @example
     *   db.auth
     *  .signInWithIdToken({
     *    // Token from external service
     *    idToken: id_token,
     *    // The name you gave the client when you registered it with Instant
     *    clientName: "google",
     *    // The nonce, if any, that you used when you initiated the auth flow
     *    // with the external service.
     *    nonce: your_nonce
     *  })
     *  .catch((err) => console.error(err.body?.message));
     *
     */
    signInWithIdToken: (params: SignInWithIdTokenParams) => Promise<VerifyResponse>;
    /**
     * Sign in with the id_token from an external provider like Google
     *
     * @see https://instantdb.com/docs/auth
     * @example
     *   db.auth
     *  .exchangeOAuthCode({
     *    // code received in redirect from OAuth callback
     *    code: code
     *    // The PKCE code_verifier, if any, that you used when you
     *    // initiated the auth flow
     *    codeVerifier: your_code_verifier
     *  })
     *  .catch((err) => console.error(err.body?.message));
     *
     */
    exchangeOAuthCode: (params: ExchangeCodeForTokenParams) => Promise<VerifyResponse>;
    /**
     * OpenID Discovery path for use with tools like
     * expo-auth-session that use auto-discovery of
     * OAuth parameters.
     *
     * @see https://instantdb.com/docs/auth
     * @example
     *   const discovery = useAutoDiscovery(
     *     db.auth.issuerURI()
     *   );
     */
    issuerURI: () => string;
    /**
     * Sign out the current user
     */
    signOut: (opts?: SignoutOpts) => Promise<void>;
}
type FileOpts = {
    contentType?: string;
    contentDisposition?: string;
};
/**
 * Functions to manage file storage.
 */
declare class Storage {
    private db;
    constructor(db: Reactor);
    /**
     * Uploads file at the provided path.
     *
     * @see https://instantdb.com/docs/storage
     * @example
     *   const [file] = e.target.files; // result of file input
     *   const data = await db.storage.uploadFile('photos/demo.png', file);
     */
    uploadFile: (path: string, file: File | Blob, opts?: FileOpts) => Promise<UploadFileResponse>;
    /**
     * Deletes a file by path name.
     *
     * @see https://instantdb.com/docs/storage
     * @example
     *   await db.storage.delete('photos/demo.png');
     */
    delete: (pathname: string) => Promise<DeleteFileResponse>;
    /**
     * @deprecated. Use `db.storage.uploadFile` instead
     * remove in the future.
     */
    upload: (pathname: string, file: File) => Promise<boolean>;
    /**
     * @deprecated Use `db.storage.uploadFile` instead
     */
    put: (pathname: string, file: File) => Promise<boolean>;
    /**
     * @deprecated. getDownloadUrl will be removed in the future.
     * Use `useQuery` instead to query and fetch for valid urls
     *
     * db.useQuery({
     *   $files: {
     *     $: {
     *       where: {
     *         path: "moop.png"
     *       }
     *     }
     *   }
     * })
     */
    getDownloadUrl: (pathname: string) => Promise<any>;
}
declare function coerceQuery(o: any): any;
declare class InstantCoreDatabase<Schema extends InstantSchemaDef<any, any, any>> implements IInstantDatabase<Schema> {
    _reactor: Reactor<RoomsOf<Schema>>;
    auth: Auth;
    storage: Storage;
    tx: TxChunk<Schema>;
    constructor(reactor: Reactor<RoomsOf<Schema>>);
    /**
     * Use this to write data! You can create, update, delete, and link objects
     *
     * @see https://instantdb.com/docs/instaml
     *
     * @example
     *   // Create a new object in the `goals` namespace
     *   const goalId = id();
     *   db.transact(db.tx.goals[goalId].update({title: "Get fit"}))
     *
     *   // Update the title
     *   db.transact(db.tx.goals[goalId].update({title: "Get super fit"}))
     *
     *   // Delete it
     *   db.transact(db.tx.goals[goalId].delete())
     *
     *   // Or create an association:
     *   todoId = id();
     *   db.transact([
     *    db.tx.todos[todoId].update({ title: 'Go on a run' }),
     *    db.tx.goals[goalId].link({todos: todoId}),
     *  ])
     */
    transact(chunks: TransactionChunk<any, any> | TransactionChunk<any, any>[]): Promise<TransactionResult>;
    getLocalId(name: string): Promise<string>;
    /**
     * Use this to query your data!
     *
     * @see https://instantdb.com/docs/instaql
     *
     * @example
     *  // listen to all goals
     *  db.subscribeQuery({ goals: {} }, (resp) => {
     *    console.log(resp.data.goals)
     *  })
     *
     *  // goals where the title is "Get Fit"
     *  db.subscribeQuery(
     *    { goals: { $: { where: { title: "Get Fit" } } } },
     *    (resp) => {
     *      console.log(resp.data.goals)
     *    }
     *  )
     *
     *  // all goals, _alongside_ their todos
     *  db.subscribeQuery({ goals: { todos: {} } }, (resp) => {
     *    console.log(resp.data.goals)
     *  });
     */
    subscribeQuery<Q extends InstaQLParams<Schema>>(query: Q, cb: (resp: InstaQLSubscriptionState<Schema, Q>) => void, opts?: InstaQLOptions): () => void;
    /**
     * Listen for the logged in state. This is useful
     * for deciding when to show a login screen.
     *
     * @see https://instantdb.com/docs/auth
     * @example
     *   const unsub = db.subscribeAuth((auth) => {
     *     if (auth.user) {
     *     console.log('logged in as', auth.user.email)
     *    } else {
     *      console.log('logged out')
     *    }
     *  })
     */
    subscribeAuth(cb: (auth: AuthResult) => void): UnsubscribeFn;
    /**
     * One time query for the logged in state. This is useful
     * for scenarios where you want to know the current auth
     * state without subscribing to changes.
     *
     * @see https://instantdb.com/docs/auth
     * @example
     *   const user = await db.getAuth();
     *   console.log('logged in as', user.email)
     */
    getAuth(): Promise<User | null>;
    /**
     * Listen for connection status changes to Instant. This is useful
     * for building things like connectivity indicators
     *
     * @see https://www.instantdb.com/docs/patterns#connection-status
     * @example
     *   const unsub = db.subscribeConnectionStatus((status) => {
     *     const connectionState =
     *       status === 'connecting' || status === 'opened'
     *         ? 'authenticating'
     *       : status === 'authenticated'
     *         ? 'connected'
     *       : status === 'closed'
     *         ? 'closed'
     *       : status === 'errored'
     *         ? 'errored'
     *       : 'unexpected state';
     *
     *     console.log('Connection status:', connectionState);
     *   });
     */
    subscribeConnectionStatus(cb: (status: ConnectionStatus) => void): UnsubscribeFn;
    /**
     * Join a room to publish and subscribe to topics and presence.
     *
     * @see https://instantdb.com/docs/presence-and-topics
     * @example
     * // init
     * const db = init();
     * const room = db.joinRoom(roomType, roomId);
     * // usage
     * const unsubscribeTopic = room.subscribeTopic("foo", console.log);
     * const unsubscribePresence = room.subscribePresence({}, console.log);
     * room.publishTopic("hello", { message: "hello world!" });
     * room.publishPresence({ name: "joe" });
     * // later
     * unsubscribePresence();
     * unsubscribeTopic();
     * room.leaveRoom();
     */
    joinRoom<RoomType extends keyof RoomsOf<Schema>>(roomType?: RoomType, roomId?: string, opts?: {
        initialPresence?: Partial<PresenceOf<Schema, RoomType>>;
    }): RoomHandle<PresenceOf<Schema, RoomType>, TopicsOf<Schema, RoomType>>;
    shutdown(): void;
    /**
     * Use this for one-off queries.
     * Returns local data if available, otherwise fetches from the server.
     * Because we want to avoid stale data, this method will throw an error
     * if the user is offline or there is no active connection to the server.
     *
     * @see https://instantdb.com/docs/instaql
     *
     * @example
     *
     *  const resp = await db.queryOnce({ goals: {} });
     *  console.log(resp.data.goals)
     */
    queryOnce<Q extends InstaQLParams<Schema>>(query: Q, opts?: InstaQLOptions): Promise<{
        data: InstaQLResponse<Schema, Q>;
        pageInfo: PageInfoResponse<Q>;
    }>;
}
/**
 *
 * The first step: init your application!
 *
 * Visit https://instantdb.com/dash to get your `appId` :)
 *
 * @example
 *  import { init } from "@instantdb/core"
 *
 *  const db = init({ appId: "my-app-id" })
 *
 *  // You can also provide a schema for type safety and editor autocomplete!
 *
 *  import { init } from "@instantdb/core"
 *  import schema from ""../instant.schema.ts";
 *
 *  const db = init({ appId: "my-app-id", schema })
 *
 *  // To learn more: https://instantdb.com/docs/modeling-data
 */
declare function init<Schema extends InstantSchemaDef<any, any, any> = InstantUnknownSchema>(config: InstantConfig<Schema>, Storage?: any, NetworkListener?: any, versions?: {
    [key: string]: string;
}): InstantCoreDatabase<Schema>;
/**
 * @deprecated
 * `init_experimental` is deprecated. You can replace it with `init`.
 *
 * @example
 *
 * // Before
 * import { init_experimental } from "@instantdb/core"
 * const db = init_experimental({  ...  });
 *
 * // After
 * import { init } from "@instantdb/core"
 * const db = init({ ...  });
 */
declare const init_experimental: typeof init;
export { init, init_experimental, id, tx, txInit, lookup, InstantAPIError, i, getOps, coerceQuery, weakHash, IndexedDBStorage, WindowNetworkListener, InstantCoreDatabase, Auth, Storage, version, type IDatabase, type RoomSchemaShape, type Query, type QueryResponse, type InstaQLResponse, type PageInfoResponse, type InstantObject, type Exactly, type TransactionChunk, type AuthState, type ConnectionStatus, type User, type AuthToken, type TxChunk, type SubscriptionState, type InstaQLSubscriptionState, type LifecycleSubscriptionState, type InstaQLLifecycleState, type PresenceOpts, type PresenceSlice, type PresenceResponse, type InstaQLParams, type InstaQLOptions, type InstaQLQueryParams, type InstantQuery, type InstantQueryResult, type InstantSchema, type InstantEntity, type InstantSchemaDatabase, type InstaQLFields, type AttrsDefs, type CardinalityKind, type DataAttrDef, type EntitiesDef, type EntitiesWithLinks, type EntityDef, type RoomsDef, type InstantGraph, type LinkAttrDef, type LinkDef, type LinksDef, type ResolveAttrs, type ValueTypes, type RoomsOf, type PresenceOf, type TopicsOf, type InstaQLEntity, type InstaQLResult, type InstantSchemaDef, type InstantUnknownSchema, type IInstantDatabase, type BackwardsCompatibleSchema, type InstantRules, type UpdateParams, type LinkParams, type RuleParams, type InstantDBAttr, type InstantDBAttrOnDelete, type InstantDBCheckedDataType, type InstantDBIdent, type InstantDBInferredType, type ExchangeCodeForTokenParams, type SendMagicCodeParams, type SendMagicCodeResponse, type SignInWithIdTokenParams, type VerifyMagicCodeParams, type VerifyResponse, type FileOpts, type UploadFileResponse, type DeleteFileResponse, type InstantIssue, };
//# sourceMappingURL=index.d.ts.map