mindoodb-app-sdk 0.0.4

package/dist/index.js

@@ -0,0 +1,634 @@
+// src/client/portRpcClient.ts
+var PROTOCOL = "mindoodb-app-bridge";
+function normalizeRpcValue(value, seen = /* @__PURE__ */ new WeakMap()) {
+  if (typeof value === "function") {
+    throw new Error("Bridge RPC params cannot include functions.");
+  }
+  if (typeof value === "symbol") {
+    throw new Error("Bridge RPC params cannot include symbols.");
+  }
+  if (value === null || typeof value !== "object") {
+    return value;
+  }
+  if (value instanceof Date) {
+    return new Date(value.getTime());
+  }
+  if (value instanceof ArrayBuffer) {
+    return value.slice(0);
+  }
+  if (ArrayBuffer.isView(value)) {
+    return new Uint8Array(value.buffer.slice(value.byteOffset, value.byteOffset + value.byteLength));
+  }
+  if (seen.has(value)) {
+    return seen.get(value);
+  }
+  if (Array.isArray(value)) {
+    const copy2 = [];
+    seen.set(value, copy2);
+    for (const entry of value) {
+      copy2.push(normalizeRpcValue(entry, seen));
+    }
+    return copy2;
+  }
+  const copy = {};
+  seen.set(value, copy);
+  for (const [key, entry] of Object.entries(value)) {
+    copy[key] = normalizeRpcValue(entry, seen);
+  }
+  return copy;
+}
+function toBridgeError(error) {
+  const wrapped = new Error(error.message);
+  wrapped.name = error.code || "MindooDBAppBridgeError";
+  return wrapped;
+}
+function isRpcMessage(message) {
+  if (!isProtocolMessage(message)) {
+    return false;
+  }
+  return "id" in message && typeof message.id === "string";
+}
+function isProtocolMessage(message) {
+  return Boolean(
+    message && typeof message === "object" && "protocol" in message && message.protocol === PROTOCOL
+  );
+}
+var PortRpcClient = class {
+  constructor(port) {
+    this.port = port;
+    this.handleMessage = this.handleMessage.bind(this);
+    this.port.addEventListener("message", this.handleMessage);
+    this.port.start();
+  }
+  pending = /* @__PURE__ */ new Map();
+  listeners = /* @__PURE__ */ new Set();
+  requestCounter = 0;
+  disposed = false;
+  /** Sends one RPC request and resolves with the typed response payload. */
+  async call(method, params) {
+    if (this.disposed) {
+      throw new Error("The bridge connection has already been closed.");
+    }
+    const normalizedParams = normalizeRpcValue(params);
+    const id = `${Date.now()}-${this.requestCounter += 1}`;
+    const message = {
+      protocol: PROTOCOL,
+      kind: "request",
+      id,
+      method,
+      params: normalizedParams
+    };
+    return await new Promise((resolve, reject) => {
+      this.pending.set(id, { resolve, reject });
+      try {
+        this.port.postMessage(message);
+      } catch (error) {
+        this.pending.delete(id);
+        console.error("MindooDB app bridge RPC postMessage failed.", { method, params: normalizedParams, error });
+        reject(error instanceof Error ? error : new Error(String(error)));
+      }
+    });
+  }
+  /** Closes the port and rejects any requests that are still waiting for a response. */
+  dispose() {
+    if (this.disposed) {
+      return;
+    }
+    this.disposed = true;
+    this.port.removeEventListener("message", this.handleMessage);
+    this.port.close();
+    this.pending.forEach(({ reject }) => reject(new Error("The bridge connection was closed.")));
+    this.pending.clear();
+    this.listeners.clear();
+  }
+  /** Subscribes to all protocol messages, including attachment stream traffic. */
+  addMessageListener(listener) {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+  /** Posts a raw protocol message over the port, optionally with transferables. */
+  postMessage(message, transfer = []) {
+    if (this.disposed) {
+      throw new Error("The bridge connection has already been closed.");
+    }
+    try {
+      this.port.postMessage(message, transfer);
+    } catch (error) {
+      console.error("MindooDB app bridge raw postMessage failed.", { message, transferCount: transfer.length, error });
+      throw error;
+    }
+  }
+  /** Dispatches incoming messages to listeners and resolves matching RPC requests. */
+  handleMessage(event) {
+    if (!isProtocolMessage(event.data)) {
+      return;
+    }
+    const message = event.data;
+    this.listeners.forEach((listener) => listener(message));
+    if (!isRpcMessage(message)) {
+      return;
+    }
+    if (message.kind !== "success" && message.kind !== "error") {
+      return;
+    }
+    const pending = this.pending.get(message.id);
+    if (!pending) {
+      return;
+    }
+    this.pending.delete(message.id);
+    if (message.kind === "success") {
+      pending.resolve(message.result);
+      return;
+    }
+    pending.reject(toBridgeError(message.error));
+  }
+};
+
+// src/client/createMindooDBAppBridge.ts
+var PROTOCOL2 = "mindoodb-app-bridge";
+var DEFAULT_CONNECT_TIMEOUT_MS = 1e4;
+function toTransferableArrayBuffer(chunk) {
+  return chunk.buffer.slice(chunk.byteOffset, chunk.byteOffset + chunk.byteLength);
+}
+function isStreamChunkFor(streamId, message) {
+  return message.kind === "stream-chunk" && message.streamId === streamId;
+}
+function isStreamAckFor(streamId, message) {
+  return message.kind === "stream-ack" && message.streamId === streamId;
+}
+function isStreamErrorFor(streamId, message) {
+  return message.kind === "stream-error" && message.streamId === streamId;
+}
+function isThemeChangedMessage(message) {
+  return message.kind === "theme-changed";
+}
+function isViewportChangedMessage(message) {
+  return message.kind === "viewport-changed";
+}
+function toStreamError(message) {
+  const error = new Error(message.error.message);
+  error.name = message.error.code || "MindooDBAppBridgeStreamError";
+  return error;
+}
+function resolveLaunchId(options) {
+  if (options?.launchId) {
+    return options.launchId;
+  }
+  if (typeof window === "undefined") {
+    throw new Error("A launchId must be provided when connecting outside the browser.");
+  }
+  const search = new URLSearchParams(window.location.search);
+  const launchId = search.get("mindoodbAppLaunchId");
+  if (!launchId) {
+    throw new Error("Missing mindoodbAppLaunchId in the current URL.");
+  }
+  return launchId;
+}
+function resolveTargetWindow() {
+  if (typeof window === "undefined") {
+    throw new Error("The MindooDB app bridge is only available in the browser.");
+  }
+  if (window.parent && window.parent !== window) {
+    return window.parent;
+  }
+  if (window.opener) {
+    return window.opener;
+  }
+  throw new Error("Could not find a MindooDB Administrator host window.");
+}
+function waitForConnectedPort(options, launchId) {
+  const targetWindow = resolveTargetWindow();
+  const targetOrigin = options?.targetOrigin ?? "*";
+  const channel = new MessageChannel();
+  const timeoutMs = options?.connectTimeoutMs ?? DEFAULT_CONNECT_TIMEOUT_MS;
+  return new Promise((resolve, reject) => {
+    let timeoutId = null;
+    const cleanup = () => {
+      if (timeoutId !== null) {
+        window.clearTimeout(timeoutId);
+      }
+      channel.port1.removeEventListener("message", handleMessage);
+    };
+    const handleMessage = (event) => {
+      const payload = event.data;
+      if (!payload || payload.protocol !== PROTOCOL2 || payload.type !== "mindoodb-app:connected") {
+        return;
+      }
+      cleanup();
+      resolve(channel.port1);
+    };
+    timeoutId = window.setTimeout(() => {
+      cleanup();
+      channel.port1.close();
+      reject(new Error(`Timed out while connecting to the MindooDB Administrator bridge for launch ${launchId}.`));
+    }, timeoutMs);
+    channel.port1.addEventListener("message", handleMessage);
+    channel.port1.start();
+    const message = {
+      protocol: PROTOCOL2,
+      type: "mindoodb-app:connect",
+      launchId
+    };
+    targetWindow.postMessage(message, targetOrigin, [channel.port2]);
+  });
+}
+var MindooDBAppViewHandleImpl = class {
+  constructor(rpc, databaseId, viewId) {
+    this.rpc = rpc;
+    this.databaseId = databaseId;
+    this.viewId = viewId;
+  }
+  async getDefinition() {
+    return await this.rpc.call("views.getDefinition", {
+      databaseId: this.databaseId,
+      viewId: this.viewId
+    });
+  }
+  async refresh() {
+    await this.rpc.call("views.refresh", {
+      databaseId: this.databaseId,
+      viewId: this.viewId
+    });
+  }
+  async page(input) {
+    return await this.rpc.call("views.page", {
+      databaseId: this.databaseId,
+      viewId: this.viewId,
+      request: input ?? {}
+    });
+  }
+  async getExpansionState() {
+    return await this.rpc.call("views.expansion.get", {
+      databaseId: this.databaseId,
+      viewId: this.viewId
+    });
+  }
+  async setExpansionState(state) {
+    return await this.rpc.call("views.expansion.set", {
+      databaseId: this.databaseId,
+      viewId: this.viewId,
+      expansion: state
+    });
+  }
+  async expand(rowKey) {
+    return await this.rpc.call("views.expansion.expand", {
+      databaseId: this.databaseId,
+      viewId: this.viewId,
+      rowKey
+    });
+  }
+  async collapse(rowKey) {
+    return await this.rpc.call("views.expansion.collapse", {
+      databaseId: this.databaseId,
+      viewId: this.viewId,
+      rowKey
+    });
+  }
+  async expandAll() {
+    return await this.rpc.call("views.expansion.expandAll", {
+      databaseId: this.databaseId,
+      viewId: this.viewId
+    });
+  }
+  async collapseAll() {
+    return await this.rpc.call("views.expansion.collapseAll", {
+      databaseId: this.databaseId,
+      viewId: this.viewId
+    });
+  }
+  async getRow(rowKey) {
+    return await this.rpc.call("views.row.get", {
+      databaseId: this.databaseId,
+      viewId: this.viewId,
+      rowKey
+    });
+  }
+  async getCategory(input) {
+    return await this.rpc.call("views.category.get", {
+      databaseId: this.databaseId,
+      viewId: this.viewId,
+      lookup: input
+    });
+  }
+  async pageCategory(categoryKey, input) {
+    return await this.rpc.call("views.category.page", {
+      databaseId: this.databaseId,
+      viewId: this.viewId,
+      categoryKey,
+      request: input ?? {}
+    });
+  }
+  async listCategoryDocumentIds(categoryKey) {
+    return await this.rpc.call("views.category.documentIds", {
+      databaseId: this.databaseId,
+      viewId: this.viewId,
+      categoryKey
+    });
+  }
+  async dispose() {
+    await this.rpc.call("views.dispose", {
+      databaseId: this.databaseId,
+      viewId: this.viewId
+    });
+  }
+};
+var MindooDBAppReadableAttachmentStreamImpl = class {
+  constructor(rpc, streamId) {
+    this.rpc = rpc;
+    this.streamId = streamId;
+    this.unsubscribe = this.rpc.addMessageListener((message) => {
+      if (isStreamChunkFor(this.streamId, message)) {
+        const pending = this.pendingRead;
+        this.pendingRead = null;
+        if (!pending) {
+          return;
+        }
+        pending.resolve(message.done ? null : new Uint8Array(message.chunk ?? new ArrayBuffer(0)));
+        if (message.done) {
+          this.closed = true;
+          this.unsubscribe();
+        }
+        return;
+      }
+      if (isStreamErrorFor(this.streamId, message)) {
+        const pending = this.pendingRead;
+        this.pendingRead = null;
+        pending?.reject(toStreamError(message));
+        this.closed = true;
+        this.unsubscribe();
+      }
+    });
+  }
+  unsubscribe;
+  closed = false;
+  pendingRead = null;
+  /** Requests and returns the next attachment chunk, or `null` when the stream ends. */
+  async read() {
+    if (this.closed) {
+      return null;
+    }
+    if (this.pendingRead) {
+      throw new Error("A read() call is already in progress for this attachment stream.");
+    }
+    return await new Promise((resolve, reject) => {
+      this.pendingRead = { resolve, reject };
+      this.rpc.postMessage({
+        protocol: PROTOCOL2,
+        kind: "stream-read",
+        streamId: this.streamId
+      });
+    });
+  }
+  /** Closes the read stream and releases any pending read waiter. */
+  async close() {
+    if (this.closed) {
+      return;
+    }
+    this.closed = true;
+    this.pendingRead?.resolve(null);
+    this.pendingRead = null;
+    this.rpc.postMessage({
+      protocol: PROTOCOL2,
+      kind: "stream-close",
+      streamId: this.streamId
+    });
+    this.unsubscribe();
+  }
+};
+var MindooDBAppWritableAttachmentStreamImpl = class {
+  constructor(rpc, streamId) {
+    this.rpc = rpc;
+    this.streamId = streamId;
+    this.unsubscribe = this.rpc.addMessageListener((message) => {
+      if (isStreamAckFor(this.streamId, message)) {
+        const inflight = this.inflight;
+        this.inflight = null;
+        inflight?.resolve();
+        return;
+      }
+      if (isStreamErrorFor(this.streamId, message)) {
+        const inflight = this.inflight;
+        this.inflight = null;
+        inflight?.reject(toStreamError(message));
+        this.closed = true;
+        this.unsubscribe();
+      }
+    });
+  }
+  unsubscribe;
+  closed = false;
+  inflight = null;
+  queue = Promise.resolve();
+  /** Ensures write/close/abort operations run strictly in order. */
+  enqueue(operation) {
+    const next = this.queue.then(operation);
+    this.queue = next.catch(() => void 0);
+    return next;
+  }
+  /** Sends one stream operation and waits for its ack/error response. */
+  async waitForAck(send) {
+    return await new Promise((resolve, reject) => {
+      this.inflight = { resolve, reject };
+      send();
+    });
+  }
+  /** Writes one binary chunk to the host-managed attachment stream. */
+  async write(chunk) {
+    if (this.closed) {
+      throw new Error("The attachment write stream is already closed.");
+    }
+    return await this.enqueue(async () => {
+      const buffer = toTransferableArrayBuffer(chunk);
+      await this.waitForAck(() => {
+        this.rpc.postMessage({
+          protocol: PROTOCOL2,
+          kind: "stream-write",
+          streamId: this.streamId,
+          chunk: buffer
+        }, [buffer]);
+      });
+    });
+  }
+  /** Gracefully closes the write stream after any queued writes complete. */
+  async close() {
+    if (this.closed) {
+      return;
+    }
+    this.closed = true;
+    await this.enqueue(async () => {
+      await this.waitForAck(() => {
+        this.rpc.postMessage({
+          protocol: PROTOCOL2,
+          kind: "stream-close",
+          streamId: this.streamId
+        });
+      });
+    });
+    this.unsubscribe();
+  }
+  /** Aborts the write stream after any in-flight work has settled. */
+  async abort() {
+    if (this.closed) {
+      return;
+    }
+    this.closed = true;
+    await this.enqueue(async () => {
+      await this.waitForAck(() => {
+        this.rpc.postMessage({
+          protocol: PROTOCOL2,
+          kind: "stream-abort",
+          streamId: this.streamId
+        });
+      });
+    });
+    this.unsubscribe();
+  }
+};
+var MindooDBAppDatabaseImpl = class {
+  constructor(rpc, databaseId) {
+    this.rpc = rpc;
+    this.databaseId = databaseId;
+    this.documents = {
+      list: async (query) => await this.rpc.call("documents.list", {
+        databaseId: this.databaseId,
+        query: query ?? {}
+      }),
+      get: async (docId) => await this.rpc.call("documents.get", {
+        databaseId: this.databaseId,
+        docId
+      }),
+      create: async (input) => await this.rpc.call("documents.create", {
+        databaseId: this.databaseId,
+        input
+      }),
+      update: async (docId, patch) => await this.rpc.call("documents.update", {
+        databaseId: this.databaseId,
+        docId,
+        patch
+      }),
+      delete: async (docId) => await this.rpc.call("documents.delete", {
+        databaseId: this.databaseId,
+        docId
+      }),
+      listHistory: async (docId) => await this.rpc.call("documents.history.list", {
+        databaseId: this.databaseId,
+        docId
+      }),
+      getAtTimestamp: async (docId, timestamp) => await this.rpc.call("documents.history.getAtTimestamp", {
+        databaseId: this.databaseId,
+        docId,
+        timestamp
+      })
+    };
+    this.views = {
+      create: async (definition) => {
+        const result = await this.rpc.call("views.create", {
+          databaseId: this.databaseId,
+          definition
+        });
+        return new MindooDBAppViewHandleImpl(this.rpc, this.databaseId, result.viewId);
+      },
+      open: async (viewId) => new MindooDBAppViewHandleImpl(this.rpc, this.databaseId, viewId)
+    };
+    this.attachments = {
+      list: async (docId) => await this.rpc.call("attachments.list", {
+        databaseId: this.databaseId,
+        docId
+      }),
+      remove: async (docId, attachmentName) => await this.rpc.call("attachments.remove", {
+        databaseId: this.databaseId,
+        docId,
+        attachmentName
+      }),
+      openReadStream: async (docId, attachmentName) => {
+        const result = await this.rpc.call("attachments.openReadStream", {
+          databaseId: this.databaseId,
+          docId,
+          attachmentName
+        });
+        return new MindooDBAppReadableAttachmentStreamImpl(this.rpc, result.streamId);
+      },
+      openWriteStream: async (docId, attachmentName, contentType) => {
+        const result = await this.rpc.call("attachments.openWriteStream", {
+          databaseId: this.databaseId,
+          docId,
+          attachmentName,
+          contentType
+        });
+        return new MindooDBAppWritableAttachmentStreamImpl(this.rpc, result.streamId);
+      }
+    };
+  }
+  documents;
+  views;
+  attachments;
+  /** Returns database metadata for the currently opened binding. */
+  async info() {
+    return await this.rpc.call("databases.info", {
+      databaseId: this.databaseId
+    });
+  }
+};
+var MindooDBAppSessionImpl = class {
+  constructor(rpc) {
+    this.rpc = rpc;
+  }
+  /** Returns the launch context provided by the Administrator host. */
+  async getLaunchContext() {
+    return await this.rpc.call("session.getLaunchContext", {});
+  }
+  async listDatabases() {
+    return await this.rpc.call("session.listDatabases", {});
+  }
+  /** Opens one database binding and returns a client facade for it. */
+  async openDatabase(databaseId) {
+    await this.rpc.call("session.openDatabase", { databaseId });
+    return new MindooDBAppDatabaseImpl(this.rpc, databaseId);
+  }
+  onThemeChange(listener) {
+    return this.rpc.addMessageListener((message) => {
+      if (isThemeChangedMessage(message)) {
+        listener(message.theme);
+      }
+    });
+  }
+  onViewportChange(listener) {
+    return this.rpc.addMessageListener((message) => {
+      if (isViewportChangedMessage(message)) {
+        listener(message.viewport);
+      }
+    });
+  }
+  /** Disconnects from the host and always disposes the underlying port client. */
+  async disconnect() {
+    try {
+      await this.rpc.call("session.disconnect", {});
+    } finally {
+      this.rpc.dispose();
+    }
+  }
+};
+function createMindooDBAppBridge() {
+  return {
+    async connect(options) {
+      const launchId = resolveLaunchId(options);
+      const port = await waitForConnectedPort(options, launchId);
+      const rpc = new PortRpcClient(port);
+      return new MindooDBAppSessionImpl(rpc);
+    }
+  };
+}
+
+// src/viewLanguage.ts
+import {
+  createViewLanguage,
+  getMindooDBViewLanguageHelper,
+  mindooDBViewLanguageHelpers,
+  mindooDBViewLanguageHelpersByName
+} from "mindoodb-view-language";
+export {
+  createMindooDBAppBridge,
+  createViewLanguage
+};

package/dist/testing/index.d.ts

@@ -0,0 +1,60 @@
+import { Z as MindooDBAppLaunchContext, P as MindooDBAppDatabaseInfo, R as MindooDBAppDocumentApi, a5 as MindooDBAppViewApi, a as MindooDBAppAttachmentApi, M as MindooDBAppBridge, a2 as MindooDBAppSession, k as MindooDBAppBridgeRpcRequest, Y as MindooDBAppHostTheme, a7 as MindooDBAppViewport, h as MindooDBAppBridgePortMessage } from '../types-BGdIfp-D.js';
+import 'mindoodb-view-language';
+
+type MaybePromise<T> = T | Promise<T>;
+type MockDatabaseMethods = {
+    documents?: Partial<MindooDBAppDocumentApi>;
+    views?: Partial<MindooDBAppViewApi>;
+    attachments?: Partial<MindooDBAppAttachmentApi>;
+};
+interface MockMindooDBAppDatabaseDefinition {
+    info: MindooDBAppDatabaseInfo;
+    methods?: MockDatabaseMethods;
+}
+interface CreateMockMindooDBAppSessionOptions {
+    launchContext?: Partial<MindooDBAppLaunchContext>;
+    databases?: MockMindooDBAppDatabaseDefinition[];
+    onDisconnect?: () => MaybePromise<void>;
+}
+interface MockMindooDBAppSessionController {
+    bridge: MindooDBAppBridge;
+    session: MindooDBAppSession;
+    getLaunchContext(): MindooDBAppLaunchContext;
+    setLaunchContext(patch?: Partial<MindooDBAppLaunchContext>): MindooDBAppLaunchContext;
+    listDatabases(): MindooDBAppDatabaseInfo[];
+    setDatabases(definitions: MockMindooDBAppDatabaseDefinition[]): void;
+    emitThemeChange(theme: MindooDBAppHostTheme): void;
+    emitViewportChange(viewport: MindooDBAppViewport): void;
+}
+declare function createMockMindooDBAppSession(options?: CreateMockMindooDBAppSessionOptions): MockMindooDBAppSessionController;
+declare function createMockMindooDBAppBridge(options?: CreateMockMindooDBAppSessionOptions): MockMindooDBAppSessionController;
+type FakeBridgeRequestHandler = (params: unknown, context: {
+    host: FakeBridgeHostController;
+    request: MindooDBAppBridgeRpcRequest;
+    port: MessagePort;
+}) => MaybePromise<unknown>;
+type FakeBridgePortMessageHandler = (message: Exclude<MindooDBAppBridgePortMessage, MindooDBAppBridgeRpcRequest>, context: {
+    host: FakeBridgeHostController;
+    port: MessagePort;
+}) => MaybePromise<boolean | void>;
+interface CreateFakeBridgeHostOptions extends CreateMockMindooDBAppSessionOptions {
+    windowMode?: "parent" | "opener";
+    requestHandlers?: Record<string, FakeBridgeRequestHandler>;
+    onPortMessage?: FakeBridgePortMessageHandler;
+}
+interface FakeBridgeHostController {
+    bridge: MindooDBAppBridge;
+    session: MindooDBAppSession;
+    readonly launchId: string;
+    readonly requests: ReadonlyArray<MindooDBAppBridgeRpcRequest>;
+    install(): void;
+    dispose(): void;
+    emitThemeChange(theme: MindooDBAppHostTheme): void;
+    emitViewportChange(viewport: MindooDBAppViewport): void;
+    postPortMessage(message: MindooDBAppBridgePortMessage, transfer?: Transferable[]): void;
+    setRequestHandler(method: string, handler: FakeBridgeRequestHandler): void;
+    clearRequestHandler(method: string): void;
+}
+declare function createFakeBridgeHost(options?: CreateFakeBridgeHostOptions): FakeBridgeHostController;
+
+export { type CreateFakeBridgeHostOptions, type CreateMockMindooDBAppSessionOptions, type FakeBridgeHostController, type FakeBridgePortMessageHandler, type FakeBridgeRequestHandler, type MockMindooDBAppDatabaseDefinition, type MockMindooDBAppSessionController, createFakeBridgeHost, createMockMindooDBAppBridge, createMockMindooDBAppSession };