{"id":28376645,"url":"https://github.com/apiaryio/metamorphoses","last_synced_at":"2025-06-26T10:30:42.774Z","repository":{"id":55140669,"uuid":"41679462","full_name":"apiaryio/metamorphoses","owner":"apiaryio","description":"Transforms API Blueprint AST or legacy Apiary Blueprint AST into Apiary Application AST","archived":true,"fork":false,"pushed_at":"2019-06-21T13:53:49.000Z","size":262,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":12,"default_branch":"master","last_synced_at":"2025-05-30T00:07:30.658Z","etag":null,"topics":["sjs-team"],"latest_commit_sha":null,"homepage":"","language":"CoffeeScript","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/apiaryio.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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":"2015-08-31T14:18:17.000Z","updated_at":"2024-11-08T09:04:05.000Z","dependencies_parsed_at":"2022-08-14T13:11:00.463Z","dependency_job_id":null,"html_url":"https://github.com/apiaryio/metamorphoses","commit_stats":null,"previous_names":[],"tags_count":24,"template":false,"template_full_name":null,"purl":"pkg:github/apiaryio/metamorphoses","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apiaryio%2Fmetamorphoses","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apiaryio%2Fmetamorphoses/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apiaryio%2Fmetamorphoses/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apiaryio%2Fmetamorphoses/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/apiaryio","download_url":"https://codeload.github.com/apiaryio/metamorphoses/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apiaryio%2Fmetamorphoses/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262047766,"owners_count":23250415,"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":["sjs-team"],"created_at":"2025-05-30T00:07:29.964Z","updated_at":"2025-06-26T10:30:42.766Z","avatar_url":"https://github.com/apiaryio.png","language":"CoffeeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Metamorphoses\n\n*In nova fert animus mutatas dicere formas / corpora;*\n\nTransforms *API Blueprint AST* or *Refract API Description Namespace* into *Apiary Application AST*.\n\n## Use\n\n**Do not use this library. You do not need it.**\n\nReally! We needed to create it for internal use within [Apiary](https://apiary.io/), but it is going to be deprecated and removed even internally as soon as we fully migrate to [API Description Parse Result Namespace](https://github.com/refractproject/refract-spec/blob/master/namespaces/parse-result-namespace.md).\n\nYou ended up here for some reason though:\n\n- Looking for [API Blueprint spec](https://github.com/apiaryio/api-blueprint/)?\n- Looking for [API Elements](http://api-elements.readthedocs.io/en/latest/)\n- Looking for [Apiary](https://apiary.io/)?\n- Looking for [API Blueprint parser](https://github.com/apiaryio/drafter)?\n- Looking for [API Description SDK](https://github.com/apiaryio/fury.js)?\n- Just being curious? Well, there are probably better things to do. Have you already read today's [featured article on Wikipedia](https://en.wikipedia.org/wiki/Main_Page)?\n\n## Purpose\n\nApiary supports three API description formats as of now:\n\n#### API Blueprint - `text/vnd.apiblueprint`\n\n-   **Status:** recommended, heavily used and under active development\n-   **Parser:** [Drafter](https://github.com/apiaryio/drafter)\n-   **Parser Outputs:**\n    - [API Blueprint AST](https://github.com/apiaryio/api-blueprint-ast) - `application/vnd.apiblueprint.ast+json` or `+yaml`\n    - [API Elements](http://api-elements.readthedocs.io/en/latest/) - `application/vnd.refract.parse-result+json` or `+yaml`\n\n#### Swagger - `application/swagger+json` or `+yaml`\n\n-   **Parser:** [fury-adapter-swagger](https://github.com/apiaryio/fury-adapter-swagger)\n-   **Parser Outputs:**\n    - [API Elements](http://api-elements.readthedocs.io/en/latest/) - `application/vnd.refract.parse-result+json` or `+yaml`\n\nTo be able to work with both of these formats through some sort of uniform interface, *Apiary* internally transforms ASTs to a so-called *Application AST*. The Metamorphoses library does exactly this job, i.e. transforms any AST to the internal *Apiary Application AST*.\n\n\u003e **Note:** The information above is *simplified* for the context of the Metamorphoses library. As noted in the introduction, API Blueprint AST is about to be slowly replaced by [API Description Parse Result Namespace](https://github.com/refractproject/refract-spec/blob/master/namespaces/api-description-namespace.md) as the parser output. Once [Fury](https://github.com/apiaryio/fury.js) has adapters to both *API Blueprint* and the *legacy Apiary Blueprint*, producing *API Description Parse Result Namespace* for both, and once *Apiary* starts to use the *API Description API Description Namespace* exclusively, this library becomes redundant.\n\n## Interface\n\n```javascript\nvar metamorphoses = require('metamorphoses');\n\n\n// Blueprint source\nvar source = '# Sample API...';\n\n\n// Select adapter by mime type:\n// -   API Blueprint AST: 'application/vnd.apiblueprint.ast'\n// -   Legacy Apiary Blueprint AST: 'application/vnd.legacyblueprint.ast'\nvar mimeType = 'application/vnd.apiblueprint.ast';\nvar adapter = metamorphoses.createAdapter(mimeType);\n\n\n// You can also import the adapter directly:\n// -   API Blueprint AST: apiBlueprintAdapter\nvar adapter = metamorphoses.apiBlueprintAdapter;\n\n\n// Pseudo-code parse function. It is a placeholder for parser\n// interface of either Drafter (https://github.com/apiaryio/drafter)\n// or the legacy Blueprint Parser (https://github.com/apiaryio/blueprint-parser)\nparse(source, ..., function (err, result) {\n\n  // transform the error parse result into an error\n  var err = adapter.transformError(source, parseResult);\n  console.log(err); // transformed error object\n\n  // transform the AST\n  var ast = adapter.transformAst(result.ast);\n  console.log(ast); // transformed AST (application AST)\n  console.log(result.warnings); // parser warnings\n  ...\n\n});\n\n\n// Blueprint API (Application AST)\nmetamorphoses.blueprintApi.Blueprint.fromJSON({\n  ...\n});\n```\n\n### `transformError`\n\nTransforming an error accepts the source API Description Document and the\nresultant parse result. The method returns an error if there was an error in\nthe parse result, the error will be a JSON object as follows:\n\n- message - Error message\n- code - Error code\n- location (array) - Error source map\n    - (object)\n        - index (number)\n        - length (number)\n- line - The line producing the error from the source API Description Document derived from the source map\n\n## Name\n\n[Wikipedia](https://en.wikipedia.org/wiki/Metamorphoses): The Metamorphoses (Latin: *Metamorphōseōn librī*: \"Books of Transformations\") is a Latin narrative poem by the Roman poet Ovid.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fapiaryio%2Fmetamorphoses","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fapiaryio%2Fmetamorphoses","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fapiaryio%2Fmetamorphoses/lists"}