@voxgig/sdkgen 4.34.0 → 4.34.2

package/project/.sdk/src/cmp/ts/fragment/EntityPatchOp.fragment.ts

@@ -0,0 +1,126 @@
+type Context = any
+type Control = any
+
+class EntityOperation {
+
+  #match: any
+  #data: any
+  #utility: any
+
+
+  // EJECT-START
+
+  async patch(this: any, reqdata?: EntityNamePatchData, ctrl?: Control): Promise<EntyClass> {
+
+    const utility = this._utility
+
+    const {
+      makeContext,
+      done,
+      // The registry name is `makeError`; `error` is the local alias.
+      makeError: error,
+      featureHook,
+      makePoint,
+      makeRequest,
+      makeResponse,
+      makeResult,
+      makeSpec,
+    } = utility
+
+    let fres: Promise<any> | undefined = undefined
+
+    let ctx: Context = makeContext({
+      opname: 'patch',
+      ctrl,
+      match: this._match,
+      data: this._data,
+      reqdata
+    }, this._entctx)
+
+    try {
+
+      // #PrePoint-Hook
+
+      ctx.out.point = makePoint(ctx)
+      if (ctx.out.point instanceof Error) {
+        return error(ctx, ctx.out.point)
+      }
+
+
+      // #PreSpec-Hook
+
+      ctx.out.spec = makeSpec(ctx)
+      if (ctx.out.spec instanceof Error) {
+        return error(ctx, ctx.out.spec)
+      }
+
+
+      // #PreRequest-Hook
+
+      ctx.out.request = await makeRequest(ctx)
+      if (ctx.out.request instanceof Error) {
+        return error(ctx, ctx.out.request)
+      }
+
+
+      // #PreResponse-Hook
+
+      ctx.out.response = await makeResponse(ctx)
+      if (ctx.out.response instanceof Error) {
+        return error(ctx, ctx.out.response)
+      }
+
+
+      // #PreResult-Hook
+
+      ctx.out.result = await makeResult(ctx)
+      if (ctx.out.result instanceof Error) {
+        return error(ctx, ctx.out.result)
+      }
+
+
+      // #PreDone-Hook
+
+      if (null != ctx.result) {
+        if (null != ctx.result.resmatch) {
+          this._match = ctx.result.resmatch
+        }
+
+        if (null != ctx.result.resdata) {
+          this._data = ctx.result.resdata
+        }
+      }
+
+      const out = done(ctx)
+
+      return (ctx.result && ctx.result.ok) ? this : out
+    }
+    catch (err: any) {
+      // What a hook throws here must not escape the cleaning below.
+      try {
+        // #PreUnexpected-Hook
+      }
+      catch (hookerr: any) {
+        err = hookerr
+      }
+
+      err = this._unexpected(ctx, err)
+
+      if (err) {
+        throw err
+      }
+      else {
+        // Off-happy-path (throw disabled): typed as any so the method's
+        // Promise<EntyClass> return stays clean under strict null checks.
+        return undefined as any
+      }
+    }
+  }
+
+  // EJECT-END
+
+
+  #unexpected(this: any, ctx: Context, ctrl: any, err: any): any { return err }
+
+}
+

package/project/.sdk/src/cmp/ts/fragment/EntityUpdateOp.fragment.ts

@@ -111,7 +111,7 @@ class EntityOperation {
       }
       else {
         // Off-happy-path (throw disabled): typed as any so the method's
-        // Promise<EntityName> return stays clean under strict null checks.
+        // Promise<EntyClass> return stays clean under strict null checks.
         return undefined as any
       }
     }

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

@@ -6,6 +6,9 @@ import type { Context, Feature } from './types'
 import { config } from './Config'
 import { ProjectNameEntityBase } from './ProjectNameEntityBase'
 import { Utility } from './utility/Utility'
+import { unreadableBody } from './utility/ResultBodyUtility'
+import { abortError } from './utility/MakeRequestUtility'
+import { allowed } from './utility/PrepareMethodUtility'
 
 
 import { BaseFeature } from './feature/base/BaseFeature'
@@ -15,6 +18,13 @@ import { BaseFeature } from './feature/base/BaseFeature'
 const stdutil = new Utility()
 
 
+// A request's outcome: ok is false alone on an error with no response, so a
+// caller narrowing on it reaches the status and the data.
+type DirectResult =
+  | { ok: false, err: any, status?: undefined, headers?: undefined, data?: undefined }
+  | { ok: boolean, status: number, headers: any, data: any, err?: any }
+
+
 class ProjectNameSDK {
   _mode: string = 'live'
   _options: any
@@ -123,13 +133,19 @@ class ProjectNameSDK {
     }, this._rootctx)
 
     const options = this._options
+    const method = String(fetchargs.method || 'GET').toUpperCase()
+
+    if (!allowed(options.allow.method, method)) {
+      return ctx.error('spec_method_allow', 'Method "' + method +
+        '" not allowed by SDK option allow.method value: "' + options.allow.method + '"')
+    }
 
     const spec: any = {
       base: options.base,
       prefix: options.prefix,
       suffix: options.suffix,
       path: fetchargs.path || '',
-      method: fetchargs.method || 'GET',
+      method,
       params: fetchargs.params || {},
       query: fetchargs.query || {},
       headers: prepareHeaders(ctx),
@@ -160,8 +176,8 @@ class ProjectNameSDK {
   // Raw endpoint access is operator-controllable, like every entity op.
   // Blocking it means denying BOTH the 'direct' and 'graphql' tokens, since
   // either one reaches the same endpoint.
-  async direct(fetchargs?: any) {
-    if (!this._options.allow.op.includes('direct')) {
+  async direct(fetchargs?: any): Promise<DirectResult> {
+    if (!allowed(this._options.allow.op, 'direct')) {
       return {
         ok: false,
         err: new Error('ProjectNameSDK: direct: operation not allowed by' +
@@ -177,7 +193,7 @@ class ProjectNameSDK {
   // checks its own allow.op token first. Private, rather than a flag on
   // fetchargs: a caller-supplied marker would let anyone opt straight back
   // out of the gate by passing it.
-  async _rawRequest(fetchargs?: any) {
+  async _rawRequest(fetchargs?: any): Promise<DirectResult> {
     const utility = this._utility
 
     const fetcher = utility.fetcher
@@ -185,7 +201,7 @@ class ProjectNameSDK {
 
     const fetchdef = await this.prepare(fetchargs)
     if (fetchdef instanceof Error) {
-      return fetchdef
+      return { ok: false, err: utility.clean(this._rootctx, fetchdef) }
     }
 
     let ctx: Context = makeContext({
@@ -194,13 +210,17 @@ class ProjectNameSDK {
     }, this._rootctx)
 
     try {
+      if (true === fetchdef.signal?.aborted) {
+        throw fetchdef.signal.reason
+      }
+
       const fetched = await fetcher(ctx, fetchdef.url, fetchdef)
 
       if (null == fetched) {
         return { ok: false, err: ctx.error('direct_no_response', 'response: undefined') }
       }
       else if (fetched instanceof Error) {
-        return { ok: false, err: utility.clean(ctx, fetched) }
+        return { ok: false, err: utility.clean(ctx, abortError(ctx, fetched)) }
       }
 
       const status = fetched.status
@@ -215,26 +235,41 @@ class ProjectNameSDK {
       const noBody = 204 === status || 304 === status || '0' === String(contentLength)
 
       let json: any = undefined
+      let err: any = undefined
       if (!noBody) {
+        let text: any = undefined
         try {
-          json = 'function' === typeof fetched.json ? await fetched.json() : fetched.json
+          const raw: any = fetched
+          if ('function' === typeof raw.text) {
+            text = await raw.text()
+            json = '' === text.trim() ? undefined : JSON.parse(text)
+          }
+          else {
+            json = 'function' === typeof fetched.json ? await fetched.json() : fetched.json
+          }
         }
-        catch (parseErr) {
-          // Body wasn't valid JSON — surface the raw response rather than
-          // throwing. data stays undefined; callers can inspect status/headers.
-          json = undefined
+        catch (parseErr: any) {
+          if ('SyntaxError' !== parseErr?.name) {
+            throw parseErr
+          }
+          err = unreadableBody(ctx, {
+            status, headers, text: text ?? parseErr.text, sent: fetchdef.headers,
+            failed: 200 <= status && status < 300 ? undefined :
+              ctx.error('request_status', 'request: ' + status + ': ' + fetched.statusText),
+          })
         }
       }
 
       return {
-        ok: status >= 200 && status < 300,
+        ok: null == err && status >= 200 && status < 300,
         status,
         headers: fetched.headers,
         data: json,
+        ...(null == err ? {} : { err: utility.clean(ctx, err) }),
       }
     }
     catch (err: any) {
-      return { ok: false, err: utility.clean(ctx, err) }
+      return { ok: false, err: utility.clean(ctx, abortError(ctx, err)) }
     }
   }
 
@@ -243,7 +278,7 @@ class ProjectNameSDK {
   async graphql(query: string, variables?: any, ctrl?: any) {
     const options = this._options
 
-    if (!options.allow.op.includes('graphql')) {
+    if (!allowed(options.allow.op, 'graphql')) {
       return {
         ok: false,
         err: new Error('ProjectNameSDK: graphql: operation not allowed by' +
@@ -258,10 +293,6 @@ class ProjectNameSDK {
       ctrl,
     })
 
-    if (res instanceof Error) {
-      return res
-    }
-
     // Errors are read BEFORE any status check: a GraphQL parse or validation
     // failure comes back as HTTP 400 carrying the standard { errors: [...] }
     // body, and the raw path represents a non-2xx as { ok: false } with no
@@ -341,3 +372,4 @@ export {
 }
 
 
+export type { DirectResult }

package/project/.sdk/src/cmp/ts/utility_ts.ts

@@ -7,6 +7,7 @@ import {
   canonScalarKey,
   each,
   opParams,
+  jsQuote,
 } from '@voxgig/sdkgen'
 
 import {
@@ -55,7 +56,7 @@ function exampleValue(entity: any, op: any, paramName: string, placeholder: stri
   if ('NULL' === key) {
     return 'null'
   }
-  return `'${placeholder}'`
+  return jsQuote(placeholder)
 }
 
 

package/project/.sdk/src/cmp/zig/Entity_zig.ts

@@ -40,12 +40,12 @@ const Entity = cmp(function Entity(props: any) {
       // error. Tag-form keys (`#LoadOp`) match `// #LoadOp` and capture the
       // marker's indent, so the spliced method nests inside the struct.
       const opfrags =
-        (['load', 'list', 'create', 'update', 'remove']
+        (['load', 'list', 'create', 'update', 'patch', 'remove']
           .reduce((a: any, opname: string) =>
           (a['#' + camelify(opname) + 'Op'] =
             !opnames.includes(opname) ?
               ({ indent }: any) => {
-                const arg = ('create' === opname || 'update' === opname) ?
+                const arg = ('create' === opname || 'update' === opname || 'patch' === opname) ?
                   'reqdata' : 'reqmatch'
                 // The stub mirrors the real signature: ops resolve to the
                 // ENTITY (`list` to a slice of them), so an unsupported op

package/project/.sdk/src/cmp/zig/Main_zig.ts

@@ -4,6 +4,7 @@ import * as Path from 'node:path'
 import {
   cmp, each,
   File, Content, Copy, Folder, Fragment,
+  inactiveFeatureExcludes,
   pluginExcludes,
   targetFeatures,
 } from '@voxgig/sdkgen'
@@ -76,38 +77,20 @@ const Main = cmp(async function Main(props: any) {
   // helpers/applicability.
   const feature = targetFeatures(model, target)
 
-  const esc = (s: string) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
-  const allfeature = getModelPath(model, `main.${KIT}.feature`,
-    { required: false, only_active: false }) || {}
-  const inactivePluginExcludes: RegExp[] = []
-  for (const fname of Object.keys(allfeature)) {
-    if (null != (feature as any)[fname]) continue
-    const groups = getModelPath(model, `main.${KIT}.feature.${fname}.plugin`,
-      { required: false, only_active: false }) || {}
-    for (const gname of Object.keys(groups)) {
-      for (const one of (groups[gname].path || [])) {
-        const pat = esc(String(one))
-        inactivePluginExcludes.push(new RegExp('(^|/)' +
-          pat.replace(/\\\/$/, '') + (/\/$/.test(String(one)) ? '/' : '$')))
-      }
-    }
-  }
-
   Package({ target })
 
   Gitignore({})
 
   Copy({
     from: 'tm/' + target.name,
-    // pluginExcludes: the generate-time plugin trim for an ACTIVE feature's
-    // inactive groups (the model's `path` entries are target-root-relative,
-    // which is this Copy's root); inactivePluginExcludes (above) for the
-    // groups of a feature that is itself off.
+    // pluginExcludes: the generate-time plugin trim, every group of a feature
+    // that is off included (the model's `path` entries are relative to this
+    // Copy's root).
     exclude: [
       /src\//,
       /build\.zig\.zon$/,
+      ...inactiveFeatureExcludes(props.ctx$, target),
       ...pluginExcludes(model),
-      ...inactivePluginExcludes,
     ],
     replace: {
       ...props.ctx$.stdrep,

package/project/.sdk/src/cmp/zig/Package_zig.ts

@@ -22,6 +22,8 @@ const Package = cmp(async function Package(props: any) {
 
   const name = zigModuleName(model)
 
+  // A fetched package keeps only `.paths`: the module source, the license
+  // and the docs the README links.
   File({ name: 'build.zig.zon' }, () => {
     Content(`.{
     .name = .${name},
@@ -29,10 +31,17 @@ const Package = cmp(async function Package(props: any) {
     .fingerprint = ${zigPackageFingerprint(name)},
     .dependencies = .{},
     .paths = .{
-        "src",
-        "test",
         "build.zig",
         "build.zig.zon",
+        "root.zig",
+        "core",
+        "entity",
+        "feature",
+        "utility",
+        "test",
+        "LICENSE",
+        "README.md",
+        "REFERENCE.md",
     },
 }
 `)

package/project/.sdk/src/cmp/zig/PrepareAuth_zig.ts

@@ -97,7 +97,7 @@ const CRED_NAME = ${zigstr(credLiteral(spec.where, spec.name))};
 const OPTION_APIKEY = "apikey";
 ` + (withBasic ? `const OPTION_SECRET = "secret";
 ` : '') + `const NOT_FOUND = "__NOTFOUND__";
-` + (withBasic ? basicHelpers() : '') + `
+` + authName(true) + (withBasic ? basicHelpers() : '') + `
 pub fn prepare_auth_util(ctx: *Context) E!*Spec {
     const spec = ctx.spec orelse return ctx.fail("auth_no_spec", "Expected context spec property to be defined.");
 
@@ -111,6 +111,13 @@ pub fn prepare_auth_util(ctx: *Context) E!*Spec {
         return spec;
     }
 
+    const name = auth_name(options);
+
+    // A credential left under the declared name would travel beside the renamed one.
+    if (!std.mem.eql(u8, name, CRED_NAME)) {
+        h.del_prop(headers, h.vstr(CRED_NAME));
+    }
+
     const apikey = vs.getprop(h.A(), options, h.vstr(OPTION_APIKEY), h.vstr(NOT_FOUND)) catch h.vstr(NOT_FOUND);
 
     const skip = switch (apikey) {
@@ -120,7 +127,7 @@ pub fn prepare_auth_util(ctx: *Context) E!*Spec {
     };
 ` + (withBasic ? basicBlock() : '') + `
     if (skip) {
-        h.del_prop(headers, h.vstr(CRED_NAME));
+        h.del_prop(headers, h.vstr(name));
     } else {
         const auth_prefix: []const u8 = switch (h.getpath(&.{ "auth", "prefix" }, options)) {
             .string => |s| s,
@@ -133,9 +140,9 @@ pub fn prepare_auth_util(ctx: *Context) E!*Spec {
         // A raw credential (empty prefix, e.g. an apiKey scheme) must go in
         // as-is; only a non-empty prefix (Bearer/Basic/OAuth) is space-joined.
         if (auth_prefix.len == 0) {
-            h.setp(headers, CRED_NAME, h.vstr(apikey_val));
+            h.setp(headers, name, h.vstr(apikey_val));
         } else {
-            h.setp(headers, CRED_NAME, h.vstr(fmt("{s} {s}", .{ auth_prefix, apikey_val })));
+            h.setp(headers, name, h.vstr(fmt("{s} {s}", .{ auth_prefix, apikey_val })));
         }
     }
 
@@ -151,7 +158,7 @@ function renderQuery(spec: AuthSpec): string {
 const CRED_NAME = ${zigstr(credLiteral(spec.where, spec.name))};
 const OPTION_APIKEY = "apikey";
 const NOT_FOUND = "__NOTFOUND__";
-
+` + authName(false) + `
 pub fn prepare_auth_util(ctx: *Context) E!*Spec {
     const spec = ctx.spec orelse return ctx.fail("auth_no_spec", "Expected context spec property to be defined.");
 
@@ -165,6 +172,13 @@ pub fn prepare_auth_util(ctx: *Context) E!*Spec {
         return spec;
     }
 
+    const name = auth_name(options);
+
+    // A credential left under the declared name would travel beside the renamed one.
+    if (!std.mem.eql(u8, name, CRED_NAME)) {
+        h.del_prop(query, h.vstr(CRED_NAME));
+    }
+
     const apikey = vs.getprop(h.A(), options, h.vstr(OPTION_APIKEY), h.vstr(NOT_FOUND)) catch h.vstr(NOT_FOUND);
 
     const skip = switch (apikey) {
@@ -174,7 +188,7 @@ pub fn prepare_auth_util(ctx: *Context) E!*Spec {
     };
 
     if (skip) {
-        h.del_prop(query, h.vstr(CRED_NAME));
+        h.del_prop(query, h.vstr(name));
     } else {
         const apikey_val: []const u8 = switch (apikey) {
             .string => |s| s,
@@ -185,7 +199,7 @@ pub fn prepare_auth_util(ctx: *Context) E!*Spec {
         // dropped here deliberately rather than silently concatenated. Nor is
         // there an HTTP Basic branch - \`Authorization: Basic base64(u:p)\`
         // cannot be a query parameter.
-        h.setp(query, CRED_NAME, h.vstr(apikey_val));
+        h.setp(query, name, h.vstr(apikey_val));
     }
 
     return spec;
@@ -205,36 +219,26 @@ const COOKIE_HEADER = "cookie";
 const CRED_NAME = ${zigstr(credLiteral(spec.where, spec.name))};
 const OPTION_APIKEY = "apikey";
 const NOT_FOUND = "__NOTFOUND__";
-
-// The cookie header minus our own pair, every other cookie left alone.
-fn cookies_without_cred(headers: Value) []const u8 {
+` + authName(false) + `
+// The cookie header minus the named pair, every other cookie left alone.
+fn cookies_without_cred(headers: Value, name: []const u8) []const u8 {
     const existing: []const u8 = switch (h.getp(headers, COOKIE_HEADER)) {
         .string => |s| s,
         else => "",
     };
     if (existing.len == 0) return "";
 
-    var kept: []const u8 = "";
-    var it = std.mem.splitScalar(u8, existing, ';');
-    while (it.next()) |part| {
-        const piece = std.mem.trim(u8, part, " \\t");
-        if (piece.len == 0) continue;
-        if (std.mem.eql(u8, piece, CRED_NAME)) continue;
-        if (std.mem.startsWith(u8, piece, CRED_NAME ++ "=")) continue;
-        kept = if (kept.len == 0) piece else fmt("{s}; {s}", .{ kept, piece });
-    }
-
-    return kept;
+    return std.mem.join(h.A(), "; ", h.cookie_keep(existing, &[_][]const u8{name})) catch "";
 }
 
-// Set (a value) or remove (null) our pair, leaving every other cookie in place.
-fn apply_cookie(headers: Value, value: ?[]const u8) void {
-    const rest = cookies_without_cred(headers);
+// Set (a value) or remove (null) the named pair, leaving every other cookie in place.
+fn apply_cookie(headers: Value, name: []const u8, value: ?[]const u8) void {
+    const rest = cookies_without_cred(headers, name);
 
     if (value) |v| {
         // NO PREFIX IN A COOKIE either - a cookie carries a bare \`name=value\`
         // pair, not a header's scheme-prefixed credential.
-        const pair = fmt("{s}={s}", .{ CRED_NAME, v });
+        const pair = fmt("{s}={s}", .{ name, v });
         h.setp(headers, COOKIE_HEADER, h.vstr(if (rest.len == 0) pair else fmt("{s}; {s}", .{ rest, pair })));
         return;
     }
@@ -255,10 +259,17 @@ pub fn prepare_auth_util(ctx: *Context) E!*Spec {
     // Public APIs that need no auth omit the options.auth block entirely.
     const auth = h.getp(options, "auth");
     if (h.is_noval(auth)) {
-        apply_cookie(headers, null);
+        apply_cookie(headers, CRED_NAME, null);
         return spec;
     }
 
+    const name = auth_name(options);
+
+    // A credential left under the declared name would travel beside the renamed one.
+    if (!std.mem.eql(u8, name, CRED_NAME)) {
+        apply_cookie(headers, CRED_NAME, null);
+    }
+
     const apikey = vs.getprop(h.A(), options, h.vstr(OPTION_APIKEY), h.vstr(NOT_FOUND)) catch h.vstr(NOT_FOUND);
 
     const skip = switch (apikey) {
@@ -268,13 +279,13 @@ pub fn prepare_auth_util(ctx: *Context) E!*Spec {
     };
 
     if (skip) {
-        apply_cookie(headers, null);
+        apply_cookie(headers, name, null);
     } else {
         const apikey_val: []const u8 = switch (apikey) {
             .string => |s| s,
             else => "",
         };
-        apply_cookie(headers, apikey_val);
+        apply_cookie(headers, name, apikey_val);
     }
 
     return spec;
@@ -283,6 +294,21 @@ pub fn prepare_auth_util(ctx: *Context) E!*Spec {
 }
 
 
+// The client's `auth.name` option, when set, replaces the declared name; a
+// header name travels lower-cased.
+function authName(header: boolean): string {
+  return `
+// The client's auth.name option, when set, replaces the name the API declares.
+fn auth_name(options: Value) []const u8 {
+    return switch (h.getpath(&.{ "auth", "name" }, options)) {
+        .string => |s| if (s.len == 0) CRED_NAME else ${header ? 'std.ascii.allocLowerString(h.A(), s) catch CRED_NAME' : 's'},
+        else => CRED_NAME,
+    };
+}
+`
+}
+
+
 function imports(need: { vs: boolean, fmt: boolean }): string {
   return `
 const std = @import("std");
@@ -345,7 +371,7 @@ function basicBlock(): string {
         };
 
         if (skip) {
-            h.del_prop(headers, h.vstr(CRED_NAME));
+            h.del_prop(headers, h.vstr(name));
         } else {
             const basic_prefix: []const u8 = switch (h.getpath(&.{ "auth", "prefix" }, options)) {
                 .string => |s| s,
@@ -364,9 +390,9 @@ function basicBlock(): string {
             // registration covers.
             ctx.util().clean_add(ctx, b64);
             if (basic_prefix.len == 0) {
-                h.setp(headers, CRED_NAME, h.vstr(b64));
+                h.setp(headers, name, h.vstr(b64));
             } else {
-                h.setp(headers, CRED_NAME, h.vstr(fmt("{s} {s}", .{ basic_prefix, b64 })));
+                h.setp(headers, name, h.vstr(fmt("{s} {s}", .{ basic_prefix, b64 })));
             }
         }