@instantdb/admin - npm Package Compare versions

Comparing version 0.10.30 to 0.10.31

dist/index.d.ts

@@ -67,2 +67,15 @@ import { tx, lookup, TransactionChunk } from "@instantdb/core";
 /**
+ * `debugQuery` returns the results of evaluating the corresponding permissions rules for each record.
+ */
+export declare type DebugCheckResult = {
+    /** The ID of the record. */
+    id: string;
+    /** The namespace/table of the record. */
+    entity: string;
+    /** The value of the record. */
+    record: Record<string, any>;
+    /** The result of evaluating the corresponding permissions rule for a record. */
+    check: any;
+};
+/**
  * (XXX)
@@ -193,2 +206,50 @@ * https://github.com/microsoft/TypeScript/issues/26051
     transact: (inputChunks: TransactionChunk | TransactionChunk[]) => Promise<any>;
+    /**
+     * Like `query`, but returns debugging information
+     * for permissions checks along with the result.
+     * Useful for inspecting the values returned by the permissions checks.
+     * Note, this will return debug information for *all* entities
+     * that match the query's `where` clauses.
+     *
+     * Requires a user/guest context to be set with `asUser`,
+     * since permissions checks are user-specific.
+     *
+     * Accepts an optional configuration object with a `rules` key.
+     * The provided rules will override the rules in the database for the query.
+     *
+     * @see https://docs.instantdb.com/docs/instaql
+     *
+     * @example
+     *  await db.asUser({ guest: true }).debugQuery(
+     *    { goals: {} },
+     *    { rules: { goals: { allow: { read: "auth.id != null" } } }
+     *  )
+     */
+    debugQuery: <Q extends Query>(query: Exactly<Query, Q>, opts?: {
+        rules: any;
+    }) => Promise<{
+        result: ResponseOf<{ [K in keyof Q]: Remove$<Q[K]>; }, Schema>;
+        checkResults: DebugCheckResult[];
+    }>;
+    /**
+     * Like `transact`, but does not write to the database.
+     * Returns debugging information for permissions checks.
+     * Useful for inspecting the values returned by the permissions checks.
+     *
+     * Requires a user/guest context to be set with `asUser`,
+     * since permissions checks are user-specific.
+     *
+     * Accepts an optional configuration object with a `rules` key.
+     * The proided rules will override the rules in the database for the duration of the transaction.
+     *
+     * @example
+     *   const goalId = id();
+     *   db.asUser({ guest: true }).debugTransact(
+     *      [tx.goals[goalId].update({title: "Get fit"})],
+     *      { rules: { goals: { allow: { update: "auth.id != null" } } }
+     *   )
+     */
+    debugTransact: (inputChunks: TransactionChunk | TransactionChunk[], opts?: {
+        rules?: any;
+    }) => Promise<any>;
 }
@@ -195,0 +256,0 @@ declare class Auth {

dist/index.js

@@ -203,2 +203,66 @@ "use strict";
         };
+        /**
+         * Like `query`, but returns debugging information
+         * for permissions checks along with the result.
+         * Useful for inspecting the values returned by the permissions checks.
+         * Note, this will return debug information for *all* entities
+         * that match the query's `where` clauses.
+         *
+         * Requires a user/guest context to be set with `asUser`,
+         * since permissions checks are user-specific.
+         *
+         * Accepts an optional configuration object with a `rules` key.
+         * The provided rules will override the rules in the database for the query.
+         *
+         * @see https://docs.instantdb.com/docs/instaql
+         *
+         * @example
+         *  await db.asUser({ guest: true }).debugQuery(
+         *    { goals: {} },
+         *    { rules: { goals: { allow: { read: "auth.id != null" } } }
+         *  )
+         */
+        this.debugQuery = (query, opts) => __awaiter(this, void 0, void 0, function* () {
+            const response = yield jsonFetch(`${this.config.apiURI}/admin/query_perms_check`, {
+                method: "POST",
+                headers: authorizedHeaders(this.config, this.impersonationOpts),
+                body: JSON.stringify({ query, "rules-override": opts === null || opts === void 0 ? void 0 : opts.rules }),
+            });
+            return {
+                result: response.result,
+                checkResults: response["check-results"],
+            };
+        });
+        /**
+         * Like `transact`, but does not write to the database.
+         * Returns debugging information for permissions checks.
+         * Useful for inspecting the values returned by the permissions checks.
+         *
+         * Requires a user/guest context to be set with `asUser`,
+         * since permissions checks are user-specific.
+         *
+         * Accepts an optional configuration object with a `rules` key.
+         * The proided rules will override the rules in the database for the duration of the transaction.
+         *
+         * @example
+         *   const goalId = id();
+         *   db.asUser({ guest: true }).debugTransact(
+         *      [tx.goals[goalId].update({title: "Get fit"})],
+         *      { rules: { goals: { allow: { update: "auth.id != null" } } }
+         *   )
+         */
+        this.debugTransact = (inputChunks, opts) => {
+            const chunks = Array.isArray(inputChunks) ? inputChunks : [inputChunks];
+            const steps = chunks.flatMap((tx) => (0, core_1.getOps)(tx));
+            return jsonFetch(`${this.config.apiURI}/admin/transact_perms_check`, {
+                method: "POST",
+                headers: authorizedHeaders(this.config, this.impersonationOpts),
+                body: JSON.stringify({
+                    steps: steps,
+                    "rules-override": opts === null || opts === void 0 ? void 0 : opts.rules,
+                    // @ts-expect-error because we're using a private API (for now)
+                    "dangerously-commit-tx": opts === null || opts === void 0 ? void 0 : opts.__dangerouslyCommit,
+                }),
+            });
+        };
         this.config = configWithDefaults(_config);
@@ -205,0 +269,0 @@ this.auth = new Auth(this.config);

dist/module/index.d.ts

@@ -67,2 +67,15 @@ import { tx, lookup, TransactionChunk } from "@instantdb/core";
 /**
+ * `debugQuery` returns the results of evaluating the corresponding permissions rules for each record.
+ */
+export declare type DebugCheckResult = {
+    /** The ID of the record. */
+    id: string;
+    /** The namespace/table of the record. */
+    entity: string;
+    /** The value of the record. */
+    record: Record<string, any>;
+    /** The result of evaluating the corresponding permissions rule for a record. */
+    check: any;
+};
+/**
  * (XXX)
@@ -193,2 +206,50 @@ * https://github.com/microsoft/TypeScript/issues/26051
     transact: (inputChunks: TransactionChunk | TransactionChunk[]) => Promise<any>;
+    /**
+     * Like `query`, but returns debugging information
+     * for permissions checks along with the result.
+     * Useful for inspecting the values returned by the permissions checks.
+     * Note, this will return debug information for *all* entities
+     * that match the query's `where` clauses.
+     *
+     * Requires a user/guest context to be set with `asUser`,
+     * since permissions checks are user-specific.
+     *
+     * Accepts an optional configuration object with a `rules` key.
+     * The provided rules will override the rules in the database for the query.
+     *
+     * @see https://docs.instantdb.com/docs/instaql
+     *
+     * @example
+     *  await db.asUser({ guest: true }).debugQuery(
+     *    { goals: {} },
+     *    { rules: { goals: { allow: { read: "auth.id != null" } } }
+     *  )
+     */
+    debugQuery: <Q extends Query>(query: Exactly<Query, Q>, opts?: {
+        rules: any;
+    }) => Promise<{
+        result: ResponseOf<{ [K in keyof Q]: Remove$<Q[K]>; }, Schema>;
+        checkResults: DebugCheckResult[];
+    }>;
+    /**
+     * Like `transact`, but does not write to the database.
+     * Returns debugging information for permissions checks.
+     * Useful for inspecting the values returned by the permissions checks.
+     *
+     * Requires a user/guest context to be set with `asUser`,
+     * since permissions checks are user-specific.
+     *
+     * Accepts an optional configuration object with a `rules` key.
+     * The proided rules will override the rules in the database for the duration of the transaction.
+     *
+     * @example
+     *   const goalId = id();
+     *   db.asUser({ guest: true }).debugTransact(
+     *      [tx.goals[goalId].update({title: "Get fit"})],
+     *      { rules: { goals: { allow: { update: "auth.id != null" } } }
+     *   )
+     */
+    debugTransact: (inputChunks: TransactionChunk | TransactionChunk[], opts?: {
+        rules?: any;
+    }) => Promise<any>;
 }
@@ -195,0 +256,0 @@ declare class Auth {

dist/module/index.js

@@ -173,2 +173,66 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
         };
+        /**
+         * Like `query`, but returns debugging information
+         * for permissions checks along with the result.
+         * Useful for inspecting the values returned by the permissions checks.
+         * Note, this will return debug information for *all* entities
+         * that match the query's `where` clauses.
+         *
+         * Requires a user/guest context to be set with `asUser`,
+         * since permissions checks are user-specific.
+         *
+         * Accepts an optional configuration object with a `rules` key.
+         * The provided rules will override the rules in the database for the query.
+         *
+         * @see https://docs.instantdb.com/docs/instaql
+         *
+         * @example
+         *  await db.asUser({ guest: true }).debugQuery(
+         *    { goals: {} },
+         *    { rules: { goals: { allow: { read: "auth.id != null" } } }
+         *  )
+         */
+        this.debugQuery = (query, opts) => __awaiter(this, void 0, void 0, function* () {
+            const response = yield jsonFetch(`${this.config.apiURI}/admin/query_perms_check`, {
+                method: "POST",
+                headers: authorizedHeaders(this.config, this.impersonationOpts),
+                body: JSON.stringify({ query, "rules-override": opts === null || opts === void 0 ? void 0 : opts.rules }),
+            });
+            return {
+                result: response.result,
+                checkResults: response["check-results"],
+            };
+        });
+        /**
+         * Like `transact`, but does not write to the database.
+         * Returns debugging information for permissions checks.
+         * Useful for inspecting the values returned by the permissions checks.
+         *
+         * Requires a user/guest context to be set with `asUser`,
+         * since permissions checks are user-specific.
+         *
+         * Accepts an optional configuration object with a `rules` key.
+         * The proided rules will override the rules in the database for the duration of the transaction.
+         *
+         * @example
+         *   const goalId = id();
+         *   db.asUser({ guest: true }).debugTransact(
+         *      [tx.goals[goalId].update({title: "Get fit"})],
+         *      { rules: { goals: { allow: { update: "auth.id != null" } } }
+         *   )
+         */
+        this.debugTransact = (inputChunks, opts) => {
+            const chunks = Array.isArray(inputChunks) ? inputChunks : [inputChunks];
+            const steps = chunks.flatMap((tx) => getOps(tx));
+            return jsonFetch(`${this.config.apiURI}/admin/transact_perms_check`, {
+                method: "POST",
+                headers: authorizedHeaders(this.config, this.impersonationOpts),
+                body: JSON.stringify({
+                    steps: steps,
+                    "rules-override": opts === null || opts === void 0 ? void 0 : opts.rules,
+                    // @ts-expect-error because we're using a private API (for now)
+                    "dangerously-commit-tx": opts === null || opts === void 0 ? void 0 : opts.__dangerouslyCommit,
+                }),
+            });
+        };
         this.config = configWithDefaults(_config);
@@ -175,0 +239,0 @@ this.auth = new Auth(this.config);

package.json

 {
   "name": "@instantdb/admin",
-  "version": "0.10.30",
+  "version": "0.10.31",
   "description": "Admin SDK for Instant DB",
@@ -27,5 +27,5 @@ "main": "dist/index.js",
   "dependencies": {
-    "@instantdb/core": "0.10.30",
+    "@instantdb/core": "0.10.31",
     "uuid": "^9.0.1"
   }
 }

src/index.ts

@@ -79,4 +79,4 @@ import { tx, lookup, TransactionChunk, getOps } from "@instantdb/core";
   [K in keyof Q]: IsEmptyObject<Q[K]> extends true
-  ? ResponseObject<K, Schema>[]
-  : (ResponseOf<Q[K], Schema> & ResponseObject<K, Schema>)[];
+    ? ResponseObject<K, Schema>[]
+    : (ResponseOf<Q[K], Schema> & ResponseObject<K, Schema>)[];
 };
@@ -94,2 +94,16 @@
 /**
+ * `debugQuery` returns the results of evaluating the corresponding permissions rules for each record.
+ */
+export type DebugCheckResult = {
+  /** The ID of the record. */
+  id: string;
+  /** The namespace/table of the record. */
+  entity: string;
+  /** The value of the record. */
+  record: Record<string, any>;
+  /** The result of evaluating the corresponding permissions rule for a record. */
+  check: any;
+};
+
+/**
  * (XXX)
@@ -321,2 +335,81 @@ * https://github.com/microsoft/TypeScript/issues/26051
   };
+
+  /**
+   * Like `query`, but returns debugging information
+   * for permissions checks along with the result.
+   * Useful for inspecting the values returned by the permissions checks.
+   * Note, this will return debug information for *all* entities
+   * that match the query's `where` clauses.
+   *
+   * Requires a user/guest context to be set with `asUser`,
+   * since permissions checks are user-specific.
+   *
+   * Accepts an optional configuration object with a `rules` key.
+   * The provided rules will override the rules in the database for the query.
+   *
+   * @see https://docs.instantdb.com/docs/instaql
+   *
+   * @example
+   *  await db.asUser({ guest: true }).debugQuery(
+   *    { goals: {} },
+   *    { rules: { goals: { allow: { read: "auth.id != null" } } }
+   *  )
+   */
+  debugQuery = async <Q extends Query>(
+    query: Exactly<Query, Q>,
+    opts?: { rules: any },
+  ): Promise<{
+    result: QueryResponse<Q, Schema>;
+    checkResults: DebugCheckResult[];
+  }> => {
+    const response = await jsonFetch(
+      `${this.config.apiURI}/admin/query_perms_check`,
+      {
+        method: "POST",
+        headers: authorizedHeaders(this.config, this.impersonationOpts),
+        body: JSON.stringify({ query, "rules-override": opts?.rules }),
+      },
+    );
+
+    return {
+      result: response.result,
+      checkResults: response["check-results"],
+    };
+  };
+
+  /**
+   * Like `transact`, but does not write to the database.
+   * Returns debugging information for permissions checks.
+   * Useful for inspecting the values returned by the permissions checks.
+   *
+   * Requires a user/guest context to be set with `asUser`,
+   * since permissions checks are user-specific.
+   *
+   * Accepts an optional configuration object with a `rules` key.
+   * The proided rules will override the rules in the database for the duration of the transaction.
+   *
+   * @example
+   *   const goalId = id();
+   *   db.asUser({ guest: true }).debugTransact(
+   *      [tx.goals[goalId].update({title: "Get fit"})],
+   *      { rules: { goals: { allow: { update: "auth.id != null" } } }
+   *   )
+   */
+  debugTransact = (
+    inputChunks: TransactionChunk | TransactionChunk[],
+    opts?: { rules?: any },
+  ) => {
+    const chunks = Array.isArray(inputChunks) ? inputChunks : [inputChunks];
+    const steps = chunks.flatMap((tx) => getOps(tx));
+    return jsonFetch(`${this.config.apiURI}/admin/transact_perms_check`, {
+      method: "POST",
+      headers: authorizedHeaders(this.config, this.impersonationOpts),
+      body: JSON.stringify({
+        steps: steps,
+        "rules-override": opts?.rules,
+        // @ts-expect-error because we're using a private API (for now)
+        "dangerously-commit-tx": opts?.__dangerouslyCommit,
+      }),
+    });
+  };
 }
@@ -442,3 +535,3 @@
     "Uh oh! Looks like `init` hasn't run yet. Make sure `init` runs " +
-    "before your first `query` or `transact`.",
+      "before your first `query` or `transact`.",
   );
@@ -445,0 +538,0 @@ return _GLOBAL_CONFIG;

No alert changes

Improved metrics

Total package byte prevSize

99641

increased by21.15%

Lines of code

2197

increased by18.25%

Dependency changes

• + Added@instantdb/core@0.10.31(transitive)

• - Removed@instantdb/core@0.10.30(transitive)

• Updated@instantdb/core@0.10.31