@voxgig/sdkgen 1.2.1 → 1.3.1

package/dist/cmp/ReadmeErrors.js

@@ -0,0 +1,210 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ReadmeErrors = void 0;
+const jostraca_1 = require("jostraca");
+const types_1 = require("../types");
+const opShape_1 = require("../helpers/opShape");
+const opExample_1 = require("../helpers/opExample");
+const naming_1 = require("../helpers/naming");
+const DEFAULT_LANG = {
+    entity: (call, op) => `Entity operations reject on failure, so wrap them in \`try\` / \`catch\`:
+
+\`\`\`ts
+try {
+  const ${call.resultVar} = await ${call.expr}
+  console.log(${call.resultVar})
+} catch (err) {
+  console.error('${op} failed:', err)
+}
+\`\`\`
+
+`,
+    direct: `The low-level \`direct()\` method does **not** throw — it returns the
+value or an \`Error\`, so check the result before using it:
+
+\`\`\`ts
+const result = await client.direct({
+  path: '/api/resource/{id}',
+  method: 'GET',
+  params: { id: 'example_id' },
+})
+
+if (result instanceof Error) {
+  throw result
+}
+\`\`\`
+
+`,
+};
+const LANGS = {
+    py: {
+        entity: (call, op) => `Entity operations raise on failure, so wrap them in \`try\` / \`except\`:
+
+\`\`\`python
+try:
+    ${call.resultVar} = ${call.expr}
+    print(${call.resultVar})
+except Exception as err:
+    print(f"${op} failed: {err}")
+\`\`\`
+
+`,
+        direct: `\`direct()\` does **not** raise — it returns the result envelope. Branch
+on \`ok\`; on failure \`status\` holds the HTTP status (for error responses)
+and \`err\` holds a transport error, so read both defensively:
+
+\`\`\`python
+result = client.direct({
+    "path": "/api/resource/{id}",
+    "method": "GET",
+    "params": {"id": "example_id"},
+})
+
+if not result["ok"]:
+    print("request failed:", result.get("status"), result.get("err"))
+\`\`\`
+
+`,
+    },
+    php: {
+        entity: (call, op) => `Entity operations throw a \`\\Throwable\` on failure, so wrap them in
+\`try\` / \`catch\`:
+
+\`\`\`php
+try {
+    $${call.resultVar} = ${call.expr};
+} catch (\\Throwable $err) {
+    echo "Error: " . $err->getMessage();
+}
+\`\`\`
+
+`,
+        direct: `\`direct()\` does **not** throw — it returns the result array. Branch on
+\`ok\`; on failure \`status\` holds the HTTP status (for error responses) and
+\`err\` holds a transport error, so read both defensively:
+
+\`\`\`php
+$result = $client->direct([
+    "path" => "/api/resource/{id}",
+    "method" => "GET",
+    "params" => ["id" => "example_id"],
+]);
+
+if (! $result["ok"]) {
+    $err = $result["err"] ?? null;
+    echo "request failed: " . ($err ? $err->getMessage() : "HTTP " . $result["status"]);
+}
+\`\`\`
+
+`,
+    },
+    rb: {
+        entity: (call, op) => `Entity operations raise on failure, so rescue them:
+
+\`\`\`ruby
+begin
+  ${call.resultVar} = ${call.expr}
+rescue => err
+  warn "${op} failed: #{err}"
+end
+\`\`\`
+
+`,
+        direct: `\`direct\` does **not** raise — it returns the result hash. Branch on
+\`ok\`; on failure \`status\` holds the HTTP status (for error responses) and
+\`err\` holds a transport error, so read both defensively:
+
+\`\`\`ruby
+result = client.direct({
+  "path" => "/api/resource/{id}",
+  "method" => "GET",
+  "params" => { "id" => "example_id" },
+})
+
+warn "request failed: #{result["err"] || "HTTP #{result["status"]}"}" unless result["ok"]
+\`\`\`
+
+`,
+    },
+    lua: {
+        entity: (call, op) => `Entity operations return \`(value, err)\`. Check \`err\` before using
+the value:
+
+\`\`\`lua
+local ${call.resultVar}, err = ${call.expr}
+if err then error(err) end
+\`\`\`
+
+`,
+        direct: `\`direct\` follows the same \`(value, err)\` convention:
+
+\`\`\`lua
+local result, err = client:direct({
+  path = "/api/resource/{id}",
+  method = "GET",
+  params = { id = "example_id" },
+})
+if err then error(err) end
+\`\`\`
+
+`,
+    },
+    go: {
+        entity: (call, op) => `Every entity operation returns \`(value, error)\`. Check \`err\` before
+using the value — there is no exception to catch:
+
+\`\`\`go
+${call.resultVar}, err := ${call.expr}
+if err != nil {
+    // handle err
+    return
+}
+_ = ${call.resultVar}
+\`\`\`
+
+`,
+        direct: `\`Direct\` follows the same \`(value, error)\` convention:
+
+\`\`\`go
+result, err := client.Direct(map[string]any{
+    "path":   "/api/resource/{id}",
+    "method": "GET",
+    "params": map[string]any{"id": "example_id"},
+})
+if err != nil {
+    // handle err
+}
+_ = result
+\`\`\`
+
+`,
+    },
+};
+const ReadmeErrors = (0, jostraca_1.cmp)(function ReadmeErrors(props) {
+    const { target, ctx$ } = props;
+    const { model } = ctx$;
+    const lang = LANGS[target.name] || DEFAULT_LANG;
+    // Derive a real example entity from the model (the same way the sibling
+    // Readme components do) so the snippet never references a phantom entity.
+    const entity = (0, types_1.getModelPath)(model, `main.${types_1.KIT}.entity`, { only_active: false, required: false });
+    const ex = Object.values(entity || {}).find((e) => e && e.active !== false);
+    const eName = ex ? (ex.Name || (ex.name[0].toUpperCase() + ex.name.slice(1))) : 'Entity';
+    // Sanitise the variable name against the target's reserved words (a `Delete`
+    // entity must not bind `const delete = ...`).
+    const eLower = (0, naming_1.safeVarName)(eName.toLowerCase(), target.name);
+    // The entity's id-like key field name, or null when it has none.
+    const idF = (0, opShape_1.entityIdField)(ex);
+    // The entity's PRIMARY op — an op it actually exposes (prefer list/load, else
+    // create/update/remove). A create-only entity therefore never shows a
+    // phantom `.load()`.
+    const primaryOp = (0, opShape_1.entityPrimaryOp)(ex) || 'load';
+    const call = (0, opExample_1.primaryOpCall)(target.name, eName, eLower, primaryOp, idF, ex);
+    (0, jostraca_1.Content)(`
+## Error handling
+
+`);
+    (0, jostraca_1.Content)(lang.entity(call, primaryOp));
+    (0, jostraca_1.Content)(lang.direct);
+});
+exports.ReadmeErrors = ReadmeErrors;
+//# sourceMappingURL=ReadmeErrors.js.map

package/dist/cmp/ReadmeErrors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ReadmeErrors.js","sourceRoot":"","sources":["../../src/cmp/ReadmeErrors.ts"],"names":[],"mappings":"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"}