@truenas/api-client 1.0.3 → 1.0.5

package/dist/index.cjs

@@ -159,6 +159,16 @@ var TrueNasApi = class {
     this.initializeJobEventsSubscription();
   }
   call(method, params) {
+    return this.dispatch(method, params);
+  }
+  /**
+   * Send a JSON-RPC request and emit its result.
+   *
+   * Shared by {@link call} and the query verbs, which type the same wire call
+   * against different directories — `call` against the hand-maintained one,
+   * the verbs against the generated one.
+   */
+  dispatch(method, params) {
     const message = createJsonRpcMessage(method, params);
     this.connection.ws.next(message);
     const messageId = message.id ?? "";
@@ -174,6 +184,58 @@ var TrueNasApi = class {
       rxjs.take(1)
     );
   }
+  /**
+   * Query a collection and emit the matching entries.
+   *
+   * ```typescript
+   * api.query('user.query')                              // UserEntry[]
+   * api.query('user.query', [['uid', '>', 1000]])        // UserEntry[]
+   * api.query('user.query', [], { select: ['id', 'username'] })
+   *                                       // Pick<UserEntry, 'id' | 'username'>[]
+   * ```
+   *
+   * The precise result type comes from reading the options *literal*. Options
+   * annotated as `QueryListOptions<E>` lose that, and the result degrades to
+   * `Partial<E>[]` — not only when a `select` is present, but whenever the
+   * annotation merely permits one:
+   *
+   * ```typescript
+   * const opts: QueryListOptions<UserEntry> = { limit: 10 };
+   * api.query('user.query', [], opts);          // Partial<UserEntry>[]
+   *
+   * const opts = { limit: 10 } satisfies QueryListOptions<UserEntry>;
+   * api.query('user.query', [], opts);          // UserEntry[]
+   * ```
+   *
+   * That is imprecise, never unsound: `Partial<E>` is a supertype of `E`, so a
+   * field is only ever reported as *possibly* missing, never as present when it
+   * is not. Reach for `satisfies` over an annotation to keep the precision —
+   * the checking is the same, the inferred type is narrower.
+   *
+   * `count` and `get` are rejected: they would change the shape of the
+   * response, which is {@link queryCount} and {@link queryOne}'s job.
+   */
+  query(method, filters, options) {
+    return this.dispatch(method, [filters ?? [], options ?? {}]);
+  }
+  /**
+   * Query a collection and emit the single matching entry.
+   *
+   * Middleware errors unless exactly one entry matches, so this rejects
+   * `limit` and `offset` as well as the shape switches.
+   */
+  queryOne(method, filters, options) {
+    return this.dispatch(method, [filters ?? [], { ...options, get: true }]);
+  }
+  /**
+   * Emit the number of entries matching the filters.
+   *
+   * Takes no options: `select` and `order_by` cannot affect a count, and
+   * `limit` / `offset` would silently cap it.
+   */
+  queryCount(method, filters) {
+    return this.dispatch(method, [filters ?? [], { count: true }]);
+  }
   /**
    * Makes an API call and returns the job ID from the websocket event.
    * Used for v26 where API calls return null but job events contain the job ID.
@@ -3429,7 +3491,14 @@ function instantiateClientForVersion(version, opts, logger) {
     version: version.version,
     versionKey
   });
-  return new Client(uuid, hostnames, version, enabled, systemName, logger);
+  return new Client(
+    uuid,
+    hostnames,
+    version,
+    enabled,
+    systemName,
+    logger
+  );
 }
 function errorMessageOrDefault(error, fallback) {
   if (error instanceof Error) {