unikernel/duniverse/ocaml-caqti/caqti/lib/caqti_response_sig.ml

@@ -0,0 +1,89 @@
+(* Copyright (C) 2017--2025  Petter A. Urkedal <paurkedal@gmail.com>
+ *
+ * This library is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU Lesser General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or (at your
+ * option) any later version, with the LGPL-3.0 Linking Exception.
+ *
+ * This library is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public
+ * License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public License
+ * and the LGPL-3.0 Linking Exception along with this library.  If not, see
+ * <http://www.gnu.org/licenses/> and <https://spdx.org>, respectively.
+ *)
+
+(** Signature of a response from a database. *)
+
+module type S = sig
+  type +'b fiber
+
+  type (+'a, +'err) stream
+
+  type ('b, +'m) t
+  (** The type describing the response and containing returned data from a
+      request execution.
+      - ['b] is the type of a single row
+      - ['m] is the possible multiplicities of rows *)
+
+  (** {2 Result inspection} *)
+
+  val returned_count :
+    ('b, 'm) t -> (int, [> Caqti_error.retrieve | `Unsupported]) result fiber
+  (** [returned_count resp] is the number of rows returned by [resp].  This
+      function may not be available for all drivers. *)
+
+  val affected_count :
+    ('b, 'm) t -> (int, [> Caqti_error.retrieve | `Unsupported]) result fiber
+  (** [affected_count resp] is the number of rows affected by the updated the
+      produced [resp].  This function may not be available for all drivers. *)
+
+  (** {2:result_retrieval Result retrieval} *)
+
+  val exec :
+    (unit, [< `Zero]) t -> (unit, [> Caqti_error.retrieve]) result fiber
+  (** [exec resp] checks that [resp] succeeded with no result rows. *)
+
+  val find :
+    ('b, [< `One]) t -> ('b, [> Caqti_error.retrieve]) result fiber
+  (** [find resp] checks that [resp] succeeded with a single row, and returns
+      the decoded row. *)
+
+  val find_opt :
+    ('b, [< `Zero | `One]) t ->
+    ('b option, [> Caqti_error.retrieve]) result fiber
+  (** [find_opt resp] checks that [resp] succeeded with at most one row, and
+      returns the row if any. *)
+
+  val fold :
+    ('b -> 'c -> 'c) ->
+    ('b, 'm) t -> 'c -> ('c, [> Caqti_error.retrieve]) result fiber
+  (** [fold f resp] folds [f] over the decoded rows returned in [resp]. *)
+
+  val fold_s :
+    ('b -> 'c -> ('c, 'e) result fiber) ->
+    ('b, 'm) t -> 'c -> ('c, [> Caqti_error.retrieve] as 'e) result fiber
+  (** [fold_s f resp] folds [f] over the decoded rows returned by [resp] within
+      the IO and result monad.
+
+      {b Note.} Do not make nested queries in the callback to this function.  If
+      you use the same connection, it may lead to data corruption.  If you pull
+      a different connection from the same pool, it may deadlock if the pool
+      runs out of connections.  Also, some drivers may not support simpltaneous
+      connections. *)
+
+  val iter_s :
+    ('b -> (unit, 'e) result fiber) ->
+    ('b, 'm) t -> (unit, [> Caqti_error.retrieve] as 'e) result fiber
+  (** [iter_s f resp] iterates [f] over the decoded rows returned by [resp]
+      within the IO and result monad.
+
+      {b Note.} Do not make nested queries in the callback to this function.
+      Cf. {!fold_s}. *)
+
+  val to_stream : ('b, 'm) t -> ('b, [> Caqti_error.retrieve]) stream
+    (** [to_stream resp] returns a stream whose elements are the decoded rows
+        returned by [resp]. *)
+end