@voxgig/sdkgen 4.34.0 → 4.34.1

package/project/.sdk/src/cmp/elixir/PrepareAuth_elixir.ts

@@ -114,11 +114,11 @@ end
     ? `      query = S.getprop(spec, "query")`
     : `      headers = S.getprop(spec, "headers")`
 
-  const clear = query
-    ? 'S.delprop(query, @cred_name)'
+  const clear = (name: string) => query
+    ? `S.delprop(query, ${name})`
     : cookie
-      ? 'apply_cookie(headers, nil)'
-      : 'S.delprop(headers, @cred_name)'
+      ? `apply_cookie(headers, ${name}, nil)`
+      : `S.delprop(headers, ${name})`
 
   const preamble = `  def prepare_auth_impl(ctx) do
     spec = S.getprop(ctx, "spec")
@@ -131,9 +131,16 @@ ${bag}
 
       # Public APIs that need no auth omit the options.auth block entirely.
       if S.getprop(options, "auth") == nil do
-        ${clear}
+        ${clear('@cred_name')}
         {spec, nil}
       else
+        name = auth_name(options)
+
+        # A credential left under the declared name would travel beside the renamed one.
+        if name != @cred_name do
+          ${clear('@cred_name')}
+        end
+
         apikey = S.getprop(options, @option_apikey, @not_found)
 
 `
@@ -151,7 +158,7 @@ ${bag}
           no_secret = not is_binary(secret) or secret == @not_found or secret == ""
 
           if no_apikey do
-            S.delprop(headers, @cred_name)
+            S.delprop(headers, name)
           else
             ap = S.getpath(options, "auth.prefix")
             auth_prefix = if is_binary(ap), do: ap, else: ""
@@ -160,13 +167,13 @@ ${bag}
             # own registration covers.
             ${spec.Name}.Utility.clean_add(ctx, b64)
             hv = if auth_prefix != "", do: auth_prefix <> " " <> b64, else: b64
-            S.setprop(headers, @cred_name, hv)
+            S.setprop(headers, name, hv)
           end
         else
-${indent(place(spec, clear), 1)}
+${indent(place(spec, clear('name')), 1)}
         end
 `
-    : place(spec, clear)
+    : place(spec, clear('name'))
 
   return head + attrs + preamble + body + `
         {spec, nil}
@@ -191,7 +198,7 @@ function place(spec: AuthSpec, clear: string): string {
           # thing any API reads: the prefix is a header convention, so
           # options.auth.prefix is dropped here deliberately rather than
           # silently concatenated.
-          S.setprop(query, @cred_name, apikey_val)
+          S.setprop(query, name, apikey_val)
         end
 `
   }
@@ -200,7 +207,7 @@ function place(spec: AuthSpec, clear: string): string {
     return guard + `          apikey_val = if is_binary(apikey), do: apikey, else: ""
           # NO PREFIX IN A COOKIE either - a cookie carries a bare
           # \`name=value\` pair, not a header's scheme-prefixed credential.
-          apply_cookie(headers, apikey_val)
+          apply_cookie(headers, name, apikey_val)
         end
 `
   }
@@ -210,14 +217,24 @@ function place(spec: AuthSpec, clear: string): string {
           apikey_val = if is_binary(apikey), do: apikey, else: ""
           # Empty prefix (raw apiKey credential) must not add a leading space.
           hv = if auth_prefix != "", do: auth_prefix <> " " <> apikey_val, else: apikey_val
-          S.setprop(headers, @cred_name, hv)
+          S.setprop(headers, name, hv)
         end
 `
 }
 
 
 function helpers(spec: AuthSpec): string {
-  const optsMap = `  # The client's options as a MAP, cloned. The clone is load-bearing: the
+  const authName = `  # The client's auth.name option, when set, replaces the name the API declares.
+  defp auth_name(options) do
+    case S.getpath(options, "auth.name") do
+      given when is_binary(given) and given != "" -> ${'header' === spec.where ? 'String.downcase(given)' : 'given'}
+      _ -> @cred_name
+    end
+  end
+
+`
+
+  const optsMap = authName + `  # The client's options as a MAP, cloned. The clone is load-bearing: the
   # secrets feature rewrites options.apikey on the live client, and
   # prepare_auth must read a snapshot rather than the node the feature is
   # mutating. Same body as ${spec.Name}.Utility's own private opts_map/1.
@@ -236,27 +253,20 @@ function helpers(spec: AuthSpec): string {
   // cookies the caller set - so the pair is spliced in and out rather than
   // the header assigned over. Splicing also makes this idempotent: a
   // retried request cannot end up carrying the credential twice.
-  return optsMap + `  # The cookie header minus our own pair, every other cookie untouched.
-  defp cookies_without_cred(headers) do
+  return optsMap + `  # The cookie header minus the named pair, every other cookie untouched.
+  defp cookies_without_cred(headers, name) do
     existing = S.getprop(headers, @cookie_header)
 
     if is_binary(existing) and existing != "" do
-      existing
-      |> String.split(";")
-      |> Enum.map(&String.trim/1)
-      |> Enum.reject(fn piece ->
-        piece == "" or piece == @cred_name or
-          String.starts_with?(piece, @cred_name <> "=")
-      end)
-      |> Enum.join("; ")
+      Enum.join(${spec.Name}.Utility.cookie_keep(existing, [name]), "; ")
     else
       ""
     end
   end
 
-  # Remove our pair, leaving the rest of the cookie header in place.
-  defp apply_cookie(headers, nil) do
-    rest = cookies_without_cred(headers)
+  # Remove the named pair, leaving the rest of the cookie header in place.
+  defp apply_cookie(headers, name, nil) do
+    rest = cookies_without_cred(headers, name)
 
     if rest == "" do
       S.delprop(headers, @cookie_header)
@@ -265,10 +275,10 @@ function helpers(spec: AuthSpec): string {
     end
   end
 
-  # Set our pair, leaving the rest of the cookie header in place.
-  defp apply_cookie(headers, value) do
-    rest = cookies_without_cred(headers)
-    pair = @cred_name <> "=" <> value
+  # Set the named pair, leaving the rest of the cookie header in place.
+  defp apply_cookie(headers, name, value) do
+    rest = cookies_without_cred(headers, name)
+    pair = name <> "=" <> value
     S.setprop(headers, @cookie_header, if(rest == "", do: pair, else: rest <> "; " <> pair))
   end
 

package/project/.sdk/src/cmp/elixir/ReadmeEntity_elixir.ts

@@ -1,5 +1,5 @@
 
-import { cmp, each, Content, canonToType, entityIdField, opRequestShape } from '@voxgig/sdkgen'
+import { cmp, each, Content, canonToType, entityIdField, opRequestShape, opNeedsAction, elixirAccessor, entityCollection, exampleVarName } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -18,6 +18,7 @@ const OP_DESC: Record<string, { method: string, desc: string }> = {
   list:   { method: 'list(entity)',         desc: 'List entities, optionally matching the given criteria.' },
   create: { method: 'create(entity, data)', desc: 'Create a new entity with the given data.' },
   update: { method: 'update(entity, data)', desc: 'Update an existing entity.' },
+  patch:  { method: 'patch(entity, data)',  desc: 'Change part of an existing entity.' },
   remove: { method: 'remove(entity, match)', desc: 'Remove the matching entity.' },
 }
 
@@ -47,8 +48,11 @@ takes an entity handle built from the client:
 
   publishedEntities.map((entity: any) => {
     const EName = entity.Name
-    const eVar = entity.name
+    const eVar = exampleVarName(entity.name, 'elixir')
+    const eCall = elixirAccessor(entity, entityCollection(model))
     const opnames = Object.keys(entity.op || {})
+    // An op that needs an action has no plain call to show.
+    const callable = opnames.filter((o: string) => !opNeedsAction(entity.op[o]))
     const fields = Object.values(entity.fields || {})
     const idF = entityIdField(entity)
 
@@ -63,7 +67,7 @@ takes an entity handle built from the client:
 `)
     }
 
-    Content(`Create a handle: \`${eVar} = ${Name}.${eVar}(sdk)\`
+    Content(`Create a handle: \`${eVar} = ${Name}.${eCall}(sdk)\`
 
 `)
 
@@ -102,7 +106,7 @@ takes an entity handle built from the client:
 `)
     }
 
-    if (opnames.includes('load')) {
+    if (callable.includes('load')) {
       const loadItems = opRequestShape(entity, 'load').items
         .filter((it: any) => !it.optional || it.name === idF)
         .sort((a: any, b: any) =>
@@ -115,25 +119,25 @@ takes an entity handle built from the client:
       Content(`#### Example: Load
 
 \`\`\`elixir
-${eVar} = ${Name}.${eVar}(sdk)
+${eVar} = ${Name}.${eCall}(sdk)
 record = ${Name}.Entity.${EName}.load(${eVar}, ${loadArg})
 \`\`\`
 
 `)
     }
 
-    if (opnames.includes('list')) {
+    if (callable.includes('list')) {
       Content(`#### Example: List
 
 \`\`\`elixir
-${eVar} = ${Name}.${eVar}(sdk)
+${eVar} = ${Name}.${eCall}(sdk)
 records = ${Name}.Entity.${EName}.list(${eVar})
 \`\`\`
 
 `)
     }
 
-    if (opnames.includes('create')) {
+    if (callable.includes('create')) {
       // Members come from the SAME shape the runtime validates
       // (opRequestShape): every required member must appear — with a real,
       // executable literal.
@@ -142,7 +146,7 @@ records = ${Name}.Entity.${EName}.list(${eVar})
       Content(`#### Example: Create
 
 \`\`\`elixir
-${eVar} = ${Name}.${eVar}(sdk)
+${eVar} = ${Name}.${eCall}(sdk)
 record = ${Name}.Entity.${EName}.create(${eVar}, ${Name}.Helpers.deep(%{
 `)
       createItems.map((it: any) => {

package/project/.sdk/src/cmp/elixir/ReadmeHowto_elixir.ts

@@ -1,5 +1,5 @@
 
-import { cmp, Content, isAuthActive, envName, entityIdField, pickExampleEntity, opRequestShape } from '@voxgig/sdkgen'
+import { cmp, Content, isAuthActive, envName, entityIdField, pickExampleEntity, opRequestShape, elixirAccessor, entityCollection, exampleVarName } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -20,13 +20,14 @@ const ReadmeHowto = cmp(function ReadmeHowto(props: any) {
   // when NO entity exposes any op (a direct()-only SDK).
   const { entity: exampleEntity, primaryOp } = pickExampleEntity(entity)
   const eName = exampleEntity ? nom(exampleEntity, 'Name') : 'Entity'
-  const eVar = exampleEntity ? exampleEntity.name : 'entity'
+  const eVar = exampleEntity ? exampleVarName(exampleEntity.name, 'elixir') : 'entity'
+  const eCall = exampleEntity ? elixirAccessor(exampleEntity, entityCollection(model)) : 'entity'
   const idF = exampleEntity ? entityIdField(exampleEntity) : null
   const isMatchOp = 'load' === primaryOp || 'remove' === primaryOp
   let testArg = 'H.deep(%{})'
   if (exampleEntity && isMatchOp) {
     testArg = idF ? `H.deep(%{"${idF}" => "test01"})` : 'H.deep(%{})'
-  } else if (exampleEntity && ('create' === primaryOp || 'update' === primaryOp)) {
+  } else if (exampleEntity && ('create' === primaryOp || 'update' === primaryOp || 'patch' === primaryOp)) {
     const items = opRequestShape(exampleEntity, primaryOp).items
       .filter((it: any) => it.name !== idF && it.name !== 'id')
     const required = items.filter((it: any) => !it.optional)
@@ -36,8 +37,8 @@ const ReadmeHowto = cmp(function ReadmeHowto(props: any) {
 
   const resVar = 'list' === primaryOp ? 'records' : 'record'
   const testModeExample = primaryOp
-    ? `# Entity ops return the bare record (raise on error).
-${eVar} = ${Name}.${eVar}(sdk)
+    ? `# Entity ops return the entity, and list one per record (raise on error).
+${eVar} = ${Name}.${eCall}(sdk)
 ${resVar} = ${Name}.Entity.${eName}.${primaryOp}(${eVar}, ${testArg})
 IO.inspect(${resVar})`
     : `result = ${Name}.direct(sdk, H.deep(%{"path" => "/api/resource", "method" => "GET"}))

package/project/.sdk/src/cmp/elixir/ReadmeInstall_elixir.ts

@@ -33,9 +33,9 @@ mix deps.get
 
   // Publish pending: not yet on Hex. Install from the git release tag or a
   // local path checkout.
-  const { repoUrl, releasesUrl } = repoInfo(model)
+  const { hostName, repoUrl, tagsUrl } = repoInfo(model)
   Content(`This package is not yet published to [Hex](https://hex.pm). Install it from
-the GitHub release tag (\`${target.name}/vX.Y.Z\`, see [Releases](${releasesUrl}))
+the ${hostName} release tag (\`${target.name}/vX.Y.Z\`, see [Tags](${tagsUrl}))
 by adding a git dependency to your \`mix.exs\`:
 
 \`\`\`elixir

package/project/.sdk/src/cmp/elixir/ReadmeIntro_elixir.ts

@@ -1,5 +1,5 @@
 
-import { cmp, Content } from '@voxgig/sdkgen'
+import { cmp, Content, elixirAccessor, entityCollection, modelText } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -10,7 +10,7 @@ import {
 
 const ReadmeIntro = cmp(function ReadmeIntro(props: any) {
   const { target, ctx$: { model } } = props
-  const info = (model.main && model.main.kit && model.main.kit.info) || {}
+  const info = modelText(model)
   const tagline = info.tagline || ''
 
   Content(`# ${model.Name} ${target.title} SDK
@@ -30,13 +30,13 @@ following idiomatic, functional Elixir conventions.
   const exampleEntity = Object.values(entity || {})
     .find((e: any) => e.active !== false) as any
   const example = exampleEntity
-    ? `for example \`${model.const.Name}.${exampleEntity.name}(sdk)\` — each`
+    ? `for example \`${model.const.Name}.${elixirAccessor(exampleEntity, entityCollection(model))}(sdk)\` — each`
     : 'each'
 
   // Model-driven op list — only the operations the active entities actually
   // expose (a read-only entity has just list+load); never claim
   // create/update/remove exist when no entity has them.
-  const CANON_OPS = ['list', 'load', 'create', 'update', 'remove']
+  const CANON_OPS = ['list', 'load', 'create', 'update', 'patch', 'remove']
   const opSet = new Set<string>()
   Object.values(entity || {}).forEach((e: any) => {
     if (!e || e.active === false) return

package/project/.sdk/src/cmp/elixir/ReadmeModel_elixir.ts

@@ -1,5 +1,5 @@
 
-import { cmp, each, Content, isAuthActive } from '@voxgig/sdkgen'
+import { cmp, each, Content, isAuthActive, elixirAccessor, entityCollection } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -21,13 +21,14 @@ const ReadmeModel = cmp(function ReadmeModel(props: any) {
   entityList.forEach((e: any) => Object.keys(e.op || {})
     .forEach((o: string) => { if (e.op[o] && e.op[o].active !== false) opUnion.add(o) }))
   const opRowDefs: Record<string, string> = {
-    load: '| `load` | `(entity, reqmatch, ctrl \\\\ nil) :: map()` | Load a single entity by match criteria. Raises on error. |',
-    list: '| `list` | `(entity, reqmatch \\\\ nil, ctrl \\\\ nil) :: list()` | List entities matching the criteria. Raises on error. |',
-    create: '| `create` | `(entity, reqdata, ctrl \\\\ nil) :: map()` | Create a new entity. Raises on error. |',
-    update: '| `update` | `(entity, reqdata, ctrl \\\\ nil) :: map()` | Update an existing entity. Raises on error. |',
-    remove: '| `remove` | `(entity, reqmatch \\\\ nil, ctrl \\\\ nil) :: map()` | Remove an entity. Raises on error. |',
+    load: '| `load` | `(entity, reqmatch, ctrl \\\\ nil) :: map()` | Load a single entity by match criteria, and return it. Raises on error. |',
+    list: '| `list` | `(entity, reqmatch \\\\ nil, ctrl \\\\ nil) :: list()` | List entities matching the criteria, one per record. Raises on error. |',
+    create: '| `create` | `(entity, reqdata, ctrl \\\\ nil) :: map()` | Create a new entity, and return it. Raises on error. |',
+    update: '| `update` | `(entity, reqdata, ctrl \\\\ nil) :: map()` | Update an existing entity, and return it. Raises on error. |',
+    patch: '| `patch` | `(entity, reqdata, ctrl \\\\ nil) :: map()` | Change part of an existing entity, and return it. Raises on error. |',
+    remove: '| `remove` | `(entity, reqmatch \\\\ nil, ctrl \\\\ nil) :: map()` | Remove an entity, and return it marked as deleted. Raises on error. |',
   }
-  const opRows = ['load', 'list', 'create', 'update', 'remove']
+  const opRows = ['load', 'list', 'create', 'update', 'patch', 'remove']
     .filter((o) => opUnion.has(o)).map((o) => opRowDefs[o]).join('\n')
 
   const apikeyOptionRow = isAuthActive(model)
@@ -72,7 +73,7 @@ Creates a test-mode client with mock transport. Both arguments may be \`nil\`.
 
   each(entityList, (ent: any) => {
     const article = /^[aeiou]/i.test(ent.Name) ? 'an' : 'a'
-    Content(`| \`${ent.name}\` | \`(client, entopts \\\\ nil) :: entity\` | Create ${article} ${ent.Name} entity handle. |
+    Content(`| \`${elixirAccessor(ent, entityCollection(model))}\` | \`(client, entopts \\\\ nil) :: entity\` | Create ${article} ${ent.Name} entity handle. |
 `)
   })
 
@@ -93,9 +94,10 @@ ${opRows}
 
 ### Result shape
 
-Entity operations return the bare result data (a value node — a map for
-single-entity ops, a list for \`list\`) and raise a \`${Name}.Error\` on
-failure. Wrap calls in \`try\`/\`rescue\` to handle errors.
+Entity operations return the entity, and \`list\` a list of entities, one per
+record; an entity module's \`data_get/1\` reads an entity's record. They raise
+a \`${Name}.Error\` on failure, so wrap calls in \`try\`/\`rescue\` to handle
+errors.
 
 The \`direct/2\` escape hatch never raises — it returns a result node you
 branch on via \`Voxgig.Struct.getprop(result, "ok")\`:

package/project/.sdk/src/cmp/elixir/ReadmeQuick_elixir.ts

@@ -1,5 +1,5 @@
 
-import { cmp, Content, isAuthActive, envName, opRequestShape, entityIdField, entityDataIdField, entityOps } from '@voxgig/sdkgen'
+import { cmp, Content, isAuthActive, envName, opRequestShape, entityIdField, entityDataIdField, entityOps, elixirAccessor, entityCollection, exampleVarName } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -46,7 +46,8 @@ sdk = ${ctor}
   if (exampleEntity) {
     const eName = nom(exampleEntity, 'Name')
     const article = /^[aeiou]/i.test(eName) ? 'an' : 'a'
-    const eVar = exampleEntity.name
+    const eVar = exampleVarName(exampleEntity.name, 'elixir')
+    const eCall = elixirAccessor(exampleEntity, entityCollection(model))
     const opnames = entityOps(exampleEntity)
     const idF = entityIdField(exampleEntity)
     const dataIdF = entityDataIdField(exampleEntity)
@@ -54,11 +55,12 @@ sdk = ${ctor}
     if (opnames.includes('list')) {
       Content(`### 2. List ${eName.toLowerCase()} records
 
-\`list/2\` returns a list value node and raises on error.
+\`list/2\` returns a list of entities, one per record, and raises on error;
+\`data_get/1\` reads an entity's record.
 
 \`\`\`elixir
 try do
-  ${eVar} = ${Name}.${eVar}(sdk)
+  ${eVar} = ${Name}.${eCall}(sdk)
   records = ${Name}.Entity.${eName}.list(${eVar})
   IO.inspect(records)
 rescue
@@ -72,7 +74,8 @@ end
     if (nestedEntity) {
       const neName = nom(nestedEntity, 'Name')
       const neArticle = /^[aeiou]/i.test(neName) ? 'an' : 'a'
-      const neVar = nestedEntity.name
+      const neVar = exampleVarName(nestedEntity.name, 'elixir')
+      const neCall = elixirAccessor(nestedEntity, entityCollection(model))
 
       const neIdF = entityIdField(nestedEntity)
       const neRequired = opRequestShape(nestedEntity, 'load').items
@@ -89,11 +92,12 @@ end
       Content(`### 3. Load ${neArticle} ${neName.toLowerCase()}
 
 ${neName} is nested under ${parentName}, so provide the \`${parentParam}\`.
-\`load/2\` returns the bare record and raises on error.
+\`load/2\` returns the entity and raises on error; \`data_get/1\` reads its
+record.
 
 \`\`\`elixir
 try do
-  ${neVar} = ${Name}.${neVar}(sdk)
+  ${neVar} = ${Name}.${neCall}(sdk)
   record = ${Name}.Entity.${neName}.load(${neVar}, H.deep(%{${neMatch.join(', ')}}))
   IO.inspect(record)
 rescue
@@ -116,11 +120,12 @@ end
 
       Content(`### 3. Load ${article} ${eName.toLowerCase()}
 
-\`load/2\` returns the bare record and raises on error.
+\`load/2\` returns the entity and raises on error; \`data_get/1\` reads its
+record.
 
 \`\`\`elixir
 try do
-  ${eVar} = ${Name}.${eVar}(sdk)
+  ${eVar} = ${Name}.${eCall}(sdk)
   record = ${Name}.Entity.${eName}.load(${eVar}, ${loadArg})
   IO.inspect(record)
 rescue
@@ -153,15 +158,16 @@ end
       ? `Voxgig.Struct.getprop(created, "${dataIdF}")`
       : elixirLit(idParamType(opname), 'example_id')
 
-    if (opnames.includes('create') || opnames.includes('update') || opnames.includes('remove')) {
+    if (opnames.includes('create') || opnames.includes('update') || opnames.includes('patch') ||
+      opnames.includes('remove')) {
       Content(`### 4. Create, update, and remove
 
 \`\`\`elixir
-${eVar} = ${Name}.${eVar}(sdk)
+${eVar} = ${Name}.${eCall}(sdk)
 
 `)
       if (opnames.includes('create')) {
-        Content(`# Create — returns the bare created record
+        Content(`# Create — returns the created entity
 created = ${Name}.Entity.${eName}.create(${eVar}, H.deep(%{${examplePairs('create').join(', ')}}))
 
 `)
@@ -171,6 +177,13 @@ created = ${Name}.Entity.${eName}.create(${eVar}, H.deep(%{${examplePairs('creat
         Content(`# Update
 ${Name}.Entity.${eName}.update(${eVar}, H.deep(%{${updatePairs.join(', ')}}))
 
+`)
+      }
+      if (opnames.includes('patch')) {
+        const patchPairs = (idF ? [`"${idF}" => ${idValueFor('patch')}`] : []).concat(examplePairs('patch'))
+        Content(`# Patch — sends only the fields given
+${Name}.Entity.${eName}.patch(${eVar}, H.deep(%{${patchPairs.join(', ')}}))
+
 `)
       }
       if (opnames.includes('remove')) {

package/project/.sdk/src/cmp/elixir/ReadmeRef_elixir.ts

@@ -1,5 +1,5 @@
 
-import { cmp, each, Content, canonToType, File, isAuthActive, entityIdField, opRequestShape , targetFeatures } from '@voxgig/sdkgen'
+import { cmp, each, Content, canonToType, File, isAuthActive, entityIdField, opRequestShape , targetFeatures, opNeedsAction, bodyNote, elixirAccessor, entityCollection, exampleVarName } from '@voxgig/sdkgen'
 import { ReadmeRefFeatures } from '@voxgig/sdkgen'
 
 import {
@@ -14,23 +14,27 @@ import { elixirLit } from './utility_elixir'
 const OP_SIGNATURES: Record<string, { sig: string, desc: string }> = {
   load: {
     sig: 'load(entity, reqmatch, ctrl \\\\ nil) :: map()',
-    desc: 'Load a single entity matching the given criteria. Returns the entity data and raises on error.',
+    desc: 'Load a single entity matching the given criteria. Returns the entity, whose record `data_get/1` reads, and raises on error.',
   },
   list: {
     sig: 'list(entity, reqmatch \\\\ nil, ctrl \\\\ nil) :: list()',
-    desc: 'List entities matching the given criteria. The match is optional — call `list(entity)` to list all records. Returns a list and raises on error.',
+    desc: 'List entities matching the given criteria. The match is optional — call `list(entity)` to list all records. Returns a list of entities, one per record, and raises on error.',
   },
   create: {
     sig: 'create(entity, reqdata, ctrl \\\\ nil) :: map()',
-    desc: 'Create a new entity with the given data. Returns the created entity data and raises on error.',
+    desc: 'Create a new entity with the given data. Returns the created entity and raises on error.',
   },
   update: {
     sig: 'update(entity, reqdata, ctrl \\\\ nil) :: map()',
-    desc: 'Update an existing entity. The data must include the entity `id`. Returns the updated entity data and raises on error.',
+    desc: 'Update an existing entity. The data must include the entity `id`. Returns the updated entity and raises on error.',
+  },
+  patch: {
+    sig: 'patch(entity, reqdata, ctrl \\\\ nil) :: map()',
+    desc: 'Change part of an existing entity: only the fields given are sent. The data must include the entity `id`. Returns the patched entity data and raises on error.',
   },
   remove: {
     sig: 'remove(entity, reqmatch, ctrl \\\\ nil) :: map()',
-    desc: 'Remove the entity matching the given criteria. Raises on error.',
+    desc: 'Remove the entity matching the given criteria. Returns the entity, marked as deleted, and raises on error.',
   },
 }
 
@@ -94,7 +98,7 @@ sdk = ${Name}.test()
 
     // Entity factory functions
     publishedEntities.map((ent: any) => {
-      Content(`#### \`${Name}.${ent.name}(client, entopts \\\\ nil)\`
+      Content(`#### \`${Name}.${elixirAccessor(ent, entityCollection(model))}(client, entopts \\\\ nil)\`
 
 Create a \`${Name}.Entity.${ent.Name}\` handle.
 
@@ -138,7 +142,8 @@ on error.
     // Entity reference sections
     publishedEntities.map((ent: any) => {
       const EName = ent.Name
-      const eVar = ent.name
+      const eVar = exampleVarName(ent.name, 'elixir')
+      const eCall = elixirAccessor(ent, entityCollection(model))
       const opnames = Object.keys(ent.op || {})
       const fields = Object.values(ent.fields || {})
       const idF = entityIdField(ent)
@@ -157,7 +162,7 @@ on error.
       }
 
       Content(`\`\`\`elixir
-${eVar} = ${Name}.${eVar}(sdk)
+${eVar} = ${Name}.${eCall}(sdk)
 \`\`\`
 
 `)
@@ -198,6 +203,10 @@ ${info.desc}
 
 `)
 
+          if (opNeedsAction(ent.op[opname])) {
+            return
+          }
+
           if ('load' === opname || 'remove' === opname) {
             const matchItems = opRequestShape(ent, opname).items
               .filter((it: any) => !it.optional || it.name === idF)
@@ -236,8 +245,8 @@ record = ${Name}.Entity.${EName}.create(${eVar}, ${Name}.Helpers.deep(%{
 
 `)
           }
-          else if ('update' === opname) {
-            const updateItems = opRequestShape(ent, 'update').items
+          else if ('update' === opname || 'patch' === opname) {
+            const updateItems = 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))
@@ -245,13 +254,20 @@ record = ${Name}.Entity.${EName}.create(${eVar}, ${Name}.Helpers.deep(%{
               `  "${it.name}" => ${elixirLit(it.type,
                 it.name === idF ? ent.name + '_id' : it.name)},\n`).join('')
             Content(`\`\`\`elixir
-record = ${Name}.Entity.${EName}.update(${eVar}, ${Name}.Helpers.deep(%{
-${updateLines}  # Fields to update
+record = ${Name}.Entity.${EName}.${opname}(${eVar}, ${Name}.Helpers.deep(%{
+${updateLines}  # ${'patch' === opname ? 'Only the fields to change' : 'Fields to update'}
 }))
 \`\`\`
 
 `)
           }
+
+          if ('create' === opname || 'update' === opname || 'patch' === opname) {
+            const note = bodyNote(ent.op[opname], {
+              values: 'a binary',
+            })
+            if ('' !== note) Content(note)
+          }
         })
       }
 

package/project/.sdk/src/cmp/elixir/ReadmeTopQuick_elixir.ts

@@ -1,5 +1,5 @@
 
-import { cmp, Content, isAuthActive, envName, entityIdField, opRequestShape } from '@voxgig/sdkgen'
+import { cmp, Content, isAuthActive, envName, entityIdField, opRequestShape, elixirAccessor, entityCollection, exampleVarName } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -32,11 +32,12 @@ sdk = ${ctor}
 
   if (exampleEntity) {
     const eName = nom(exampleEntity, 'Name')
-    const eVar = exampleEntity.name
+    const eVar = exampleVarName(exampleEntity.name, 'elixir')
+    const eCall = elixirAccessor(exampleEntity, entityCollection(model))
     const opnames = Object.keys(exampleEntity.op || {})
     const idF = entityIdField(exampleEntity)
 
-    Content(`${eVar} = ${Name}.${eVar}(sdk)
+    Content(`${eVar} = ${Name}.${eCall}(sdk)
 `)
 
     if (opnames.includes('list')) {
@@ -64,7 +65,7 @@ IO.inspect(records)
             it.name === idF ? 'example_id' : 'example_' + it.name)}`).join(', ')}})`
         : eVar
       Content(`
-# Load a specific ${eName.toLowerCase()} (returns the record, raises on error)
+# Load a specific ${eName.toLowerCase()} (returns the entity, raises on error)
 record = ${Name}.Entity.${eName}.load(${loadArgs})
 IO.inspect(record)
 `)

package/project/.sdk/src/cmp/elixir/ReadmeTopTest_elixir.ts

@@ -1,5 +1,5 @@
 
-import { cmp, Content, entityIdField, pickExampleEntity, opRequestShape } from '@voxgig/sdkgen'
+import { cmp, Content, entityIdField, pickExampleEntity, opRequestShape, elixirAccessor, entityCollection, exampleVarName } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -28,7 +28,8 @@ sdk = ${Name}.test()
 
   if (exampleEntity && primaryOp) {
     const eName = nom(exampleEntity, 'Name')
-    const eVar = exampleEntity.name
+    const eVar = exampleVarName(exampleEntity.name, 'elixir')
+    const eCall = elixirAccessor(exampleEntity, entityCollection(model))
     const idF = entityIdField(exampleEntity)
     const isMatchOp = 'load' === primaryOp || 'remove' === primaryOp
     let arg = ''
@@ -41,7 +42,7 @@ sdk = ${Name}.test()
         ? `H.deep(%{${items.map((it: any) =>
           `"${it.name}" => ${it.name === idF ? '"test01"' : elixirLit(it.type)}`).join(', ')}})`
         : 'H.deep(%{})'
-    } else if ('create' === primaryOp || 'update' === primaryOp) {
+    } else if ('create' === primaryOp || 'update' === primaryOp || 'patch' === primaryOp) {
       const items = opRequestShape(exampleEntity, primaryOp).items
         .filter((it: any) => it.name !== idF && it.name !== 'id')
       const required = items.filter((it: any) => !it.optional)
@@ -51,7 +52,7 @@ sdk = ${Name}.test()
       arg = 'H.deep(%{})'
     }
     const resVar = 'list' === primaryOp ? 'records' : 'record'
-    Content(`${eVar} = ${Name}.${eVar}(sdk)
+    Content(`${eVar} = ${Name}.${eCall}(sdk)
 ${resVar} = ${Name}.Entity.${eName}.${primaryOp}(${eVar}, ${arg})
 IO.inspect(${resVar})
 `)