{"id":26550062,"url":"https://github.com/daniel-sc/properties-trueformat","last_synced_at":"2025-10-06T02:16:40.494Z","repository":{"id":283317581,"uuid":"951360399","full_name":"daniel-sc/properties-trueformat","owner":"daniel-sc","description":"Typescript parser for (Java-) properties that 100% retains all formatting for creating identical files on roundtrips","archived":false,"fork":false,"pushed_at":"2025-03-24T09:46:58.000Z","size":49,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-09-08T21:36:16.692Z","etag":null,"topics":["java-properties","properties","typescript"],"latest_commit_sha":null,"homepage":"","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/daniel-sc.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-03-19T14:58:07.000Z","updated_at":"2025-03-24T09:44:50.000Z","dependencies_parsed_at":"2025-03-19T16:47:07.421Z","dependency_job_id":null,"html_url":"https://github.com/daniel-sc/properties-trueformat","commit_stats":null,"previous_names":["daniel-sc/properties-trueformat"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/daniel-sc/properties-trueformat","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/daniel-sc%2Fproperties-trueformat","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/daniel-sc%2Fproperties-trueformat/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/daniel-sc%2Fproperties-trueformat/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/daniel-sc%2Fproperties-trueformat/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/daniel-sc","download_url":"https://codeload.github.com/daniel-sc/properties-trueformat/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/daniel-sc%2Fproperties-trueformat/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278547821,"owners_count":26004775,"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","status":"online","status_checked_at":"2025-10-06T02:00:05.630Z","response_time":65,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["java-properties","properties","typescript"],"created_at":"2025-03-22T07:23:06.543Z","updated_at":"2025-10-06T02:16:40.489Z","avatar_url":"https://github.com/daniel-sc.png","language":"TypeScript","readme":"[![npm](https://img.shields.io/npm/v/properties-trueformat)](https://www.npmjs.com/package/properties-trueformat)\n[![Coverage Status](https://coveralls.io/repos/github/daniel-sc/properties-trueformat/badge.svg?branch=main)](https://coveralls.io/github/daniel-sc/properties-trueformat?branch=main)\n\n# properties-trueformat\n\nproperties-trueformat is a TypeScript library for parsing, editing, and serializing Java .properties files without losing any formatting details.\nIt builds a custom AST that captures every nuance — comments, blank lines, indentation, and multi-line value continuations — ensuring a no-op round trip.\n\nThis library is inspired by the design of [xml-trueformat](https://github.com/daniel-sc/xml-trueformat) and is ideal for use cases where preserving the exact layout and comments of .properties files is critical (e.g., configuration files under version control).\nEnjoy seamless, non-destructive editing of your Java properties files!\n\n## Features\n\n- **Exact Formatting Preservation** \\\n  Retains inline comments, blank lines, and all whitespace exactly as in the original file.\n\n- **Multi-line Value Support** \\\n  Handles properties with multi-line values (using the backslash continuation) while preserving the exact line breaks and indents.\\\n  See `ValueSegment` and `PropertyEntry.valueSegments`.\n\n- **AST-based Editing** \\\n  Provides an Abstract Syntax Tree for precise modifications. Change a property’s value or add new entries without reformatting the rest of the file.\n\n- **Text Escaping and Unescaping** \\\n  Automatically escapes and unescapes special characters (e.g., newlines, tabs, backslashes, and unicode characters) in property values.\\\n  See `PropertyEntry.getText()` and `PropertyEntry.setText(..)`.\n\n- **Default Separator and Newline Guessing** \\\n  Automatically determines the most common separator and newline characters used in the document for consistent formatting.\\\n  See `PropertiesDocument.guessDefaults()`.\n\n## Installation\n\nInstall via npm:\n\n```bash\nnpm install properties-trueformat\n```\n\n## Usage\n\nBelow is an example that reads a .properties file, updates a property, and writes it back without altering its formatting:\n\n```ts\nimport { PropertiesDocument, PropertyEntry, parseProperties } from 'properties-trueformat';\n\n// alternatively, read the file content from disk\nconst content = `# Example configuration file\n  ! comment with exclamation mark (indented)\nkey = value\nkey.subkey=without spaces around separator\n  indented_key: indented value\n\nkey_after_blank_line = start \\\\\n  of \\\\\n  a multi-line value\n`;\n\n// Parse into a structured AST\nconst doc: PropertiesDocument = parseProperties(content);\n\n// this is the expected AST:\nexpect(doc).toEqual(\n  new PropertiesDocument([\n    new CommentLine('', '#', ' Example configuration file', '\\n'),\n    new CommentLine('  ', '!', ' comment with exclamation mark (indented)', '\\n'),\n    new PropertyEntry('', 'key', ' = ', [{ indent: '', newline: '\\n', text: 'value' }]),\n    new PropertyEntry('', 'key.subkey', '=', [{ indent: '', newline: '\\n', text: 'without spaces around separator' }]),\n    new PropertyEntry('  ', 'indented_key', ': ', [{ indent: '', newline: '\\n', text: 'indented value' }]),\n    new BlankLine('', '\\n'),\n    new PropertyEntry('', 'key_after_blank_line', ' = ', [\n      { indent: '', newline: '\\\\\\n', text: 'start ' },\n      { indent: '  ', newline: '\\\\\\n', text: 'of ' },\n      { indent: '  ', newline: '\\n', text: 'a multi-line value' },\n    ]),\n  ]),\n);\n\n// Find and update a property, e.g., change \"username\"\nconst entry = doc.nodes.filter((node) =\u003e node instanceof PropertyEntry).find((node) =\u003e node.key === 'indented_key');\nif (entry) {\n  entry.setText('updated value');\n}\n\n// Serialize back to string (format preserved)\nconst newContent = doc.toString();\n\nexpect(newContent).toEqual(`# Example configuration file\n  ! comment with exclamation mark (indented)\nkey = value\nkey.subkey=without spaces around separator\n  indented_key: updated value\n\nkey_after_blank_line = start \\\\\n  of \\\\\n  a multi-line value\n`);\n// you may write the new content back to disk\n```\n\n## Contributing\n\nContributions, bug reports, and feature requests are welcome!\n\nPlease open an issue or submit a pull request on the GitHub repository.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdaniel-sc%2Fproperties-trueformat","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdaniel-sc%2Fproperties-trueformat","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdaniel-sc%2Fproperties-trueformat/lists"}