@voxgig/sdkgen 1.3.14 → 1.3.17

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

@@ -0,0 +1,381 @@
+
+import { cmp, each, Content, canonToType, canonKey, File, isAuthActive, entityIdField, opRequestShape, safeVarName, exampleVarName } from '@voxgig/sdkgen'
+
+import {
+  KIT,
+  getModelPath,
+} from '@voxgig/apidef'
+
+import { dartPackageName } from './Package_dart'
+
+
+// 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}'`
+}
+
+
+const OP_SIGNATURES: Record<string, { sig: string, returns: string, desc: string }> = {
+  load: {
+    sig: 'load(reqmatch, [ctrl]) -> Future<dynamic>',
+    returns: 'the entity data',
+    desc: 'Load a single entity matching the given criteria. Returns the entity data and throws on error.',
+  },
+  list: {
+    sig: 'list([reqmatch, ctrl]) -> Future<List>',
+    returns: 'a list of entities',
+    desc: 'List entities matching the given criteria. The match is optional — call `list()` with no argument to list all records. Returns a list of entity instances and throws on error.',
+  },
+  create: {
+    sig: 'create(reqdata, [ctrl]) -> Future<dynamic>',
+    returns: 'the created entity data',
+    desc: 'Create a new entity with the given data. Returns the created entity data and throws on error.',
+  },
+  update: {
+    sig: 'update(reqdata, [ctrl]) -> Future<dynamic>',
+    returns: 'the updated entity data',
+    desc: 'Update an existing entity. The data must include the entity `id`. Returns the updated entity data and throws on error.',
+  },
+  remove: {
+    sig: 'remove(reqmatch, [ctrl]) -> Future<dynamic>',
+    returns: 'the removed entity data',
+    desc: 'Remove the entity matching the given criteria. Throws on error.',
+  },
+}
+
+
+const ReadmeRef = cmp(function ReadmeRef(props: any) {
+  const { target } = props
+  const { model } = props.ctx$
+
+  const entity = getModelPath(model, `main.${KIT}.entity`)
+  const feature = getModelPath(model, `main.${KIT}.feature`)
+  const pkg = dartPackageName(model)
+
+  const publishedEntities = each(entity).filter((e: any) => e.active !== false)
+
+
+  File({ name: 'REFERENCE.md' }, () => {
+
+    Content(`# ${model.Name} ${target.title} SDK Reference
+
+Complete API reference for the ${model.Name} ${target.title} SDK.
+
+## ${model.const.Name}SDK
+
+### Constructor
+
+`)
+
+    Content(`\`\`\`dart
+import 'package:${pkg}/${model.const.Name}SDK.dart';
+
+final client = ${model.const.Name}SDK(options);
+\`\`\`
+
+Create a new SDK client instance.
+
+**Parameters:**
+
+| Name | Type | Description |
+| --- | --- | --- |
+| \`options\` | \`Map\` | SDK configuration options. |
+${isAuthActive(model) ? '| `options[\'apikey\']` | `String` | API key for authentication. |\n' : ''}| \`options['base']\` | \`String\` | Base URL for API requests. |
+| \`options['prefix']\` | \`String\` | URL prefix appended after base. |
+| \`options['suffix']\` | \`String\` | URL suffix appended after path. |
+| \`options['headers']\` | \`Map\` | Custom headers for all requests. |
+| \`options['feature']\` | \`Map\` | Feature configuration. |
+| \`options['system']\` | \`Map\` | System overrides (e.g. custom fetch). |
+
+`)
+
+
+    Content(`
+### Static Methods
+
+`)
+
+    Content(`#### \`${model.const.Name}SDK.test([testopts, sdkopts])\`
+
+Create a test client with mock features active. Both arguments may be \`null\`.
+
+\`\`\`dart
+final client = ${model.const.Name}SDK.test();
+\`\`\`
+
+`)
+
+
+    Content(`
+### Instance Methods
+
+`)
+
+
+    // Entity factory methods
+    publishedEntities.map((ent: any) => {
+      Content(`#### \`${ent.Name}([entopts])\`
+
+Create a new \`${ent.Name}Entity\` instance. Pass no argument for no initial data.
+
+`)
+    })
+
+
+    Content(`#### \`options() -> Map\`
+
+Return a deep copy of the current SDK options.
+
+#### \`utility() -> Utility\`
+
+Return the SDK utility object.
+
+#### \`direct([fetchargs]) -> Future<Map>\`
+
+Make a direct HTTP request to any API endpoint. Returns a result \`Map\` with \`ok\`, \`status\`, \`headers\`, and \`data\` (or \`err\` on failure). This escape hatch never throws — branch on \`result['ok']\`.
+
+**Parameters:**
+
+| Name | Type | Description |
+| --- | --- | --- |
+| \`fetchargs['path']\` | \`String\` | URL path with optional \`{param}\` placeholders. |
+| \`fetchargs['method']\` | \`String\` | HTTP method (default: \`'GET'\`). |
+| \`fetchargs['params']\` | \`Map\` | Path parameter values. |
+| \`fetchargs['query']\` | \`Map\` | Query string parameters. |
+| \`fetchargs['headers']\` | \`Map\` | Request headers (merged with defaults). |
+| \`fetchargs['body']\` | \`dynamic\` | Request body (maps are JSON-serialized). |
+
+**Returns:** \`Future<Map>\`
+
+#### \`prepare([fetchargs]) -> Future\`
+
+Prepare a fetch definition without sending. Returns the \`fetchdef\` (or an error value on failure).
+
+`)
+
+
+    // Entity reference sections
+    publishedEntities.map((ent: any) => {
+      const opnames = Object.keys(ent.op || {})
+      const fields = ent.fields || []
+      const idF = entityIdField(ent)
+      const eVar = exampleVarName(ent.name, 'dart')
+
+      Content(`
+---
+
+## ${ent.Name}Entity
+
+`)
+
+      if (ent.short) {
+        Content(`${ent.short}
+
+`)
+      }
+
+      Content(`\`\`\`dart
+final ${eVar} = client.${ent.Name}();
+\`\`\`
+
+`)
+
+
+      // Field schema
+      if (fields.length > 0) {
+        Content(`### Fields
+
+| Field | Type | Required | Description |
+| --- | --- | --- | --- |
+`)
+        each(fields, (field: any) => {
+          const req = field.req ? 'Yes' : 'No'
+          const desc = field.short || ''
+          Content(`| \`${field.name}\` | \`${canonToType(field.type, target.name)}\` | ${req} | ${desc} |
+`)
+        })
+
+        Content(`
+`)
+
+        // Field operations breakdown
+        const hasFieldOps = fields.some((f: any) => f.op && Object.keys(f.op).length > 0)
+        if (hasFieldOps) {
+          const opcols = ['load', 'list', 'create', 'update', 'remove']
+            .filter((op: string) => opnames.includes(op) && ent.op[op]?.active !== false)
+          Content(`### Field Usage by Operation
+
+| Field | ${opcols.join(' | ')} |
+| --- | ${opcols.map(() => '---').join(' | ')} |
+`)
+          each(fields, (field: any) => {
+            const fops = field.op || {}
+            const cols = opcols.map((op: string) => {
+              const fop = fops[op]
+              if (null == fop) return '-'
+              if (fop.active === false) return '-'
+              return 'Yes'
+            })
+            Content(`| \`${field.name}\` | ${cols.join(' | ')} |
+`)
+          })
+
+          Content(`
+`)
+        }
+      }
+
+
+      // Operation details
+      if (opnames.length > 0) {
+        Content(`### Operations
+
+`)
+
+        opnames.map((opname: string) => {
+          const info = OP_SIGNATURES[opname]
+          if (!info) return
+
+          Content(`#### \`${info.sig}\`
+
+${info.desc}
+
+`)
+
+          if ('load' === opname || 'remove' === opname) {
+            const matchItems = opRequestShape(ent, opname).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 arg = 0 < matchItems.length
+              ? `{${matchItems.map((it: any) =>
+                `'${it.name}': ${dartLit(it.type,
+                  it.name === idF ? ent.name + '_id' : it.name)}`).join(', ')}}`
+              : ''
+            Content(`\`\`\`dart
+final result = await client.${ent.Name}().${opname}(${arg});
+\`\`\`
+
+`)
+          }
+          else if ('list' === opname) {
+            Content(`\`\`\`dart
+final results = await client.${ent.Name}().list();
+for (final ${eVar} in results) {
+  print(${eVar}.data());
+}
+\`\`\`
+
+`)
+          }
+          else if ('create' === opname) {
+            const createItems = opRequestShape(ent, 'create').items
+              .filter((it: any) => !it.optional)
+            Content(`\`\`\`dart
+final result = await client.${ent.Name}().create({
+`)
+            createItems.map((it: any) => {
+              Content(`  '${it.name}': ${dartLit(it.type, 'example_' + it.name)},  // ${canonToType(it.type, target.name)}
+`)
+            })
+            Content(`});
+\`\`\`
+
+`)
+          }
+          else if ('update' === opname) {
+            const updateItems = opRequestShape(ent, 'update').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 updateLines = updateItems.map((it: any) =>
+              `  '${it.name}': ${dartLit(it.type,
+                it.name === idF ? ent.name + '_id' : it.name)},\n`).join('')
+            Content(`\`\`\`dart
+final result = await client.${ent.Name}().update({
+${updateLines}  // Fields to update
+});
+\`\`\`
+
+`)
+          }
+        })
+      }
+
+
+      // Common methods
+      Content(`### Common Methods
+
+#### \`data([d]) -> Map\`
+
+Get the entity data, or set it when passed an argument.
+
+#### \`match([m]) -> Map\`
+
+Get the entity match criteria, or set it when passed an argument.
+
+#### \`make() -> Entity\`
+
+Create a new \`${ent.Name}Entity\` instance with the same options.
+
+#### \`entopts() -> Map\`
+
+Return the entity options.
+
+`)
+    })
+
+
+    // Features section
+    const activeFeatures = each(feature).filter((f: any) => f.active)
+    if (activeFeatures.length > 0) {
+      Content(`
+---
+
+## Features
+
+| Feature | Version | Description |
+| --- | --- | --- |
+`)
+
+      activeFeatures.map((f: any) => {
+        Content(`| \`${f.name}\` | ${f.version || '0.0.1'} | ${f.title || ''} |
+`)
+      })
+
+      Content(`
+
+Features are activated via the \`feature\` option:
+
+`)
+
+      Content(`\`\`\`dart
+final client = ${model.const.Name}SDK({
+  'feature': {
+`)
+      activeFeatures.map((f: any) => {
+        Content(`    '${f.name}': {'active': true},
+`)
+      })
+      Content(`  },
+});
+\`\`\`
+
+`)
+    }
+
+  })
+})
+
+
+export {
+  ReadmeRef
+}

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

@@ -0,0 +1,24 @@
+
+import { cmp, Content } from '@voxgig/sdkgen'
+
+
+const ReadmeTopHowto = cmp(function ReadmeTopHowto(props: any) {
+  const { target } = props
+
+  Content(`**Dart:**
+\`\`\`dart
+final result = await client.direct({
+  'path': '/api/resource/{id}',
+  'method': 'GET',
+  'params': {'id': 'example'},
+});
+\`\`\`
+
+`)
+
+})
+
+
+export {
+  ReadmeTopHowto
+}

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

@@ -0,0 +1,95 @@
+
+import { cmp, Content, isAuthActive, envName, canonKey, entityIdField, opRequestShape, safeVarName, exampleVarName } from '@voxgig/sdkgen'
+
+import {
+  KIT,
+  getModelPath,
+  nom,
+} from '@voxgig/apidef'
+
+import { dartPackageName } from './Package_dart'
+
+
+// A type-correct, executable Dart literal for a param: numeric/boolean/
+// array/object params render a typed literal; 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}'`
+}
+
+
+const ReadmeTopQuick = cmp(function ReadmeTopQuick(props: any) {
+  const { target, ctx$: { model } } = props
+
+  const entity = getModelPath(model, `main.${KIT}.entity`)
+  const pkg = dartPackageName(model)
+
+  const exampleEntity = Object.values(entity).find((e: any) => e.active !== false) as any
+
+  const authActive = isAuthActive(model)
+  const importIO = authActive ? `import 'dart:io';\n` : ''
+  const ctor = authActive
+    ? `${model.const.Name}SDK({\n    'apikey': Platform.environment['${envName(model)}_APIKEY'],\n  })`
+    : `${model.const.Name}SDK()`
+
+  Content(`\`\`\`dart
+${importIO}import 'package:${pkg}/${model.const.Name}SDK.dart';
+
+Future<void> main() async {
+  final client = ${ctor};
+
+`)
+
+  if (exampleEntity) {
+    const eName = nom(exampleEntity, 'Name')
+    const eVar = exampleVarName(eName.toLowerCase(), 'dart')
+    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 no match argument.
+    const idF = entityIdField(exampleEntity)
+
+    if (opnames.includes('list')) {
+      Content(`  // List all ${eName.toLowerCase()}s (returns a list of entities, throws on error)
+  final ${eVar}s = await client.${eName}().list();
+  for (final item in ${eVar}s) {
+    print(item.data());
+  }
+`)
+    }
+
+    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
+        ? `{${loadItems.map((it: any) =>
+          `'${it.name}': ${dartLit(it.type,
+            it.name === idF ? 'example_id' : 'example_' + it.name)}`).join(', ')}}`
+        : ''
+      Content(`
+  // Load a specific ${eName.toLowerCase()} (returns the record, throws on error)
+  final ${eVar} = await client.${eName}().load(${loadArg});
+  print(${eVar});
+`)
+    }
+  }
+
+  Content(`}
+\`\`\`
+`)
+
+})
+
+
+export {
+  ReadmeTopQuick
+}

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

@@ -0,0 +1,78 @@
+
+import { cmp, Content, canonKey, entityIdField, pickExampleEntity, opRequestShape, safeVarName, exampleVarName } from '@voxgig/sdkgen'
+
+import {
+  KIT,
+  getModelPath,
+  nom,
+} from '@voxgig/apidef'
+
+import { dartPackageName } from './Package_dart'
+
+
+// A type-correct Dart literal for a field's canonical type.
+function dartLit(type: any): 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 "'example'"
+}
+
+
+const ReadmeTopTest = cmp(function ReadmeTopTest(props: any) {
+  const { target, ctx$: { model } } = props
+
+  const entity = getModelPath(model, `main.${KIT}.entity`)
+  const pkg = dartPackageName(model)
+
+  // 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(`\`\`\`dart
+import 'package:${pkg}/${model.const.Name}SDK.dart';
+
+Future<void> main() async {
+  final client = ${model.const.Name}SDK.test();
+`)
+
+  if (exampleEntity && primaryOp) {
+    const eName = nom(exampleEntity, 'Name')
+    const idF = entityIdField(exampleEntity)
+    const isMatchOp = 'load' === primaryOp || 'remove' === primaryOp
+    let arg = ''
+    if (isMatchOp) {
+      // Every REQUIRED match key (id first).
+      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
+        ? `{${items.map((it: any) =>
+          `'${it.name}': ${it.name === idF ? "'test01'" : dartLit(it.type)}`).join(', ')}}`
+        : ''
+    } 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 = `{${chosen.map((it: any) => `'${it.name}': ${dartLit(it.type)}`).join(', ')}}`
+    }
+    const eVar = exampleVarName(eName.toLowerCase(), 'dart') + ('list' === primaryOp ? 's' : '')
+    Content(`  final ${eVar} = await client.${eName}().${primaryOp}(${arg});
+  print(${eVar});
+`)
+  }
+
+  Content(`}
+\`\`\`
+`)
+
+})
+
+
+export {
+  ReadmeTopTest
+}

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

@@ -96,6 +96,58 @@ const TestEntity = cmp(function TestEntity(props: any) {
                 a[1] + n[1]))), 2)
         ])
 
+        // The stream test drives the `list` op; only emit it when the entity
+        // actually has a list op (a create-only entity like a *_result has no
+        // list endpoint, so ent.stream('list', …) would throw point_no_points).
+        const flowHasList = Object.values(basicflow.step)
+          .some((s: any) => 'list' === s.op)
+        Slot({ name: 'stream' }, () => {
+          if (!flowHasList) {
+            return
+          }
+          Content(`test('stream', (t) async {
+      // stream() runs the list op through the full pipeline and yields each
+      // result item. Seed two entities via test mode; with the \`streaming\`
+      // feature active it yields the feature's incremental items, else it
+      // falls back to the materialised items — either way every item yields.
+      final seed = <String, dynamic>{
+        'entity': {
+          '${entity.name}': {
+            'strm01': <String, dynamic>{'id': 'strm01'},
+            'strm02': <String, dynamic>{'id': 'strm02'},
+          }
+        }
+      };
+
+      final sdkopts = <String, dynamic>{};
+      if (null != config.feature['streaming']) {
+        sdkopts['feature'] = {
+          'streaming': {'active': true}
+        };
+      }
+
+      final testsdk = ${model.Name}SDK.test(seed, sdkopts);
+      final ent = testsdk.${nom(entity, 'Name')}();
+
+      final seen = [];
+      await for (final item in ent.stream('list', <String, dynamic>{})) {
+        seen.add(item);
+      }
+      equal(2, seen.length);
+
+      // Fallback: with streaming inactive, stream() still yields both items
+      // from the materialised result.
+      final plainsdk = ${model.Name}SDK.test(seed);
+      final plainent = plainsdk.${nom(entity, 'Name')}();
+      final seen2 = [];
+      await for (final item in plainent.stream('list', <String, dynamic>{})) {
+        seen2.add(item);
+      }
+      equal(2, seen2.length);
+    });
+`)
+        })
+
         Slot({ name: 'basicSetup' }, () => {
           Content(`
 Map<String, dynamic> basicSetup([dynamic extra]) {

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

@@ -14,6 +14,7 @@ import { cmp, each, snakify, Folder, File, Content } from '@voxgig/sdkgen'
 
 import { TestDirect } from './TestDirect_dart'
 import { TestEntity } from './TestEntity_dart'
+import { ReadmeExamplesTest } from './ReadmeExamplesTest_dart'
 
 
 const Test = cmp(function Test(props: any) {
@@ -41,6 +42,7 @@ import 'pipeline_test.dart' as pipeline_test;
 import 'feature_test.dart' as feature_test;
 import 'netsim_test.dart' as netsim_test;
 import 'custom_test.dart' as custom_test;
+import 'readme_examples_test.dart' as readme_examples_test;
 `)
 
       each(entity, (ent: ModelEntity) => {
@@ -62,6 +64,7 @@ Future<void> main() async {
   feature_test.tests();
   netsim_test.tests();
   custom_test.tests();
+  readme_examples_test.tests();
 `)
 
       each(entity, (ent: ModelEntity) => {
@@ -83,6 +86,9 @@ Future<void> main() async {
 `)
     })
 
+    // Documentation dart-examples presence & completeness gate.
+    ReadmeExamplesTest({ target })
+
     Folder({ name: 'entity' }, () => {
       each(entity, (ent: ModelEntity) => {
         TestEntity({ target, entity: ent })

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

@@ -1,10 +1,8 @@
 
 // ignore_for_file: non_constant_identifier_names
 
-import 'dart:async';
-
+// #OpImports
 import '../ProjectNameEntityBase.dart';
-import '../utility/ErrUtility.dart';
 
 // #TypeImports