{"id":16369268,"url":"https://github.com/arturmuller/stringcaster","last_synced_at":"2025-08-22T10:42:07.827Z","repository":{"id":57215453,"uuid":"76410195","full_name":"arturmuller/stringcaster","owner":"arturmuller","description":"Covert strings to booleans, numbers, arrays and objects.","archived":false,"fork":false,"pushed_at":"2018-01-31T03:11:50.000Z","size":58,"stargazers_count":5,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-01-31T16:52:08.869Z","etag":null,"topics":["dotenv","string-conversion","string-manipulation"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/arturmuller.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-12-14T00:33:13.000Z","updated_at":"2023-03-11T12:20:22.000Z","dependencies_parsed_at":"2022-08-29T02:10:43.408Z","dependency_job_id":null,"html_url":"https://github.com/arturmuller/stringcaster","commit_stats":null,"previous_names":["arturmuller/dotenv-utils"],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arturmuller%2Fstringcaster","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arturmuller%2Fstringcaster/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arturmuller%2Fstringcaster/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arturmuller%2Fstringcaster/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/arturmuller","download_url":"https://codeload.github.com/arturmuller/stringcaster/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":238284795,"owners_count":19446729,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["dotenv","string-conversion","string-manipulation"],"created_at":"2024-10-11T02:54:58.525Z","updated_at":"2025-02-11T11:31:28.003Z","avatar_url":"https://github.com/arturmuller.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Stringcaster\n\n[![npm](https://img.shields.io/npm/v/stringcaster.svg)](https://www.npmjs.com/package/stringcaster)\n\nStringcaster is a focused, light-weight, tested, zero-dependency lib that lets you cast strings into any kind of JavaScript primitive type.\n\n\n## The Problem\n\nThere are many places in JavaScript land where you'll only ever be given strings as input: environment variables, command-line arguments, cookies, and many others.\n\nImagine that you have a script that enables a feature based on an env variable. A correct-looking check like this: `if (process.env.ENABLE_BUBBLES) { ...some logic }` will actually not fail when the script is run with `ENABLE_BUBBLES=false`, because env vars are strings and non-empty strings in JavaScript are truthy. Ugh.\n\nThe quick solution is to write more careful checks like so `process.env.ENABLE_BUBBLES === \"true\"`, but as you get more vars, more var \"types\", and a bigger team, these ad-hoc solutions become tedious, unclear, and error-prone.\n\nStringcaster solves this by providing a clean API for casting strings to any kind of JavaScript primitive type without hassle. It works. It's tested. No more bubbles!\n\n\n## Install\n\n```sh\n# Using `npm`\nnpm install --save stringcaster\n\n# ...or using `yarn`\nyarn add stringcaster\n```\n\nTested on Node.js v6.9.2, likely runs on earlier versions too.\n\n\n## API\n\nThe core conversion functions in Stringcaster are:\n\n- [`toBoolean`](#toBoolean)\n- [`toNumber`](#toNumber)\n- [`toString`](#toString)\n- [`toArray`](#toArray)\n- [`toObject`](#toObject)\n\nAll of these also contain a `withDefault` method that can be used to create a new conversion function with a custom fallback value.\n\nLastly, there is also the [`conform`](#conform) utility function, which takes an object and applies transformations based on a provided schema. Very useful for converting `process.env` variables!\n\nConversion functions **always return the right type**. That way, you can safely call methods without worrying about getting that _undefined-is-not-a-function_ fun.\n\n### `toBoolean`\n\nConverts a string representation (case-insensitive) of a boolean to an actual boolean.\n\n```js\nconst cast = require(\"stringcaster\")\n\ncast.toBoolean(\"true\") // true\ncast.toBoolean(\"TRUE\") // true\ncast.toBoolean(\"false\") // false\ncast.toBoolean(\"foo\") // false\ncast.toBoolean(\"\") // false\ncast.toBoolean(undefined) // false\n\nconst castToBooleanDefaultTrue = cast.toBoolean.withDefault(true)\ntoBooleanDefaultTrue(undefined) // true\n```\n\n### `toNumber`\n\nConverts a string representation of a number to an actual number. Basically like `Number(x)`, but will return a `0` instead of `NaN` when string cannot be converted to a number.\n\n```js\nconst cast = require(\"stringcaster\")\n\ncast.toNumber(\"123\") // 123\ncast.toNumber(\"  123   \") // 123\ncast.toNumber(\"foo\") // 0\ncast.toNumber(undefined) // 0\n\nconst castToNumberDefault42 = cast.toNumber.withDefault(42)\ntoBooleanDefaultTrue(undefined) // 42\n```\n\n### `toString`\n\nTrims the supplied string. If provided a falsy value, returns `\"\"`. This is mainly useful when used in conjunction with the [`conform`](#conform) helper.\n\n```js\nconst cast = require(\"stringcaster\")\n\ncast.toString(\"foo\") // foo\ncast.toString(\"  foo   \") // \"foo\"\ncast.toString(\"\") // \"\"\ncast.toString(undefined) // \"\"\n\nconst castToStringDefaultFoo = cast.toString.withDefault(\"foo\")\ncastToStringDefaultFoo(undefined) // \"foo\"\n```\n\n### `toArray`\n\nConverts a string of comma-separated values (`\"foo, bar, baz\"`) to an array of strings. Any extra whitespace will be trimmed and empty strings discarded.\n\n```js\nconst cast = require(\"stringcaster\")\n\ncast.toArray(\"foo, bar, baz\") // [\"foo\", \"bar\", \"baz\"]\ncast.toArray(\"foo,   bar,    baz\") // [\"foo\", \"bar\", \"baz\"]\ncast.toArray(\",,,\") // []\ncast.toArray(\"\") // []\ncast.toArray(undefined) // []\n\nconst castToArrayDefaultFooBar = cast.toArray.withDefault([\"foo\", \"bar\"])\ncastToArrayDefaultFooBar(undefined) // [\"foo\", \"bar\"]\n```\n\n### `toObject`\n\nConverts a string of comma-separated tuples (`\"foo: bar, baz: quux\"`) to an object. Any extra whitespace from either key or value will be discarded, as are tuples with falsy keys.\n\n```js\nconst cast = require(\"stringcaster\")\n\ncast.toObject(\"foo: bar, baz: quux\") // {foo: \"bar\", baz: \"quux\"}\ncast.toObject(\"foo:    bar   ,baz:quux\") // {foo: \"bar\", baz: \"quux\"}\ncast.toObject(\":,foo:\") // {foo: \"\"}\ncast.toObject(\"::,\") // {}\ncast.toObject(\"\") // {}\ncast.toObject(undefined) // {}\n\nconst castToObjectDefaultFooBar = cast.toObject.withDefault({ foo: \"bar\" })\ncastToObjectDefaultFooBar(undefined) // { foo: \"bar\" }\n```\n\n### `conform`\n\nProvided a schema, `conform` picks keys from an object and converts them using the supplied functions.\n\nKeys which are present in the `schema`, but not in the supplied object *will* be present in the final object, having a value/type based on calling the conversion function with `undefined`.\n\nFor example, imagine this script:\n\n```js\n// Presume that the following env vars have been set:\n// MINIFY=false\n// SUPPORTED_LOCALES=en-GB,cs-CZ,pl-PL\n\nconst cast = require(\"stringcaster\")\n\n// Specify a schema using the conversion functions\nconst schema = {\n  MINIFY: cast.toBoolean,\n  DEFAULT_LOCALE: cast.toString.withDefault(\"en-GB\"),\n  SUPPORTED_LOCALES: cast.toArray,\n}\n\n// Drop `process.env` into `conform`\nconst config = conform(process.env, schema)\n\n// `config` is now:\n// {\n//   MINIFY: false,\n//   DEFAULT_LOCALE: \"en-GB\",\n//   SUPPORTED_LOCALES: [\"en-GB\", \"cs-CZ\", \"pl-PL\"],\n// }\n\nmodule.exports = config\n```\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farturmuller%2Fstringcaster","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Farturmuller%2Fstringcaster","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farturmuller%2Fstringcaster/lists"}