@voxgig/sdkgen 1.3.14 → 1.3.17

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

@@ -0,0 +1,92 @@
+
+import { cmp, Content, isAuthActive, envName, canonKey, entityIdField, opRequestShape } from '@voxgig/sdkgen'
+
+import {
+  KIT,
+  getModelPath,
+  nom,
+} from '@voxgig/apidef'
+
+import { csVarName } from './utility_csharp'
+
+
+// A type-correct C# literal for a param: numeric/boolean/array/object params
+// render a typed literal; strings render the quoted placeholder. The SDK's
+// loose object model means all values live in Dictionary<string, object?>.
+function csLit(type: any, placeholder: string = 'example'): string {
+  const k = canonKey(type)
+  if ('INTEGER' === k) return '1L'
+  if ('NUMBER' === k) return '1.0'
+  if ('BOOLEAN' === k) return 'true'
+  if ('ARRAY' === k) return 'new List<object?>()'
+  if ('OBJECT' === k) return 'new Dictionary<string, object?>()'
+  return `"${placeholder}"`
+}
+
+
+const ReadmeTopQuick = cmp(function ReadmeTopQuick(props: any) {
+  const { target, ctx$: { model } } = props
+
+  const entity = getModelPath(model, `main.${KIT}.entity`)
+
+  const exampleEntity = Object.values(entity).find((e: any) => e.active !== false) as any
+
+  const authActive = isAuthActive(model)
+  const ctor = authActive
+    ? `new ${model.const.Name}SDK(new Dictionary<string, object?>\n{\n    ["apikey"] = Environment.GetEnvironmentVariable("${envName(model)}_APIKEY"),\n})`
+    : `new ${model.const.Name}SDK()`
+
+  Content(`\`\`\`csharp
+using ${model.const.Name}Sdk;
+
+var client = ${ctor};
+
+`)
+
+  if (exampleEntity) {
+    const eName = nom(exampleEntity, 'Name')
+    // Sanitise the local variable name — an entity whose camelCased name is a
+    // C# keyword gets a trailing underscore (csVarName) so the snippet compiles.
+    const eVar = csVarName(exampleEntity.name)
+    const opnames = Object.keys(exampleEntity.op || {})
+    // Model-driven id key: null when the entity has no id-like field, in which
+    // case the load example takes an empty match.
+    const idF = entityIdField(exampleEntity)
+
+    if (opnames.includes('list')) {
+      Content(`// List all ${eName.toLowerCase()}s (returns object?, an aggregate list; raises on error)
+var ${eVar}List = client.${eName}().List(null);
+Console.WriteLine(${eVar}List);
+`)
+    }
+
+    if (opnames.includes('load')) {
+      // Every REQUIRED load-match key (id first, then parent path params like
+      // page_id) — the same shape the runtime resolves path params from, so
+      // the example always works.
+      const loadItems = opRequestShape(exampleEntity, 'load').items
+        .filter((it: any) => !it.optional || it.name === idF)
+        .sort((a: any, b: any) =>
+          (a.name === idF ? 0 : 1) - (b.name === idF ? 0 : 1))
+      const loadArg = 0 < loadItems.length
+        ? `new Dictionary<string, object?> {${loadItems.map((it: any) =>
+          ` ["${it.name}"] = ${csLit(it.type,
+            it.name === idF ? 'example_id' : 'example_' + it.name)}`).join(',')} }`
+        : 'null'
+      Content(`
+// Load a specific ${eName.toLowerCase()} (returns the record, raises on error)
+var ${eVar} = client.${eName}().Load(${loadArg});
+Console.WriteLine(${eVar});
+`)
+    }
+  }
+
+  Content(`\`\`\`
+`)
+
+})
+
+
+export {
+  ReadmeTopQuick
+}

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

@@ -0,0 +1,77 @@
+
+import { cmp, Content, canonKey, entityIdField, pickExampleEntity, opRequestShape } from '@voxgig/sdkgen'
+
+import {
+  KIT,
+  getModelPath,
+  nom,
+} from '@voxgig/apidef'
+
+import { csVarName } from './utility_csharp'
+
+
+// A type-correct C# literal for a field's canonical type.
+function csLit(type: any): string {
+  const k = canonKey(type)
+  if ('INTEGER' === k) return '1L'
+  if ('NUMBER' === k) return '1.0'
+  if ('BOOLEAN' === k) return 'true'
+  if ('ARRAY' === k) return 'new List<object?>()'
+  if ('OBJECT' === k) return 'new Dictionary<string, object?>()'
+  return '"example"'
+}
+
+
+const ReadmeTopTest = cmp(function ReadmeTopTest(props: any) {
+  const { target, ctx$: { model } } = props
+
+  const entity = getModelPath(model, `main.${KIT}.entity`)
+
+  // Pick an entity with a real op (prefer a read op) — never fabricate a
+  // `load` on an op-less entity.
+  const { entity: exampleEntity, primaryOp } = pickExampleEntity(entity)
+
+  Content(`\`\`\`csharp
+var client = ${model.const.Name}SDK.TestSDK(null, null);
+`)
+
+  if (exampleEntity && primaryOp) {
+    const eName = nom(exampleEntity, 'Name')
+    const idF = entityIdField(exampleEntity)
+    const opMethod = primaryOp.charAt(0).toUpperCase() + primaryOp.slice(1)
+    const isMatchOp = 'load' === primaryOp || 'remove' === primaryOp
+    let arg = 'null'
+    if (isMatchOp) {
+      // Every REQUIRED match key (id first) — the same shape that generates
+      // the op's request type, so the block stays honest.
+      const items = opRequestShape(exampleEntity, primaryOp).items
+        .filter((it: any) => !it.optional || it.name === idF)
+        .sort((a: any, b: any) =>
+          (a.name === idF ? 0 : 1) - (b.name === idF ? 0 : 1))
+      arg = 0 < items.length
+        ? `new Dictionary<string, object?> {${items.map((it: any) =>
+          ` ["${it.name}"] = ${it.name === idF ? '"test01"' : csLit(it.type)}`).join(',')} }`
+        : 'null'
+    } else if ('create' === primaryOp || 'update' === primaryOp) {
+      const items = opRequestShape(exampleEntity, primaryOp).items
+        .filter((it: any) => it.name !== idF && it.name !== 'id')
+      const required = items.filter((it: any) => !it.optional)
+      const chosen = required.length ? required : items.slice(0, 3)
+      arg = `new Dictionary<string, object?> {${chosen.map((it: any) =>
+        ` ["${it.name}"] = ${csLit(it.type)}`).join(',')} }`
+    }
+    const eVar = csVarName(exampleEntity.name) + ('list' === primaryOp ? 'List' : '')
+    Content(`var ${eVar} = client.${eName}().${opMethod}(${arg});
+Console.WriteLine(${eVar});
+`)
+  }
+
+  Content(`\`\`\`
+`)
+
+})
+
+
+export {
+  ReadmeTopTest
+}

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

@@ -13,6 +13,7 @@ import { cmp, each, Folder } from '@voxgig/sdkgen'
 
 import { TestEntity } from './TestEntity_csharp'
 import { TestDirect } from './TestDirect_csharp'
+import { ReadmeExamplesTest } from './ReadmeExamplesTest_csharp'
 
 
 const Test = cmp(function Test(props: any) {
@@ -29,6 +30,9 @@ const Test = cmp(function Test(props: any) {
       TestEntity({ target, entity })
       TestDirect({ target, entity })
     })
+
+    // Validate the documented csharp examples in the root + per-language docs.
+    ReadmeExamplesTest({ target })
   })
 })
 

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

@@ -5,10 +5,10 @@
 // (op.<name>.points[].args.params[]) and emits one file,
 // lib/<Sdk>Types.dart, with a Dart class per active entity plus a
 // request/match class per active op. Field/param sentinels ($STRING,
-// $INTEGER, ...) are turned into Dart types locally (Dart is not in the
-// shared canonToType table); the sentinel key comes from the shared
-// canonKey helper so the source of truth (@voxgig/apidef VALID_CANON) is
-// respected.
+// $INTEGER, ...) map to Dart types via the SHARED canonToType 'dart' column
+// (the single source of truth per language — do not keep a local table
+// here); the doc-comment sentinel key comes from the shared canonKey helper
+// so the source of truth (@voxgig/apidef VALID_CANON) is respected.
 //
 // TYPE CHOICE: plain classes with nullable fields + fromMap/toMap. The
 // generated ops accept/return runtime maps (Dart has no structural typing),
@@ -23,7 +23,7 @@ import {
   File, Content,
 } from '@voxgig/sdkgen'
 
-import { canonKey, opTypeName, opRequestShape } from '@voxgig/sdkgen'
+import { canonKey, canonToType, opTypeName, opRequestShape, warnEntityTypeCollisions } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -31,21 +31,7 @@ import {
 } from '@voxgig/apidef'
 
 
-// Sentinel -> Dart type (nullable added at emission).
-const DART_TYPE: Record<string, string> = {
-  STRING: 'String',
-  INTEGER: 'int',
-  NUMBER: 'num',
-  BOOLEAN: 'bool',
-  NULL: 'Object',
-  ARRAY: 'List<dynamic>',
-  OBJECT: 'Map<String, dynamic>',
-  ANY: 'dynamic',
-}
-
-function dartType(sentinel: unknown): string {
-  return DART_TYPE[canonKey(sentinel)] ?? 'dynamic'
-}
+const LANG = 'dart'
 
 
 // Dart reserved words that cannot be used as field names.
@@ -65,14 +51,28 @@ function dartIdent(name: string): boolean {
 
 // Emit a Dart data class from a list of {name, type, optional} items. All
 // fields are nullable (`optional` is documented) since the runtime passes
-// partial maps; fromMap is lenient (mismatched value types become null).
-function emitClass(typeName: string, items: any[]): void {
+// partial maps; fromMap is lenient (mismatched value types become null). An
+// item whose name is not a legal identifier is skipped (WITH a warning — the
+// key stays reachable via the runtime map, but its absence from the typed
+// model should be visible, not silent).
+function emitClass(typeName: string, items: any[], log?: any): void {
   const usable = items.filter((it: any) => it && null != it.name && dartIdent(it.name))
 
+  items.forEach((it: any) => {
+    if (it && null != it.name && !dartIdent(it.name) && log && log.warn) {
+      log.warn({
+        point: 'entity-types-skip-field', typeName, field: it.name,
+        note: `dart: field "${it.name}" of ${typeName} has no legal Dart ` +
+          `identifier form; omitted from the typed model (still reachable ` +
+          `via the runtime map)`,
+      })
+    }
+  })
+
   Content(`class ${typeName} {
 `)
   usable.forEach((it: any) => {
-    const base = dartType(it.type)
+    const base = canonToType(it.type, LANG)
     const t = 'dynamic' === base ? 'dynamic' : base + '?'
     const req = it.optional ? '' : ' (required at the API)'
     Content(`  /// ${canonKey(it.type) || 'ANY'}${req}
@@ -101,7 +101,7 @@ function emitClass(typeName: string, items: any[]): void {
   factory ${typeName}.fromMap(Map<String, dynamic> m) => ${typeName}(
 `)
     usable.forEach((it: any) => {
-      const base = dartType(it.type)
+      const base = canonToType(it.type, LANG)
       if ('dynamic' === base) {
         Content(`        ${it.name}: m['${it.name}'],
 `)
@@ -134,16 +134,30 @@ function emitClass(typeName: string, items: any[]): void {
 
 
 const EntityTypes = cmp(function EntityTypes(props: any) {
-  const { model } = props.ctx$
+  const { model, log } = props.ctx$
   const { target } = props
 
-  const entity = getModelPath(model, `main.${KIT}.entity`)
-  const entityList = each(entity).filter((e: any) => e.active !== false)
+  // only_active:false — getModelPath DROPS active:false entries by default,
+  // but the consumer scaffold (create-sdkgen Root.ts) iterates the RAW entity
+  // collection, so inactive entities still get generated entity code that
+  // references these typed names. The typed model must cover them too.
+  const entity = getModelPath(model, `main.${KIT}.entity`, { only_active: false, required: false })
+  // Emit for EVERY entity that gets generated entity code: the consumer
+  // scaffold (create-sdkgen Root.ts) iterates entities WITHOUT an active
+  // filter, so inactive entities still get class files referencing these
+  // typed names. Filter on `name` (always present), NOT `active` — parity
+  // with the go emitter's fix.
+  const entityList = each(entity).filter((e: any) => e && null != e.name)
   // Derive the PascalCase Name up-front — it is set LAZILY by names(), so an
   // entity not yet named (e.g. a fieldless placeholder) would otherwise read
   // `Name = undefined` below. Parity with the go emitter's fix.
   entityList.forEach((e: any) => { if (null == e.Name) names(e, e.name) })
 
+  // Surface duplicate generated type names (two entities with the same
+  // PascalCase Name) — they would redeclare a type in statically-typed
+  // targets. Detection only; renaming is a model-level decision.
+  warnEntityTypeCollisions(entity, log, LANG)
+
   File({ name: model.const.Name + 'Types.' + target.ext }, () => {
 
     Content(`// Typed models for the ${model.const.Name} SDK.
@@ -168,7 +182,7 @@ const EntityTypes = cmp(function EntityTypes(props: any) {
         name: f.name,
         type: f.type,
         optional: false === f.req,
-      })))
+      })), log)
 
       // Per active op: a request/match type. The members and each member's
       // required/optional decision come from the shared partiality policy
@@ -182,7 +196,7 @@ const EntityTypes = cmp(function EntityTypes(props: any) {
         const typeName = opTypeName(Name, opname)
         const { items } = opRequestShape(ent, opname)
 
-        emitClass(typeName, items)
+        emitClass(typeName, items, log)
       })
     })
   })

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

@@ -64,6 +64,14 @@ const Entity = cmp(function Entity(props: any) {
             `// Typed models: see ../${model.const.Name}Types.dart ` +
             `(${entity.Name} and the per-op request/match types).`),
 
+          // dart:async (Future/Stream) and ErrUtility are only referenced by
+          // op method bodies, so an op-less entity would import them unused.
+          // Emit them only when the entity actually has operations.
+          '#OpImports': opnames.length > 0
+            ? ({ indent }: any) => Content({ indent },
+              `import 'dart:async';\nimport '../utility/ErrUtility.dart';`)
+            : '',
+
           ...opfrags,
         }
       })

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

@@ -0,0 +1,166 @@
+
+import { cmp, each, Content, canonToType, canonKey, entityIdField, opRequestShape, safeVarName, exampleVarName } from '@voxgig/sdkgen'
+
+import {
+  KIT,
+  getModelPath,
+} from '@voxgig/apidef'
+
+
+// Type names come from the shared canonToType 'dart' column (single source of truth).
+
+// A type-correct Dart literal for a field's canonical type. Strings render
+// the quoted placeholder (single-quoted, matching the generated Dart style).
+function dartLit(type: any, placeholder: string = 'example'): string {
+  const k = canonKey(type)
+  if ('INTEGER' === k || 'NUMBER' === k) return '1'
+  if ('BOOLEAN' === k) return 'true'
+  if ('ARRAY' === k) return '<dynamic>[]'
+  if ('OBJECT' === k) return '<String, dynamic>{}'
+  return `'${placeholder}'`
+}
+
+
+// Op method spellings + descriptions (language-agnostic wording).
+const OP_DESC: Record<string, { method: string, desc: string }> = {
+  load:   { method: 'load(match)',   desc: 'Load a single entity by match criteria.' },
+  list:   { method: 'list()',        desc: 'List entities, optionally matching the given criteria.' },
+  create: { method: 'create(data)',  desc: 'Create a new entity with the given data.' },
+  update: { method: 'update(data)',  desc: 'Update an existing entity.' },
+  remove: { method: 'remove(match)', desc: 'Remove the matching entity.' },
+}
+
+
+const ReadmeEntity = cmp(function ReadmeEntity(props: any) {
+  const { target } = props
+  const { model } = props.ctx$
+
+  const entity = getModelPath(model, `main.${KIT}.entity`)
+
+  const publishedEntities = each(entity)
+    .filter((entity: any) => entity.active !== false)
+
+  if (0 === publishedEntities.length) {
+    return
+  }
+
+  Content(`
+
+## Entities
+
+`)
+
+  publishedEntities.map((entity: any) => {
+    const opnames = Object.keys(entity.op || {})
+    const fields = entity.fields || []
+    // Model-driven id key: null when this entity has no id-like field.
+    const idF = entityIdField(entity)
+    const eVar = exampleVarName(entity.name, 'dart')
+
+    Content(`
+### ${entity.Name}
+
+`)
+
+    if (entity.short) {
+      Content(`${entity.short}
+
+`)
+    }
+
+    Content(`Create an instance: \`final ${eVar} = client.${entity.Name}();\`
+
+`)
+
+    if (opnames.length > 0) {
+      Content(`#### Operations
+
+| Method | Description |
+| --- | --- |
+`)
+      opnames.map((opname: string) => {
+        const info = OP_DESC[opname]
+        if (info) {
+          Content(`| \`${info.method}\` | ${info.desc} |
+`)
+        }
+      })
+
+      Content(`
+`)
+    }
+
+    if (fields.length > 0) {
+      Content(`#### Fields
+
+| Field | Type | Description |
+| --- | --- | --- |
+`)
+
+      each(fields, (field: any) => {
+        const desc = field.short || ''
+        Content(`| \`${field.name}\` | \`${canonToType(field.type, target.name)}\` | ${desc} |
+`)
+      })
+
+      Content(`
+`)
+    }
+
+    if (opnames.includes('load')) {
+      // The id key plus every REQUIRED match key (parent path params like
+      // page_id) — the same shape the runtime resolves path params from.
+      const loadItems = opRequestShape(entity, 'load').items
+        .filter((it: any) => !it.optional || it.name === idF)
+        .sort((a: any, b: any) =>
+          (a.name === idF ? 0 : 1) - (b.name === idF ? 0 : 1))
+      const loadArg = 0 < loadItems.length
+        ? `{${loadItems.map((it: any) =>
+          `'${it.name}': ${dartLit(it.type,
+            it.name === idF ? entity.name + '_id' : it.name)}`).join(', ')}}`
+        : ''
+      Content(`#### Example: Load
+
+\`\`\`dart
+final ${eVar} = await client.${entity.Name}().load(${loadArg});
+\`\`\`
+
+`)
+    }
+
+    if (opnames.includes('list')) {
+      Content(`#### Example: List
+
+\`\`\`dart
+final ${eVar}s = await client.${entity.Name}().list();
+\`\`\`
+
+`)
+    }
+
+    if (opnames.includes('create')) {
+      // Members come from the SAME shape the runtime validates
+      // (opRequestShape): every required member must appear.
+      const createItems = opRequestShape(entity, 'create').items
+        .filter((it: any) => !it.optional)
+      Content(`#### Example: Create
+
+\`\`\`dart
+final ${eVar} = await client.${entity.Name}().create({
+`)
+      createItems.map((it: any) => {
+        Content(`  '${it.name}': ${dartLit(it.type, 'example_' + it.name)},  // ${canonToType(it.type, target.name)}
+`)
+      })
+      Content(`});
+\`\`\`
+
+`)
+    }
+  })
+})
+
+
+export {
+  ReadmeEntity
+}