{"id":20311098,"url":"https://github.com/mcmath/gulp-transform","last_synced_at":"2025-07-31T17:34:43.968Z","repository":{"id":52045355,"uuid":"49316092","full_name":"mcmath/gulp-transform","owner":"mcmath","description":"Gulp plugin for performing arbitrary transformations on the contents of files.","archived":false,"fork":false,"pushed_at":"2022-12-06T17:23:04.000Z","size":126,"stargazers_count":9,"open_issues_count":3,"forks_count":6,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-25T12:11:05.105Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","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/mcmath.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-01-09T07:58:15.000Z","updated_at":"2023-12-09T08:43:26.000Z","dependencies_parsed_at":"2023-01-24T10:30:36.374Z","dependency_job_id":null,"html_url":"https://github.com/mcmath/gulp-transform","commit_stats":null,"previous_names":[],"tags_count":17,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mcmath%2Fgulp-transform","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mcmath%2Fgulp-transform/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mcmath%2Fgulp-transform/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mcmath%2Fgulp-transform/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mcmath","download_url":"https://codeload.github.com/mcmath/gulp-transform/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247976080,"owners_count":21027011,"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":[],"created_at":"2024-11-14T17:36:09.671Z","updated_at":"2025-04-11T16:07:10.162Z","avatar_url":"https://github.com/mcmath.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# gulp-transform\n\n[![version][versionBadge]][npm]\n[![build][buildBadge]][build]\n[![coverage][coverageBadge]][coverage]\n[![dependencies][dependenciesBadge]][dependencies]\n\nA [Gulp][gulp] plugin for applying custom transformations to the contents of\nfiles.\n\n## Install\n\nInstall via [npm][npm]:\n\n```sh\nnpm install --save-dev gulp gulp-transform\n```\n\n## Usage\n\n### Synchronous usage\n\nThis example adds a timestamp to the beginning of each source file. The comment\nformat is inferred from the file extension. Files with unrecognized extensions\nare not modified.\n\n#### gulpfile.js\n\n```js\nconst gulp = require('gulp');\nconst transform = require('gulp-transform');\nconst path = require('path');\n\nconst TIMESTAMP = Date();\n\ngulp.task('timestamp', () =\u003e {\n  return gulp.src('src/**/*')\n    .pipe(transform('utf8', timestamp))\n    .pipe(gulp.dest('out'));\n});\n\nfunction timestamp(content, file) {\n  switch (path.extname(file.path)) {\n    case '.js':\n    case '.ts':\n      return `// ${TIMESTAMP}\\n\\n${content}`;\n    case '.coffee':\n      return `# ${TIMESTAMP}\\n\\n${content}`;\n    default:\n      return content;\n  }\n}\n```\n\n#### src/hello.js\n\n```js\nconsole.log('Hello, world.');\n```\n\n#### out/hello.js\n\n```js\n// Thu Jul 27 2017 15:56:14 GMT-0700 (PDT)\n\nconsole.log('Hello, world.');\n```\n\n### Asynchronous usage\n\nThis example uses [xml2js][xml2js] to convert XML to JSON. The callback\nreturns a [Promise][promise] since the operation is asynchronous.\n\n#### gulpfile.js\n\n```js\nconst gulp = require('gulp');\nconst transform = require('gulp-transform');\nconst rename = require('gulp-rename');\nconst xml2js = require('xml2js');\n\ngulp.task('xml-to-json', () =\u003e {\n  return gulp.src('src/**/*.xml')\n    .pipe(transform('utf8', xmlToJson))\n    .pipe(rename({ extname: '.json' }))\n    .pipe(gulp.dest('out'));\n});\n\nfunction xmlToJson(content) {\n  return new Promise((resolve, reject) =\u003e {\n    xml2js.parseString(content, (error, data) =\u003e {\n      if (error) {\n        reject(error);\n      } else {\n        resolve(JSON.stringify(data, null, 2));\n      }\n    });\n  });\n}\n```\n\n#### src/cities.xml\n\n```xml\n\u003ccities\u003e\n  \u003ccity\u003eAmsterdam\u003c/city\u003e\n  \u003ccity\u003eRotterdam\u003c/city\u003e\n  \u003ccity\u003eThe Hague\u003c/city\u003e\n\u003c/cities\u003e\n```\n\n#### out/cities.json\n\n```json\n{\n  \"cities\": {\n    \"city\": [\n      \"Amsterdam\",\n      \"Rotterdam\",\n      \"The Hague\"\n    ]\n  }\n}\n```\n\n## API\n\n### transform([options], callback)\n\nCreates a stream that transforms the contents of [File][vinylFile] objects.\nFiles in both streaming and buffer mode are accepted.\n\nTo transform contents as a string, a [character encoding][encoding] must be\nspecified; otherwise, contents will be passed to the callback as a\n[Buffer][nodeBuffer].\n\nThe contents of each File are replaced with the return value of the callback.\nOr, to perform an asynchronous transformation, a [Promise][promise] may be\nreturned.\n\n#### Parameters\n\n\u003ctable\u003e\n  \u003cthead\u003e\n    \u003ctr\u003e\n      \u003cth\u003eName\u003c/th\u003e\n      \u003cth\u003eType\u003c/th\u003e\n      \u003cth\u003eDescription\u003c/th\u003e\n    \u003c/tr\u003e\n  \u003c/thead\u003e\n  \u003ctbody\u003e\n    \u003ctr\u003e\n      \u003ctd align=\"left\"\u003e\n        \u003cstrong\u003e[options]\u003c/strong\u003e\n      \u003c/td\u003e\n      \u003ctd align=\"center\"\u003e\n        \u003cp\u003e\u003ccode\u003eobject\u003c/code\u003e\u003c/p\u003e\n        \u003cp\u003e\u003ccode\u003estring\u003c/code\u003e\u003c/p\u003e\n        \u003cp\u003e\u003ccode\u003enull\u003c/code\u003e\u003c/p\u003e\n      \u003c/td\u003e\n      \u003ctd align=\"left\"\u003e\n        \u003cp\u003e\n          An optional options object or a value indicating an encoding. If\n          passed as an object, the following properties are are accepted as\n          options:\n        \u003c/p\u003e\n        \u003cul\u003e\n          \u003cli\u003e\n            \u003cstrong\u003eencoding\u003c/strong\u003e - \u003ccode\u003estring\u003c/code\u003e | \u003ccode\u003enull\u003c/code\u003e - An\n            \u003ca href=\"https://nodejs.org/dist/latest/docs/api/buffer.html#buffer_buffers_and_character_encodings\"\u003e\n            encoding\u003c/a\u003e supported by Node.js or \u003ccode\u003enull\u003c/code\u003e to indicate\n            no encoding. Defaults to \u003ccode\u003enull\u003c/code\u003e.\n          \u003c/li\u003e\n          \u003cli\u003e\n            \u003cstrong\u003ethisArg\u003c/strong\u003e - \u003ccode\u003eany\u003c/code\u003e - The value of\n            \u003ccode\u003ethis\u003c/code\u003e within \u003cem\u003ecallback\u003c/em\u003e. Defaults to\n            \u003ccode\u003eundefined\u003c/code\u003e.\n          \u003c/li\u003e\n        \u003c/ul\u003e\n        \u003cp\u003e\n          If passed as a string or \u003ccode\u003enull\u003c/code\u003e, it is interpreted as the\n          \u003cem\u003eencoding\u003c/em\u003e option.\n        \u003c/p\u003e\n        \u003cp\u003e\n          If no encoding is given, \u003cem\u003ecallback\u003c/em\u003e is called with a\n          \u003ccode\u003eBuffer\u003c/code\u003e object containing the contents of the file.\n          Otherwise, it is called with a string created with\n          \u003ca href=\"https://nodejs.org/dist/latest/docs/api/buffer.html#buffer_buf_tostring_encoding_start_end\"\u003e\n          \u003ccode\u003e\u003cem\u003ebuffer\u003c/em\u003e.toString(\u003cem\u003eencoding\u003c/em\u003e)\u003c/code\u003e\u003c/a\u003e.\n        \u003c/p\u003e\n      \u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003ctd align=\"left\"\u003e\n        \u003cstrong\u003ecallback\u003c/strong\u003e\n      \u003c/td\u003e\n      \u003ctd align=\"center\"\u003e\n        \u003ccode\u003efunction\u003c/code\u003e\n      \u003c/td\u003e\n      \u003ctd align=\"left\"\u003e\n        \u003cp\u003e\n          A function that transforms the contents of each file. It is invoked\n          with two arguments:\n        \u003c/p\u003e\n        \u003cul\u003e\n          \u003cli\u003e\n            \u003cstrong\u003econtents\u003c/strong\u003e - \u003ccode\u003eBuffer\u003c/code\u003e | \u003ccode\u003estring\u003c/code\u003e - The\n            contents of the file. If no encoding is given, \u003cem\u003econtents\u003c/em\u003e\n            will be a \u003ccode\u003eBuffer\u003c/code\u003e; otherwise, it will be a string.\n          \u003c/li\u003e\n          \u003cli\u003e\n            \u003cstrong\u003efile\u003c/strong\u003e - \u003ccode\u003eFile\u003c/code\u003e - The\n            \u003ca href=\"https://github.com/gulpjs/vinyl#instance-methods\"\u003e\n            \u003ccode\u003eFile\u003c/code\u003e\u003c/a\u003e object whose contents are being transformed.\n            Use this to access metadata about the file, e.g., its filename.\n          \u003c/li\u003e\n        \u003c/ul\u003e\n        \u003cp\u003e\n          The contents of the file are replaced with the return value of the\n          callback. For asynchronous transformations, a\n          \u003ca href=\"https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Promise\"\u003e\n          \u003ccode\u003ePromise\u003c/code\u003e\u003c/a\u003e may be returned. The return or completion\n          value must have the same type as \u003cem\u003econtents\u003c/em\u003e.\n        \u003c/p\u003e\n        \u003cp\u003e\n          The value of \u003ccode\u003ethis\u003c/code\u003e within the callback may be set with the\n          \u003cem\u003ethisArg\u003c/em\u003e option; otherwise, \u003ccode\u003ethis\u003c/code\u003e will be\n          \u003ccode\u003eundefined\u003c/code\u003e.\n        \u003c/p\u003e\n      \u003c/td\u003e\n    \u003c/tr\u003e\n  \u003c/tbody\u003e\n\u003c/table\u003e\n\n## TypeScript\n\n[TypeScript][typescript] declarations are included in the package.\n\n```sh\nnpm i -D typescript ts-node gulp @types/gulp gulp-transform\n```\n\n#### gulpfile.ts\n\n```ts\nimport gulp = require(\"gulp\");\nimport transform = require(\"gulp-transform\");\n\ngulp.task(\"build\", () =\u003e {\n  gulp.src(\"src/**/*\")\n    .pipe(transform(\"utf8\", () =\u003e { /* transform contents */ }))\n    .pipe(gulp.dest(\"out\"));\n});\n```\n\n## License\n\nCopyright \u0026copy; 2016\u0026ndash;2017 Akim McMath. Licensed under the [MIT License][license].\n\n[gulp]: http://gulpjs.com/\n[npm]: https://npmjs.org/package/gulp-transform\n[versionBadge]: https://img.shields.io/npm/v/gulp-transform.svg?style=flat-square\n[license]: LICENSE\n[buildBadge]: https://img.shields.io/travis/mcmath/gulp-transform/master.svg?style=flat-square\n[build]: https://travis-ci.org/mcmath/gulp-transform\n[coverageBadge]: https://img.shields.io/coveralls/mcmath/gulp-transform/master.svg?style=flat-square\u0026service=github\n[coverage]: https://coveralls.io/github/mcmath/gulp-transform?branch=master\n[dependenciesBadge]: https://img.shields.io/gemnasium/mcmath/gulp-transform.svg?style=flat-square\n[dependencies]: https://gemnasium.com/mcmath/gulp-transform\n[xml2js]: https://github.com/Leonidas-from-XIV/node-xml2js\n[vinylFile]: https://github.com/gulpjs/vinyl#instance-methods\n[encoding]: https://nodejs.org/dist/latest/docs/api/buffer.html#buffer_buffers_and_character_encodings\n[nodeBuffer]: https://nodejs.org/dist/latest-v8.x/docs/api/buffer.html\n[promise]: https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Promise\n[typescript]: https://www.typescriptlang.org/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmcmath%2Fgulp-transform","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmcmath%2Fgulp-transform","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmcmath%2Fgulp-transform/lists"}