@voxgig/sdkgen 3.4.7 → 3.5.0

package/project/.sdk/src/cmp/clojure/Config_clojure.ts

@@ -3,8 +3,11 @@ import {
   Content,
   File,
   cmp,
+  configDefinition,
+  configReprSetting,
   each,
   isAuthActive,
+  isConfigData,
   resolveAuthPrefix,
 } from '@voxgig/sdkgen'
 
@@ -17,7 +20,7 @@ import {
 
 
 import {
-  clean,
+  cljStringChunks,
   formatCljValue,
 } from './utility_clojure'
 
@@ -32,52 +35,44 @@ const Config = cmp(async function Config(props: any) {
 
   const model: Model = ctx$.model
 
-  const entity = getModelPath(model, `main.${KIT}.entity`)
-  const feature = getModelPath(model, `main.${KIT}.feature`)
+  // The canonical config OBJECT and its JSON, from the shared helper. Both
+  // representations render from the same `def`, so they cannot describe
+  // different configs - and this target picks up `options.server` (the OpenAPI
+  // server-variable defaults), which the hand-rolled build here omitted.
+  const { def: config, json: configJson } = configDefinition(model)
+  const asData = isConfigData(configJson, configReprSetting(model))
 
-  const headers = getModelPath(model, `main.${KIT}.config.headers`) || {}
+  File({ name: 'config.clj' }, () => {
 
-  const authActive = isAuthActive(model)
-  const authPrefix = resolveAuthPrefix(model)
+    // ABOVE THE THRESHOLD: emit the model as DATA.
+    //
+    // The literal is one nested form the Clojure reader walks and the compiler
+    // turns into constructor calls at load; a string is one token, and
+    // `sdk.core/json-parse` builds the same LinkedHashMap/ArrayList nodes
+    // `vs/jm` and `vs/jt` produce. It is already the SDK's response decoder,
+    // so this adds no dependency.
+    //
+    // JSON.stringify output is a valid Clojure string literal: it escapes
+    // every backslash, so the JSON's own `\uXXXX` reaches the reader as
+    // `\\uXXXX` and no Clojure escape is ever formed from it.
+    if (asData) {
+      Content(`;; ${model.const.Name} SDK configuration (generated by @voxgig/sdkgen).
+;;
+;; THE API MODEL, EMBEDDED AS DATA (sdkgen rung L1). Emitted only above a size
+;; threshold, or when main.kit.config.repr pins it: for a small model the
+;; literal is smaller and far easier to read when debugging.
+(ns sdk.config
+  (:require [sdk.core :as core]))
 
-  let baseUrl = ''
-  try { baseUrl = getModelPath(model, `main.${KIT}.info.servers.0.url`) } catch (_e) { }
+(def ^:private config-data
+  (str ${cljStringChunks(configJson).map((c: string) => JSON.stringify(c)).join('\n       ')}))
 
-  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,
-    }, true), a), {})
-
-  const config = {
-    main: { name: model.const.Name },
-    feature: featureConfig,
-    options,
-    entity: entityConfig,
-  }
+(defn make-config []
+  (core/json-parse config-data))
+`)
+      return
+    }
 
-  File({ name: 'config.clj' }, () => {
     Content(`;; ${model.const.Name} SDK configuration (generated by @voxgig/sdkgen).
 (ns sdk.config
   (:require [voxgig.struct :as vs]))

package/project/.sdk/src/cmp/clojure/utility_clojure.ts

@@ -125,7 +125,49 @@ function clean(o: any, dropDefaults?: boolean): any {
 }
 
 
+
+// The JSON as Clojure string literals, CHUNKED, joined at load.
+//
+// A Clojure string literal becomes a JVM constant-pool UTF-8 entry, and those
+// are capped at 65,535 bytes. One constant therefore cannot hold a config
+// large enough to select the data representation at all - the threshold is
+// 256 KB, so every model that reaches this branch would exceed the limit.
+//
+// The failure is AOT-only and so is easy to miss: loading from source is fine,
+// and `clojure -M:test-compile` only `require`s. It appears the moment anyone
+// compiles the SDK, which is the normal path for distribution:
+//
+//   Execution error (IllegalArgumentException)
+//     at clojure.asm.ByteVector/putUTF8 (ByteVector.java:245)
+//
+// java/kotlin/scala already chunk for exactly this reason (see Config_java's
+// jsonAppendLines). Chunks are measured in UTF-8 BYTES, not characters, with
+// a wide margin: modified UTF-8 encodes a supplementary character as six
+// bytes, so a character count is not a byte count. Surrogate pairs are kept
+// whole, or a cut would emit a lone surrogate.
+function cljStringChunks(json: string, maxBytes: number = 20000): string[] {
+  const chunks: string[] = []
+  let start = 0
+  let bytes = 0
+  for (let i = 0; i < json.length; i++) {
+    const code = json.charCodeAt(i)
+    // Worst case per UTF-16 unit under modified UTF-8.
+    bytes += code < 0x80 ? 1 : code < 0x800 ? 2 : 3
+    const high = 0xd800 <= code && code <= 0xdbff
+    if (maxBytes <= bytes && !high) {
+      chunks.push(json.slice(start, i + 1))
+      start = i + 1
+      bytes = 0
+    }
+  }
+  if (start < json.length) {
+    chunks.push(json.slice(start))
+  }
+  return 0 === chunks.length ? [''] : chunks
+}
+
 export {
+  cljStringChunks,
   clean,
   formatCljValue,
   cljString,

package/project/.sdk/src/cmp/cpp/Config_cpp.ts

@@ -109,6 +109,24 @@ ${cppConfigLiterals(config)};
 
 inline Value makeConfig() { return vs::parse_json(config_json()); }
 
+// SHARED CONFIG (sdkgen rung L2).
+//
+// The SDK reads the config on every request and never writes to it, so one
+// instance is shared by every client rather than rebuilt per client - this is
+// the difference between parsing the embedded JSON once and once per client.
+//
+// A function-local static in an inline function is one object across every
+// translation unit, and its initialisation is thread-safe by the standard.
+// Value holds shared_ptr nodes, so copying the returned Value shares the
+// structure rather than duplicating it.
+//
+// The result is SHARED: treat it as read-only. Callers that need to mutate
+// should use makeConfig, which always parses a fresh copy.
+inline const Value& sharedConfig() {
+  static const Value shared = makeConfig();
+  return shared;
+}
+
 inline FeaturePtr makeFeature(const std::string& name) {
 `)
 

package/project/.sdk/src/cmp/csharp/Config_csharp.ts

@@ -3,9 +3,10 @@ import {
   Content,
   File,
   cmp,
+  configDefinition,
+  configReprSetting,
   each,
-  isAuthActive,
-  resolveAuthPrefix,
+  isConfigData,
 } from '@voxgig/sdkgen'
 
 
@@ -17,7 +18,7 @@ import {
 
 
 import {
-  clean,
+  csStringLiteral,
   formatCsMap,
 } from './utility_csharp'
 
@@ -32,78 +33,150 @@ const Config = cmp(async function Config(props: any) {
 
   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)
-  // config.auth.prefix override -> spec-derived info.security.prefix -> 'Bearer'
-  const authPrefix = resolveAuthPrefix(model)
-
-  let baseUrl = ''
-  try { baseUrl = getModelPath(model, `main.${KIT}.info.servers.0.url`) } catch (_e) { }
-
-  const authBlock = authActive
-    ? `                ["auth"] = new Dictionary<string, object?>
-                {
-                    ["prefix"] = "${authPrefix}",
-                },\n`
-    : ''
+  // The same config as an OBJECT, built by the shared helper so this target's
+  // literal and the data that replaces it above the threshold are the same
+  // config by construction. The JSON is what the threshold is measured on -
+  // emitted source size varies by language, the model does not.
+  const { def: configDef, json: configJson } = configDefinition(model)
+  const asData = isConfigData(configJson, configReprSetting(model))
 
   File({ name: 'Config.' + target.ext }, () => {
 
     Content(`// ${model.const.Name} SDK - generated model configuration and feature
 // factory. GENERATED from the API model - do not edit by hand.
-
+${asData ? '\nusing System.Text.Json;\n' : ''}
 namespace ${model.const.Name}Sdk;
 
 public static class SdkConfig
 {
-    public static Dictionary<string, object?> MakeConfig()
+`)
+
+    // ABOVE THE THRESHOLD: emit the model as DATA.
+    //
+    // A composite Dictionary literal is a single expression the C# compiler
+    // must bind, type and lower node by node, and every entry becomes IL the
+    // JIT executes on first call. A string constant is one token, and
+    // System.Text.Json builds the same dictionary from it far faster.
+    //
+    // JSON.stringify output is ALMOST a valid C# string literal: every escape
+    // it emits (\\", \\\\, \\b, \\f, \\n, \\r, \\t, \\uXXXX) means the same thing in C#,
+    // and it never emits \\/ or \\0, neither of which C# would accept. What it
+    // does leave raw is U+0085/U+2028/U+2029, which C# counts as line
+    // terminators and forbids inside a quoted literal - hence csStringLiteral.
+    if (asData) {
+      Content(`    // THE API MODEL, EMBEDDED AS DATA (sdkgen rung L1).
+    //
+    // Emitted only above a size threshold, or when \`main.kit.config.repr\`
+    // pins it: for a small model the literal is smaller and far easier to
+    // read when debugging.
+    private const string ConfigData = ${csStringLiteral(configJson)};
+
+    // Boxed numerics compare by exact type - (object)5L does not Equals
+    // (object)5 - and MakeConfig is public API consumers read numbers out of,
+    // so the two representations must not disagree about the type of a whole
+    // number just because the model crossed a size threshold. This ladder
+    // (int, else long, else double) is exactly what the literal branch emits;
+    // see formatCsNumber in the generator.
+    //
+    // Deliberately NOT SdkUtility.JsonToNative: that helper's conditional
+    // operator gives \`TryGetInt64(out var l) ? l : el.GetDouble()\` the common
+    // type double, so it boxes every whole number as a double regardless of
+    // its own doc comment. Reusing it here would make the data branch
+    // disagree with the literal on every integer in the model.
+    private static object? ConfigValue(JsonElement el)
     {
-        return new Dictionary<string, object?>
+        switch (el.ValueKind)
         {
-            ["main"] = new Dictionary<string, object?>
+            case JsonValueKind.Object:
             {
-                ["name"] = "${model.const.Name}",
-            },
-            ["feature"] = new Dictionary<string, object?>
+                var map = new Dictionary<string, object?>();
+                foreach (var prop in el.EnumerateObject())
+                {
+                    map[prop.Name] = ConfigValue(prop.Value);
+                }
+                return map;
+            }
+
+            case JsonValueKind.Array:
             {
-`)
+                var list = new List<object?>();
+                foreach (var item in el.EnumerateArray())
+                {
+                    list.Add(ConfigValue(item));
+                }
+                return list;
+            }
 
-    each(feature, (f: any) => {
-      const fconfig = f.config || {}
-      Content(`                ["${f.name}"] = ${formatCsMap(fconfig, 4)},
-`)
-    })
+            case JsonValueKind.String:
+                return el.GetString();
 
-    Content(`            },
-            ["options"] = new Dictionary<string, object?>
-            {
-                ["base"] = "${baseUrl}",
-${authBlock}                ["headers"] = ${formatCsMap(headers, 4)},
-                ["entity"] = new Dictionary<string, object?>
+            case JsonValueKind.Number:
+                if (el.TryGetInt32(out var i))
                 {
-`)
+                    return i;
+                }
+                if (el.TryGetInt64(out var l))
+                {
+                    return l;
+                }
+                return el.GetDouble();
+
+            case JsonValueKind.True:
+                return true;
+
+            case JsonValueKind.False:
+                return false;
 
-    each(entity, (ent: any) => {
-      Content(`                    ["${ent.name}"] = new Dictionary<string, object?>(),
+            default:
+                return null;
+        }
+    }
+
+    // Parses a fresh, fully materialised config dictionary. Every call
+    // re-parses, so hold the result if you need it more than once.
+    public static Dictionary<string, object?> MakeConfig()
+    {
+        return ConfigValue(JsonSerializer.Deserialize<JsonElement>(ConfigData))
+            as Dictionary<string, object?>
+            ?? new Dictionary<string, object?>();
+    }
 `)
-    })
+    }
+    else {
+      Content(`    public static Dictionary<string, object?> MakeConfig()
+    {
+        return ${formatCsMap(configDef, 2)};
+    }
+`)
+    }
 
-    Content(`                },
-            },
-            ["entity"] = ${formatCsMap(
-      Object.values(entity).reduce((a: any, n: any) => (a[n.name] = clean({
-        fields: n.fields,
-        name: n.name,
-        op: n.op,
-        relations: n.relations,
-      }, true), a), {}), 3)},
-        };
+    // SHARED CONFIG (sdkgen rung L2).
+    //
+    // The SDK reads the config on every request and never writes to it, so one
+    // instance is shared by every client rather than rebuilt per client. Above
+    // the size threshold MakeConfig re-parses the whole embedded JSON, so this
+    // is the difference between parsing the model once per process and once
+    // per client.
+    //
+    // Lazy<T> defaults to ExecutionAndPublication, so concurrent first calls
+    // build it exactly once - the C# twin of go's sync.Once.
+    Content(`
+    private static readonly Lazy<Dictionary<string, object?>> SharedConfigVal =
+        new(MakeConfig);
+
+    // The process-wide config, built once on first use.
+    //
+    // The returned dictionary is SHARED: treat it as read-only. Callers that
+    // need to mutate should use MakeConfig, which always returns a fresh copy.
+    public static Dictionary<string, object?> SharedConfig()
+    {
+        return SharedConfigVal.Value;
     }
+`)
 
+    Content(`
     public static Feature.BaseFeature MakeFeature(string name)
     {
         switch (name)

package/project/.sdk/src/cmp/csharp/fragment/Main.fragment.cs

@@ -27,7 +27,9 @@ public class ProjectNameSDK
     {
         _utility = new Utility();
 
-        var config = global::ProjectNameSdk.SdkConfig.MakeConfig();
+        // The process-wide config (sdkgen rung L2): read-only on the request
+        // path, so every client shares one rather than rebuilding it.
+        var config = global::ProjectNameSdk.SdkConfig.SharedConfig();
 
         _rootctx = _utility.MakeContext(new Dictionary<string, object?>
         {

package/project/.sdk/src/cmp/csharp/utility_csharp.ts

@@ -86,13 +86,103 @@ function formatCsMap(obj: any, indent: number = 0): string {
 }
 
 
+// C# NEW-LINE CHARACTERS, which a regular quoted string literal may not
+// contain: U+000D, U+000A, U+0085 (NEL), U+2028 (LINE SEPARATOR) and U+2029
+// (PARAGRAPH SEPARATOR) - C# language spec, "Line terminators".
+//
+// The first two everyone escapes. The other three are the trap: they are
+// ordinary characters in JSON, in every other target language, and to the eye,
+// so a model string carrying one (an OpenAPI description, default or example
+// pasted from a word processor) emits a C# source file that fails to compile
+// with `error CS1010: Newline in constant`. Verified against .NET 8.
+//
+// Written as ESCAPES, not as the characters themselves: U+2028 and U+2029
+// are line terminators in JavaScript too, so a regex literal containing them
+// verbatim does not parse ("Invalid regular expression: missing /") and this
+// module fails to load. The same trap, one language up.
+const CS_NEWLINE = /[\u0085\u2028\u2029]/g
+
+function csEscapeNewlines(s: string): string {
+  return s.replace(CS_NEWLINE,
+    (c) => '\\u' + (c.codePointAt(0) as number).toString(16).padStart(4, '0'))
+}
+
+
 function formatCsString(val: string): string {
-  return '"' + val
+  return '"' + csEscapeNewlines(val
     .replace(/\\/g, '\\\\')
     .replace(/"/g, '\\"')
     .replace(/\n/g, '\\n')
     .replace(/\r/g, '\\r')
-    .replace(/\t/g, '\\t') + '"'
+    .replace(/\t/g, '\\t')) + '"'
+}
+
+
+// The whole config JSON as a C# string literal.
+//
+// JSON.stringify output is otherwise a valid C# literal - every escape it
+// emits means the same thing in C#, and it never emits \/ or \0 - but it
+// leaves U+0085/U+2028/U+2029 RAW, and those three end a C# string literal.
+function csStringLiteral(s: string): string {
+  return csEscapeNewlines(JSON.stringify(s))
+}
+
+
+// A number as a C# literal whose BOXED TYPE is predictable.
+//
+// C# gives an unsuffixed integer literal the first type of int/uint/long/ulong
+// that fits it, so `3000000000` boxes as uint while `5` boxes as int and
+// `5000000000` as long. Boxed numerics compare by exact type - (object)5L does
+// not Equals (object)5 - so the type a config number lands with is observable
+// to every consumer, and the L1 data branch has to be able to reproduce it.
+// Reproducing a uint band nothing else in the SDK ever produces is not worth
+// it, so the suffix is made explicit instead and the ladder is just int -> long
+// -> double, which SdkConfig.ConfigValue mirrors exactly.
+//
+// THE RANGE TEST IS ON THE EMITTED TEXT, not on the JS number.
+//
+// `String(val)` is exactly what JSON.stringify puts in the data branch, and it
+// prints a double as the SHORTEST decimal that round-trips - which for a value
+// near the 64-bit boundary is not the value's exact decimal expansion. The
+// clearest case is long.MinValue: `String(-9223372036854775808)` is
+// "-9223372036854776000", which is BELOW long.MinValue, so TryGetInt64 refuses
+// it and the data branch yields a double. Deciding from the JS value instead
+// emitted `long.MinValue` and the two branches disagreed at exactly that
+// boundary. Comparing the text as a BigInt makes both sides ask the same
+// question of the same digits.
+//
+// int.MinValue is written by name: `-2147483648` parses as unary minus applied
+// to a literal that does not itself fit in an int, and relying on the special
+// case for that is needless subtlety. There is deliberately no long.MinValue
+// twin - no JS number prints as that text, so it is unreachable.
+//
+// A non-finite value emits `null`, because that is what JSON.stringify does
+// with it - so the two representations still agree.
+const CS_INT_MIN = -2147483648n
+const CS_INT_MAX = 2147483647n
+const CS_LONG_MIN = -9223372036854775808n
+const CS_LONG_MAX = 9223372036854775807n
+
+function formatCsNumber(val: number): string {
+  if (!Number.isFinite(val)) {
+    return 'null'
+  }
+  const text = String(val)
+  // An integer TOKEN, not merely an integral value: `String` switches to
+  // exponential form at 1e21, which is not an integer literal on either side.
+  if (Number.isInteger(val) && /^-?\d+$/.test(text)) {
+    const n = BigInt(text)
+    if (CS_INT_MIN <= n && n <= CS_INT_MAX) {
+      return CS_INT_MIN === n ? 'int.MinValue' : text
+    }
+    if (CS_LONG_MIN <= n && n <= CS_LONG_MAX) {
+      return text + 'L'
+    }
+  }
+  // Fractional, or outside the long range: a double literal. The `D` suffix is
+  // required for the whole-valued case, where the digits alone would be read
+  // as an integer literal (and rejected as too large).
+  return text + 'D'
 }
 
 
@@ -104,10 +194,7 @@ function formatCsValue(val: any, indent: number = 0): string {
     return formatCsString(val)
   }
   if (typeof val === 'number') {
-    if (Number.isInteger(val)) {
-      return String(val)
-    }
-    return String(val)
+    return formatCsNumber(val)
   }
   if (typeof val === 'boolean') {
     return val ? 'true' : 'false'
@@ -186,6 +273,7 @@ function clean(o: any, dropDefaults?: boolean): any {
 export {
   clean,
   csPascalName,
+  csStringLiteral,
   csVarName,
   formatCsMap,
   formatCsValue,

package/project/.sdk/src/cmp/dart/Config_dart.ts

@@ -7,7 +7,10 @@ import {
   Fragment,
   Line,
   cmp,
+  configDefinition,
+  configReprSetting,
   each,
+  isConfigData,
   isAuthActive,
   resolveAuthPrefix,
 } from '@voxgig/sdkgen'
@@ -23,6 +26,7 @@ import {
 
 import {
   clean,
+  dartStringLiteral,
   dartValue,
 } from './utility_dart'
 
@@ -64,8 +68,42 @@ const Config = cmp(async function Config(props: any) {
     baseUrl = getModelPath(model, `main.${KIT}.info.servers.0.url`)
   } catch (_e) { }
 
+  // The same config as an OBJECT, built by the shared helper so this target's
+  // literal and the data that replaces it above the threshold are the same
+  // config by construction. The JSON is what the threshold is measured on -
+  // emitted source size varies by language, the model does not.
+  const { def: configDef, json: configJson } = configDefinition(model)
+  const asData = isConfigData(configJson, configReprSetting(model))
+
   File({ name: 'Config.' + target.ext }, () => {
 
+    // ABOVE THE THRESHOLD: emit the model as DATA.
+    //
+    // `jsonDecode` yields exactly what the literal declared - Map<String,
+    // dynamic> for objects, List<dynamic> for arrays, and int for a whole
+    // number where Dart source would also have written an int - so the fields
+    // keep their types and callers cannot tell the representations apart.
+    if (asData) {
+      Fragment({
+        from: ff + 'Config.data.fragment.dart',
+
+        replace: {
+          ...ctx$.stdrep,
+
+          '// #ImportFeatures': () => each(feature, (f: any) => {
+            Line(`import 'feature/${f.name}/${nom(f, 'Name')}Feature.dart';`)
+          }),
+
+          '// #FeatureClasses': () => each(feature, (f: any) => {
+            Line(`  '${f.name}': () => ${nom(f, 'Name')}Feature(),`)
+          }),
+
+          "'CONFIGJSON'": dartStringLiteral(configJson),
+        }
+      })
+      return
+    }
+
     Fragment({
       from: ff + 'Config.fragment.dart',
 
@@ -77,11 +115,11 @@ const Config = cmp(async function Config(props: any) {
         // these; this one did not.
         ...ctx$.stdrep,
 
-        "'BASEURL'": JSON.stringify(baseUrl),
-
-        "'AUTHBLOCK'": authBlock,
-
-        "'HEADERS'": dartValue(headers, 2),
+        // The whole options map from the canonical definition. Assembling it
+        // slot by slot lost `options.server` entirely, so a spec with a
+        // templated server URL described a different config either side of the
+        // threshold.
+        "'OPTIONSMAP'": dartValue(configDef.options, 1),
 
         '// #ImportFeatures': () => each(feature, (f: any) => {
           Line(`import 'feature/${f.name}/${nom(f, 'Name')}Feature.dart';`)