@voxgig/sdkgen 1.3.8 → 1.3.9

package/project/.sdk/src/cmp/lua/fragment/Entity.fragment.lua

@@ -78,6 +78,143 @@ function EntyClass:match_get()
 end
 
 
+-- Feature #4: run `action` through the full pipeline and return a stateful
+-- iterator over result items, so the `streaming` feature's incremental output
+-- is reachable from a generated entity (a normal op call materialises the
+-- whole result). Use it as `for item in ent:stream("list") do ... end`.
+-- `callopts` parameterises the call:
+--   - inbound (download): iterate items/chunks (from the streaming feature
+--     when active, else the materialised items);
+--   - outbound (upload): an iterable `body` in callopts is attached to the
+--     request so the transport can stream the payload;
+--   - `ctrl` (pipeline control) and `signal` (cancellation) honoured.
+function EntyClass:stream(action, args, callopts)
+  local utility = self._utility
+  callopts = callopts or {}
+  local signal = callopts["signal"]
+
+  local ctrl = {}
+  if type(callopts["ctrl"]) == "table" then
+    for k, v in pairs(callopts["ctrl"]) do
+      ctrl[k] = v
+    end
+  end
+  ctrl["stream"] = callopts
+
+  local ctxmap = {
+    opname = action,
+    ctrl = ctrl,
+    match = self._match,
+    data = self._data,
+  }
+  if type(args) == "table" then
+    for k, v in pairs(args) do
+      ctxmap[k] = v
+    end
+  end
+
+  local ctx = utility.make_context(ctxmap, self._entctx)
+
+  -- Outbound: expose the caller's iterable payload so the request builder /
+  -- transport can stream it as the request body.
+  local body = callopts["body"]
+  if body ~= nil then
+    ctx.reqdata = ctx.reqdata or {}
+    ctx.reqdata["body$"] = body
+    ctx.meta["stream_out"] = body
+  end
+
+  local function aborted()
+    if signal == nil then
+      return false
+    end
+    if type(signal) == "function" then
+      return signal() and true or false
+    end
+    if type(signal) == "table" and signal.aborted ~= nil then
+      return signal.aborted and true or false
+    end
+    return false
+  end
+
+  return coroutine.wrap(function()
+    utility.feature_hook(ctx, "PrePoint")
+    local point, err = utility.make_point(ctx)
+    ctx.out["point"] = point
+    if err ~= nil then
+      return
+    end
+
+    utility.feature_hook(ctx, "PreSpec")
+    local spec
+    spec, err = utility.make_spec(ctx)
+    ctx.out["spec"] = spec
+    if err ~= nil then
+      return
+    end
+
+    utility.feature_hook(ctx, "PreRequest")
+    local resp
+    resp, err = utility.make_request(ctx)
+    ctx.out["request"] = resp
+    if err ~= nil then
+      return
+    end
+
+    utility.feature_hook(ctx, "PreResponse")
+    local resp2
+    resp2, err = utility.make_response(ctx)
+    ctx.out["response"] = resp2
+    if err ~= nil then
+      return
+    end
+
+    utility.feature_hook(ctx, "PreResult")
+    local result
+    result, err = utility.make_result(ctx)
+    ctx.out["result"] = result
+    if err ~= nil then
+      return
+    end
+
+    utility.feature_hook(ctx, "PreDone")
+
+    result = ctx.result
+
+    -- Inbound: prefer the streaming feature's incremental iterator; else fall
+    -- back to the materialised items so stream always yields.
+    local stream_fn = nil
+    if result ~= nil then
+      stream_fn = result.stream
+    end
+    if type(stream_fn) == "function" then
+      for item in stream_fn() do
+        if aborted() then
+          return
+        end
+        coroutine.yield(item)
+      end
+    else
+      local data = utility.done(ctx)
+      local items
+      if vs.islist(data) then
+        items = data
+      elseif data == nil then
+        items = {}
+      else
+        items = { data }
+      end
+      for _, item in ipairs(items) do
+        if aborted() then
+          return
+        end
+        coroutine.yield(item)
+      end
+    end
+  end)
+end
+
+
 -- #LoadOp
 
 -- #ListOp

package/project/.sdk/src/cmp/lua/fragment/Main.fragment.lua

@@ -55,14 +55,17 @@ function ProjectNameSDK.new(options)
 
   self._rootctx.options = self.options
 
-  -- Add features from config.
+  -- Add features in the resolved order (make_options puts an explicit list
+  -- order first, else defaults to test-first). Ordering matters: the `test`
+  -- feature installs the base mock transport and the transport features
+  -- (retry/cache/netsim/proxy/ratelimit) wrap whatever is current, so `test`
+  -- must be added before them to sit at the base of the chain.
   local feature_opts = helpers.to_map(vs.getprop(self.options, "feature"))
   if feature_opts ~= nil then
-    local feature_items = vs.items(feature_opts)
-    if feature_items ~= nil then
-      for _, item in ipairs(feature_items) do
-        local fname = item[1]
-        local fopts = helpers.to_map(item[2])
+    local featureorder = vs.getpath(self.options, "__derived__.featureorder")
+    if type(featureorder) == "table" then
+      for _, fname in ipairs(featureorder) do
+        local fopts = helpers.to_map(feature_opts[fname])
         if fopts ~= nil and fopts["active"] == true then
           utility.feature_add(self._rootctx, _make_feature(fname))
         end

package/project/.sdk/src/cmp/ocaml/Config_ocaml.ts

@@ -0,0 +1,114 @@
+
+import {
+  Content,
+  File,
+  cmp,
+  each,
+  isAuthActive,
+  resolveAuthPrefix,
+} from '@voxgig/sdkgen'
+
+
+import {
+  KIT,
+  Model,
+  getModelPath,
+} from '@voxgig/apidef'
+
+
+import {
+  clean,
+  formatOcamlValue,
+  ocamlString,
+} from './utility_ocaml'
+
+
+// sdk_config.ml: make_config () builds the embedded API model as a value;
+// make_feature name is the N-feature-safe factory the client uses to
+// instantiate features named in the options (mirrors go/rust Config).
+const Config = cmp(async function Config(props: any) {
+  const ctx$ = props.ctx$
+  const target = props.target
+
+  const model: Model = ctx$.model
+
+  const entity = getModelPath(model, `main.${KIT}.entity`)
+  const feature = getModelPath(model, `main.${KIT}.feature`)
+
+  const headers = getModelPath(model, `main.${KIT}.config.headers`) || {}
+
+  const authActive = isAuthActive(model)
+  const authPrefix = resolveAuthPrefix(model)
+
+  let baseUrl = ''
+  try { baseUrl = getModelPath(model, `main.${KIT}.info.servers.0.url`) } catch (_e) { }
+
+  const featureConfig: any = {}
+  each(feature, (f: any) => {
+    featureConfig[f.name] = f.config || {}
+  })
+
+  const entityOptions: any = {}
+  each(entity, (ent: any) => {
+    entityOptions[ent.name] = {}
+  })
+
+  const options: any = {
+    base: baseUrl,
+    headers,
+    entity: entityOptions,
+  }
+  if (authActive) {
+    options.auth = { prefix: authPrefix }
+  }
+
+  const entityConfig = Object.values(entity || {}).reduce((a: any, n: any) => (
+    a[n.name] = clean({
+      fields: n.fields,
+      name: n.name,
+      op: n.op,
+      relations: n.relations,
+    }), a), {})
+
+  const config = {
+    main: { name: model.const.Name },
+    feature: featureConfig,
+    options,
+    entity: entityConfig,
+  }
+
+  File({ name: 'sdk_config.' + target.ext }, () => {
+
+    Content(`(* Generated API configuration (mirrors go core/config.go).
+ *
+ * make_config () — the embedded API model as a voxgig struct value.
+ * make_feature name — the N-feature-safe factory the client uses. *)
+
+open Voxgig_struct
+open Sdk_types
+open Sdk_helpers
+open Sdk_features
+
+let make_config () : value =
+  ${formatOcamlValue(config, 1)}
+
+let make_feature (name : string) : feature =
+  match name with
+`)
+
+    each(feature, (f: any) => {
+      if (f.name !== 'base') {
+        Content(`  | "${ocamlString(f.name)}" -> ${f.name}_feature ()
+`)
+      }
+    })
+
+    Content(`  | _ -> base_feature ()
+`)
+  })
+})
+
+
+export {
+  Config
+}

package/project/.sdk/src/cmp/ocaml/EntityOperation_ocaml.ts

@@ -0,0 +1,63 @@
+
+import { ocamlString } from './utility_ocaml'
+
+
+// Emit the OCaml source for one entity CRUD operation, as an assignment to
+// the entity_obj's op field (e_load / e_list / ...). Present ops run the real
+// pipeline via run_op with an op-specific post_done writeback; absent ops
+// install a stub that errors at call time (so the entity_obj record is always
+// fully populated). Mirrors the rust/py Entity op fragments.
+function entityOp(opname: string, present: boolean, entityname: string): string {
+  const field =
+    'load' === opname ? 'e_load' :
+      'list' === opname ? 'e_list' :
+        'create' === opname ? 'e_create' :
+          'update' === opname ? 'e_update' : 'e_remove'
+
+  if (!present) {
+    return `  ent.${field} <- (fun _ _ ->
+      raise (Sdk_error_exc (mk_error "unsupported_op"
+        "Operation \\"${ocamlString(opname)}\\" not supported by entity \\"${ocamlString(entityname)}\\".")));
+`
+  }
+
+  const inputField = ('create' === opname || 'update' === opname) ? 'cs_reqdata' : 'cs_reqmatch'
+  const arg = ('create' === opname || 'update' === opname) ? 'reqdata' : 'reqmatch'
+
+  // Writeback after a successful op (mirrors the py op fragments):
+  //   load/update/remove -> match + data ; list -> match ; create -> data
+  const writeMatch = ('list' === opname || 'load' === opname || 'update' === opname || 'remove' === opname)
+  const writeData = ('create' === opname || 'load' === opname || 'update' === opname || 'remove' === opname)
+
+  let post = ''
+  if (writeMatch) {
+    post += `            (match result.rt_resmatch with Map _ as m -> ent.e_match <- m | _ -> ());\n`
+  }
+  if (writeData) {
+    post += `            if not (is_nullish result.rt_resdata) then
+              ent.e_data <- (match to_map (clone result.rt_resdata) with Map _ as m -> m | _ -> empty_map ());\n`
+  }
+  if ('' === post) {
+    post = `            ()\n`
+  }
+
+  return `  ent.${field} <- (fun ${arg} ctrl ->
+      let ${arg} = if is_nullish ${arg} then empty_map () else ${arg} in
+      let ctx = utility.u_make_context
+          { (default_ctxspec ()) with
+            cs_opname = Some "${ocamlString(opname)}";
+            cs_ctrl = (match ctrl with Noval | Null -> None | c -> Some c);
+            cs_match = Some ent.e_match; cs_data = Some ent.e_data;
+            ${inputField} = Some ${arg} }
+          (Some entctx) in
+      run_op ctx (fun () ->
+          match ctx.c_result with
+          | Some result ->
+${post}          | None -> ()));
+`
+}
+
+
+export {
+  entityOp,
+}

package/project/.sdk/src/cmp/ocaml/Entity_ocaml.ts

@@ -0,0 +1,152 @@
+
+import * as Path from 'node:path'
+
+import {
+  cmp,
+  File, Content, Fragment,
+} from '@voxgig/sdkgen'
+
+import {
+  getModelPath,
+} from '@voxgig/apidef'
+
+import { entityModule, ocamlString, ocamlVarName } from './utility_ocaml'
+import { entityOp } from './EntityOperation_ocaml'
+
+
+const Entity = cmp(function Entity(props: any) {
+  const { model } = props.ctx$
+  const { target, entity } = props
+
+  const ff = Path.normalize(__dirname + '/../../../src/cmp/ocaml/fragment/')
+
+  const opnames = Object.keys(entity.op || {})
+
+  const ops = ['load', 'list', 'create', 'update', 'remove']
+    .map((opname: string) => entityOp(opname, opnames.includes(opname), entity.name))
+    .join('')
+
+  File({ name: entityModule(entity.name) + '.' + target.ext }, () => {
+
+    Content(`(* ${model.const.Name} SDK ${entity.Name} entity (generated by @voxgig/sdkgen).
+ *
+ * An entity is a mutable entity_obj record (see Sdk_types): its CRUD closures
+ * drive the operation pipeline through run_op. Missing ops install a stub that
+ * errors at call time so the record is always fully populated. *)
+
+open Voxgig_struct
+open Sdk_types
+open Sdk_helpers
+open Sdk_runtime
+
+exception Op_return of value
+
+`)
+
+    // run_op — the operation pipeline runner. The (* #Stage-Hook *) marker
+    // lines are the OCaml (* *)-comment hook form; jostraca's built-in
+    // #Name-Tag replacement only matches //-comments, so match the (* *) form
+    // explicitly and rewrite each to a feature_hook call.
+    Fragment({
+      from: ff + 'RunOp.fragment.ml',
+      replace: {
+        ...props.ctx$.stdrep,
+        '/(?<indent>[ \\t]*)\\(\\*[ \\t]*#(?<name>[A-Za-z0-9]+)-Hook[ \\t]*\\*\\)[ \\t]*\\n?/':
+          ({ name, indent }: any) => `${indent}feature_hook ctx "${name}";\n`,
+      }
+    })
+
+    Content(`
+let rec make (client : sdk_client) (entopts_in : value) : entity_obj =
+  let entopts = match to_map entopts_in with Map _ as m -> m | _ -> empty_map () in
+  (match getp entopts "active" with Bool false -> () | _ -> setp entopts "active" (Bool true));
+  let utility = client.cl_utility in
+  let root =
+    match client.cl_rootctx with Some c -> c | None -> failwith "root context not initialised" in
+  let ent = {
+    e_name = "${ocamlString(entity.name)}";
+    e_client = client;
+    e_utility = utility;
+    e_entopts = entopts;
+    e_data = empty_map ();
+    e_match = empty_map ();
+    e_entctx = root;
+    e_make = (fun () -> make client entopts);
+    e_data_set = (fun _ -> ());
+    e_data_get = (fun () -> empty_map ());
+    e_match_set = (fun _ -> ());
+    e_match_get = (fun () -> empty_map ());
+    e_load = (fun _ _ -> Noval);
+    e_list = (fun _ _ -> Noval);
+    e_create = (fun _ _ -> Noval);
+    e_update = (fun _ _ -> Noval);
+    e_remove = (fun _ _ -> Noval);
+    e_stream = (fun _ _ _ -> Seq.empty);
+  } in
+  let entctx = utility.u_make_context
+      { (default_ctxspec ()) with cs_entity = Some ent; cs_entopts = Some entopts } (Some root) in
+  ent.e_entctx <- entctx;
+  utility.u_feature_hook entctx "PostConstructEntity";
+  ent.e_data_set <- (fun args ->
+      if not (is_nullish args) then begin
+        ent.e_data <- (match to_map (clone args) with Map _ as m -> m | _ -> empty_map ());
+        utility.u_feature_hook entctx "SetData"
+      end);
+  ent.e_data_get <- (fun () -> utility.u_feature_hook entctx "GetData"; clone ent.e_data);
+  ent.e_match_set <- (fun args ->
+      if not (is_nullish args) then begin
+        ent.e_match <- (match to_map (clone args) with Map _ as m -> m | _ -> empty_map ());
+        utility.u_feature_hook entctx "SetMatch"
+      end);
+  ent.e_match_get <- (fun () -> utility.u_feature_hook entctx "GetMatch"; clone ent.e_match);
+  (* Streaming operation. Runs \`action\` (an op name, e.g. "list") through the
+   * full pipeline and returns a lazy Seq over result items, so the streaming
+   * feature's incremental output is reachable (a normal op call materialises
+   * the whole result). When the streaming feature is active the result carries
+   * a stream closure and this yields from it (honouring chunkSize); otherwise
+   * it falls back to the materialised items, so stream always yields.
+   * callopts parameterises the call: ctrl (per-call pipeline control), body (an
+   * enumerable/list payload attached to the request for outbound streaming),
+   * and signal (a 0-arity fn -> Bool; iteration stops when it returns true). *)
+  ent.e_stream <- (fun action args callopts ->
+      let callopts = match to_map callopts with Map _ as m -> m | _ -> empty_map () in
+      let ctrl = match to_map (getp callopts "ctrl") with Map _ as m -> m | _ -> empty_map () in
+      setp ctrl "stream" callopts;
+      let reqmatch = match to_map args with Map _ as m -> m | _ -> empty_map () in
+      let ctx = utility.u_make_context
+          { (default_ctxspec ()) with
+            cs_opname = Some action;
+            cs_ctrl = Some ctrl;
+            cs_match = Some ent.e_match; cs_data = Some ent.e_data;
+            cs_reqmatch = Some reqmatch }
+          (Some entctx) in
+      let body = getp callopts "body" in
+      (if not (is_nullish body) then begin
+         let reqdata = match to_map ctx.c_reqdata with Map _ as m -> m | _ -> empty_map () in
+         setp reqdata "body$" body;
+         ctx.c_reqdata <- reqdata;
+         scratch_set ctx "stream_out" body
+       end);
+      ignore (run_op ctx (fun () -> ()));
+      let signal = getp callopts "signal" in
+      let aborted () = match signal with Func _ -> call_json signal = Bool true | _ -> false in
+      let raw = (match ctx.c_result with
+          | Some result ->
+            (match result.rt_stream with
+             | Some fn -> fn ()
+             | None -> (match result.rt_resdata with List r -> !r | v when is_nullish v -> [] | v -> [v]))
+          | None -> []) in
+      let rec seq_of l () = match l with
+        | [] -> Seq.Nil
+        | x :: rest -> if aborted () then Seq.Nil else Seq.Cons (x, seq_of rest) in
+      seq_of raw);
+  ignore run_op;
+${ops}  ent
+`)
+  })
+})
+
+
+export {
+  Entity
+}

package/project/.sdk/src/cmp/ocaml/Gitignore_ocaml.ts

@@ -0,0 +1,37 @@
+
+import {
+  Content,
+  File,
+  cmp,
+} from '@voxgig/sdkgen'
+
+
+const Gitignore = cmp(async function Gitignore(_props: any) {
+  File({ name: '.gitignore' }, () => {
+    Content(`# OCaml build output
+*.cmi
+*.cmo
+*.cmx
+*.cma
+*.cmxa
+*.o
+*.a
+a.out
+run_sdk_test
+run_struct_corpus
+
+# dune (unused; the build is stock ocamlc via the Makefile)
+_build/
+
+# IDE / OS
+.idea/
+.vscode/
+.DS_Store
+`)
+  })
+})
+
+
+export {
+  Gitignore
+}

package/project/.sdk/src/cmp/ocaml/MainEntity_ocaml.ts

@@ -0,0 +1,28 @@
+
+
+import { cmp, Content } from '@voxgig/sdkgen'
+
+import { entityModule, ocamlString, ocamlVarName } from './utility_ocaml'
+
+
+// Entity accessor on the SDK client, injected into sdk_client.ml. Idiomatic
+// usage:  Sdk_client.product client Noval  |> ... .e_list ...
+const MainEntity = cmp(async function MainEntity(props: any) {
+  const { entity } = props
+
+  const fn = ocamlVarName(entity.name)
+  const mod = entityModule(entity.name)
+  const Mod = mod.charAt(0).toUpperCase() + mod.slice(1)
+
+  Content(`
+(* ${entity.Name} entity bound to a client:  ${fn} client entopts *)
+let ${fn} (client : sdk_client) (entopts : value) : entity_obj =
+  ${Mod}.make client entopts
+`)
+
+})
+
+
+export {
+  MainEntity
+}

package/project/.sdk/src/cmp/ocaml/Main_ocaml.ts

@@ -0,0 +1,111 @@
+
+import {
+  cmp, each,
+  File, Content, Copy,
+  entityClassName,
+} from '@voxgig/sdkgen'
+
+
+import type {
+  ModelEntity
+} from '@voxgig/apidef'
+
+
+import {
+  KIT,
+  getModelPath
+} from '@voxgig/apidef'
+
+
+import { Package } from './Package_ocaml'
+import { Config } from './Config_ocaml'
+import { Gitignore } from './Gitignore_ocaml'
+import { MainEntity } from './MainEntity_ocaml'
+import { SdkError } from './SdkError_ocaml'
+
+
+const Main = cmp(async function Main(props: any) {
+
+  const { target } = props
+  const { model } = props.ctx$
+
+  const entity: Record<string, ModelEntity> = getModelPath(model, `main.${KIT}.entity`)
+
+  Package({ target })
+
+  Gitignore({})
+
+  // Copy tm/ocaml verbatim with ProjectName replacement. The src/ subtree
+  // only stages per-feature custom-source dirs (srcfeature: false, so unused),
+  // excluded like the go/rust targets. Stray compiled artifacts are excluded
+  // defensively.
+  Copy({
+    from: 'tm/' + target.name,
+    exclude: [/src\//, /\.(cmi|cmo|cmx|cma|cmxa|o|a)$/, /a\.out$/, /run_sdk_test$/, /run_struct_corpus$/],
+    replace: {
+      ...props.ctx$.stdrep,
+    }
+  })
+
+  // Generated API config + branded-error re-export.
+  Config({ target })
+  SdkError({ target })
+
+  // sdk_client.ml — the client constructors, direct/prepare, and the
+  // per-entity accessors (twin of the go root package + rust core/sdk.rs).
+  File({ name: 'sdk_client.' + target.ext }, () => {
+
+    Content(`(* ${model.const.Name} SDK client (generated by @voxgig/sdkgen).
+ *
+ * The SDK "object" is the runtime sdk_client record (see Sdk_types). These
+ * constructors wire the embedded config + feature factory (Sdk_config) into
+ * the API-agnostic client builders (Sdk_features.make_client_base / sdk_test).
+ * Entity accessors return an entity_obj whose CRUD closures run the pipeline. *)
+
+open Voxgig_struct
+open Sdk_types
+open Sdk_features
+
+(* Construct a live client from options (Noval for defaults). *)
+let make (options : value) : sdk_client =
+  make_client_base
+    ~config:(Sdk_config.make_config ())
+    ~make_feature:Sdk_config.make_feature
+    options
+
+(* No-argument convenience constructor. *)
+let make0 () : sdk_client = make Noval
+
+(* Construct a client in test mode (in-memory mock transport). *)
+let test () : sdk_client =
+  sdk_test
+    ~config:(Sdk_config.make_config ())
+    ~make_feature:Sdk_config.make_feature
+    Noval Noval
+
+(* Test-mode client with explicit test / sdk options. *)
+let test_with (testopts : value) (sdkopts : value) : sdk_client =
+  sdk_test
+    ~config:(Sdk_config.make_config ())
+    ~make_feature:Sdk_config.make_feature
+    testopts sdkopts
+
+(* Low-level escape hatches (raw transport call / request preparation). *)
+let direct (client : sdk_client) (fetchargs : value) : value =
+  Sdk_features.direct client fetchargs
+
+let prepare (client : sdk_client) (fetchargs : value) : value =
+  Sdk_features.prepare client fetchargs
+`)
+
+    each(entity, (entity: ModelEntity) => {
+      MainEntity({ target, entity })
+    })
+  })
+
+})
+
+
+export {
+  Main
+}