@mojir/dvala 0.0.32 → 0.0.33

package/dist/cli/cli.js

@@ -480,7 +480,7 @@ function findAllOccurrences(input, pattern) {
 }
 //#endregion
 //#region package.json
-var version = "0.0.32";
+var version = "0.0.33";
 //#endregion
 //#region src/typeGuards/string.ts
 function isString(value, options = {}) {
@@ -8351,32 +8351,32 @@ const timeModule = {
 	docs: moduleDocsFromFunctions(timeFunctions)
 };
 const handlerModule = {
-	name: "handler",
+	name: "effectHandler",
 	functions: {},
 	source: "{\n  retry: (n) -> (arg, eff, nxt) ->\n    if eff == @dvala.error then nxt(eff, arg)\n    else\n      loop (remaining = n) ->\n        handle nxt(eff, arg)\n        with @dvala.error(msg) ->\n          if remaining > 0 then recur(remaining - 1)\n          else nxt(@dvala.error, msg)\n          end\n        end\n    end,\n\n  fallback: (value) -> @dvala.error(msg) -> value\n}\n",
 	docs: {
 		"retry": {
-			category: "handler",
+			category: "effectHandler",
 			returns: { type: "function" },
 			args: { n: { type: "integer" } },
 			variants: [{ argumentNames: ["n"] }],
 			description: "Returns a handler function that retries failing effects up to `$n` times. On final failure, propagates the original error. Passes `@dvala.error` through unchanged.",
 			examples: [
-				"let { retry } = import(handler); retry(3)",
-				"let { retry, fallback } = import(handler);\nperform(@my.eff, \"data\") ||> [retry(2), @my.eff(x) -> x ++ \"!\", fallback(\"gave up\")]",
-				"let { retry } = import(handler);\nhandle perform(@my.eff, 10) with [retry(3), @my.eff(x) -> x * 2] end"
+				"let { retry } = import(effectHandler); retry(3)",
+				"let { retry, fallback } = import(effectHandler);\nperform(@my.eff, \"data\") ||> [retry(2), @my.eff(x) -> x ++ \"!\", fallback(\"gave up\")]",
+				"let { retry } = import(effectHandler);\nhandle perform(@my.eff, 10) with [retry(3), @my.eff(x) -> x * 2] end"
 			]
 		},
 		"fallback": {
-			category: "handler",
+			category: "effectHandler",
 			returns: { type: "function" },
 			args: { value: { type: "any" } },
 			variants: [{ argumentNames: ["value"] }],
 			description: "Returns a handler function that catches `@dvala.error` and returns `$value` instead.",
 			examples: [
-				"let { fallback } = import(handler); fallback(0)",
-				"let { fallback } = import(handler);\n(0 / 0) ||> fallback(0)",
-				"let { fallback } = import(handler);\nhandle let x = 0 / 0; x + 1 with fallback(0) end"
+				"let { fallback } = import(effectHandler); fallback(0)",
+				"let { fallback } = import(effectHandler);\n(0 / 0) ||> fallback(0)",
+				"let { fallback } = import(effectHandler);\nhandle let x = 0 / 0; x + 1 with fallback(0) end"
 			]
 		}
 	}
@@ -24400,13 +24400,20 @@ const standardEffects = {
 				description: "Value to print."
 			} },
 			variants: [{ argumentNames: ["value"] }],
-			examples: [{
-				code: "perform(@dvala.io.print, \"hello\")",
-				noRun: true
-			}, {
-				code: "perform(@dvala.io.print, 42)",
-				noRun: true
-			}],
+			examples: [
+				{
+					code: "perform(@dvala.io.print, \"hello\")",
+					noRun: true
+				},
+				{
+					code: "perform(@dvala.io.print, 42)",
+					noRun: true
+				},
+				{
+					code: "perform(@dvala.io.print, {name: \"Alice\", age: 30})",
+					noRun: true
+				}
+			],
 			seeAlso: [
 				"-effect-dvala.io.error",
 				"-effect-dvala.io.read",
@@ -24439,6 +24446,9 @@ const standardEffects = {
 			examples: [{
 				code: "perform(@dvala.io.error, \"something went wrong\")",
 				noRun: true
+			}, {
+				code: "perform(@dvala.io.error, {code: 500, message: \"Internal error\"})",
+				noRun: true
 			}],
 			seeAlso: [
 				"-effect-dvala.io.print",
@@ -24470,7 +24480,13 @@ const standardEffects = {
 				description: "Optional prompt message to display."
 			} },
 			variants: [{ argumentNames: [] }, { argumentNames: ["message"] }],
-			examples: ["@dvala.io.read"],
+			examples: [{
+				code: "let name = perform(@dvala.io.read, \"What is your name?\"); \"Hello, \" ++ name",
+				noRun: true
+			}, {
+				code: "let input = perform(@dvala.io.read); input ?? \"no input\"",
+				noRun: true
+			}],
 			seeAlso: [
 				"-effect-dvala.io.readStdin",
 				"-effect-dvala.io.print",
@@ -24483,9 +24499,8 @@ const standardEffects = {
 	},
 	"dvala.io.pick": {
 		handler: (arg, k, sourceCodeInfo) => {
-			const argObj = arg;
-			const items = argObj?.["items"];
-			const options = argObj?.["options"];
+			const items = Array.isArray(arg) ? arg : arg?.["items"];
+			const options = Array.isArray(arg) ? void 0 : arg?.["options"];
 			if (!Array.isArray(items)) throw new DvalaError(`dvala.io.pick: first argument must be an array, got ${typeof items}`, sourceCodeInfo);
 			if (items.length === 0) throw new DvalaError("dvala.io.pick: items array must not be empty", sourceCodeInfo);
 			for (let i = 0; i < items.length; i++) if (typeof items[i] !== "string") throw new DvalaError(`dvala.io.pick: items[${i}] must be a string, got ${typeof items[i]}`, sourceCodeInfo);
@@ -24535,12 +24550,12 @@ const standardEffects = {
 		},
 		docs: {
 			category: "effect",
-			description: "Presents a numbered list of items and asks the user to choose one. In browsers uses `window.prompt()`. In Node.js, register a host handler. Resumes with the index of the chosen item, or `null` if the user cancels.",
+			description: "Presents a list of items and asks the user to choose one. Accepts either a plain array of strings or an object with `items` and optional `options`. Resumes with the index of the chosen item, or `null` if the user cancels.",
 			returns: { type: ["integer", "null"] },
 			args: {
 				items: {
 					type: "array",
-					description: "Non-empty array of strings to display."
+					description: "Non-empty array of strings to display. Can be passed directly as the arg."
 				},
 				options: {
 					type: "object",
@@ -24548,7 +24563,20 @@ const standardEffects = {
 				}
 			},
 			variants: [{ argumentNames: ["items"] }, { argumentNames: ["items", "options"] }],
-			examples: ["@dvala.io.pick"],
+			examples: [
+				{
+					code: "let choice = perform(@dvala.io.pick, [\"Red\", \"Green\", \"Blue\"])",
+					noRun: true
+				},
+				{
+					code: "let choice = perform(@dvala.io.pick, {items: [\"Red\", \"Green\", \"Blue\"], options: {prompt: \"Pick a color:\", default: 0}})",
+					noRun: true
+				},
+				{
+					code: "do\n  let colors = [\"Red\", \"Green\", \"Blue\"];\n  let idx = perform(@dvala.io.pick, colors);\n  if idx != null then nth(colors, idx) else \"No selection\" end\nend",
+					noRun: true
+				}
+			],
 			seeAlso: [
 				"-effect-dvala.io.read",
 				"-effect-dvala.io.confirm",
@@ -24594,7 +24622,13 @@ const standardEffects = {
 				}
 			},
 			variants: [{ argumentNames: ["question"] }, { argumentNames: ["question", "options"] }],
-			examples: ["@dvala.io.confirm"],
+			examples: [{
+				code: "if perform(@dvala.io.confirm, \"Delete all files?\") then \"Deleted\" else \"Cancelled\" end",
+				noRun: true
+			}, {
+				code: "perform(@dvala.io.confirm, {question: \"Continue?\", options: {default: true}})",
+				noRun: true
+			}],
 			seeAlso: [
 				"-effect-dvala.io.read",
 				"-effect-dvala.io.pick",
@@ -24626,7 +24660,10 @@ const standardEffects = {
 			returns: { type: "string" },
 			args: {},
 			variants: [{ argumentNames: [] }],
-			examples: ["@dvala.io.readStdin"],
+			examples: [{
+				code: "let input = perform(@dvala.io.readStdin); count(input)",
+				noRun: true
+			}],
 			seeAlso: [
 				"-effect-dvala.io.read",
 				"perform",
@@ -24866,7 +24903,13 @@ const standardEffects = {
 				description: "The number of milliseconds to sleep. Must be a non-negative number."
 			} },
 			variants: [{ argumentNames: ["ms"] }],
-			examples: ["@dvala.sleep"],
+			examples: [{
+				code: "do perform(@dvala.sleep, 1000); \"awake!\" end",
+				noRun: true
+			}, {
+				code: "do perform(@dvala.io.print, \"waiting...\"); perform(@dvala.sleep, 500); perform(@dvala.io.print, \"done!\") end",
+				noRun: true
+			}],
 			seeAlso: [
 				"-effect-dvala.time.now",
 				"perform",

package/package.json

@@ -3,7 +3,7 @@
   "overrides": {
     "file-type": "^21.3.2"
   },
-  "version": "0.0.32",
+  "version": "0.0.33",
   "description": "A suspendable, time-traveling functional language for JavaScript with algebraic effects",
   "author": "Albert Mojir",
   "license": "MIT",