# vue-nested-json-to-csv

> A component to allow nested JSON or nested javascript objects/arrays to be queried and exported to csv. A query result row is generated for each array element in the data object provided.

Latest version **0.0.23** (published 2019-08-15) · MIT license · 0 weekly downloads

## Install

```sh
npm install vue-nested-json-to-csv
pnpm add vue-nested-json-to-csv
yarn add vue-nested-json-to-csv
bun add vue-nested-json-to-csv
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.0.23 |
| Published | 2019-08-15 |
| First published | 2019-08-07 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 0 |
| Unpacked size | 37.3 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Dan Clark |
| Maintainers | dandclark |
| Keywords | vue, nested, json, csv, query, dot notation |

## Links

- npm: https://www.npmjs.com/package/vue-nested-json-to-csv
- Repository: https://bitbucket.org/dandclark/vue-nested-json-to-csv
- Homepage: https://bitbucket.org/dandclark/vue-nested-json-to-csv#readme
- npm.io page: https://npm.io/package/vue-nested-json-to-csv

## Alternatives

- [@mapbox/jsonlint-lines-primitives](https://npm.io/package/@mapbox/jsonlint-lines-primitives.md) — 5.3M weekly downloads
- [reftools](https://npm.io/package/reftools.md) — 3.5M weekly downloads
- [@hey-api/openapi-ts](https://npm.io/package/@hey-api/openapi-ts.md) — 3.5M weekly downloads
- [@mapbox/geojson-rewind](https://npm.io/package/@mapbox/geojson-rewind.md) — 2.4M weekly downloads
- [turbo-stream](https://npm.io/package/turbo-stream.md) — 1.7M weekly downloads

## Recent versions

- 0.0.23 (latest) — 2019-08-15
- 0.0.22 — 2019-08-15
- 0.0.21 — 2019-08-15
- 0.0.20 — 2019-08-15
- 0.0.19 — 2019-08-15
- 0.0.18 — 2019-08-15
- 0.0.17 — 2019-08-15
- 0.0.16 — 2019-08-15
- 0.0.15 — 2019-08-14
- 0.0.14 — 2019-08-08
- 0.0.12 — 2019-08-07
- 0.0.11 — 2019-08-07
- 0.0.10 — 2019-08-07
- 0.0.9 — 2019-08-07
- 0.0.8 — 2019-08-07
- … 7 more at https://npm.io/package/vue-nested-json-to-csv/versions

## README

# vue-nested-json-to-csv

A component to allow nested JSON or nested javascript objects/arrays to be queried and exported to csv. A query result row is generated for each array element in the data object provided.

## Getting Started

### Installing

```
npm install vue-nested-json-to-csv
```
---
### Basic Usage

The below is a basic example of using this component

```
<template>
  <div id="app">
  
    <vue-nested-json-to-csv
    	:fields="myFields"
        :object="myData"
        :show-table="true"
        :show-export-button="true"
    ></vue-nested-json-to-csv>
    
  </div>
</template>

<script>

  export default {
  
    data(){
    	return {
        
        	myFields: [
                {
                    alias: 'A Friendly Display Name',
                    name: 'dataObject.stringProperty'
                },
                {
                    alias: 'Another Friendly Display Name',
                    name: 'dataObject.stringArrayProperty'
                },
                {
                    alias: 'Yet Another Friendly Display Name',
                    name: 'dataObject.objectArrayProperty.stringProperty'
                },
                {
                    alias: 'Yet Again Another Friendly Display Name',
                    name: 'dataObject.objectArrayProperty.arrayProperty'
                },
              ],
            
              myData: {

                  dataObject: [
                  	{
                  		stringProperty: "string1",
                  		stringArrayProperty: [
                  			"arrayString1",
                  			"arrayString2",
                  			"arrayString3",
                  		],
                  		objectArrayProperty: [
                  			{
                  				stringProperty: "objectArrayString1",
                  				arrayProperty: [
                  					"arrayString1",
                  					"arrayString2",
                  				],
                  			},
                  			{
                  				stringProperty: "objectArrayString2",
                  			},
                  			{
                  				stringProperty: "objectArrayString3",
                  			},
                  		]
                  	},
                  	{
                  		stringProperty: "string2",
                  		stringArrayProperty: [
                  			"arrayString4",
                  			"arrayString5",
                  			"arrayString6",
                  		],
                  		objectArrayProperty: [
                  			{
                  				stringProperty: "objectArrayString4",
                  			},
                  			{
                  				stringProperty: "objectArrayString5",
                  			},
                  		]
                  	},
                  ]

              },
        
        };
    }
    
  }

</script>

```
The above usage would result in the below if exported to CSV.

| A Friendly Display Name  | Another Friendly Display Name | Another Friendly Display Name | Yet Again, Another Friendly Display Name |
| ------------- | ------------- | ------------- | ------------- |
| string1  | arrayString1 \| arrayString2 \| arrayString3 | objectArrayString1 \| objectArrayString2 \| objectArrayString3  | arrayString1 \| arrayString2  |
| string2  | arrayString4 \| arrayString5 \| arrayString6  | objectArrayString4 \| objectArrayString5  |   |

---

### Expected Data Format

Whilst it is not necessary to export query results as a csv to utilise this component, the nature of the queries being performed and the data being returned lends itself to csv or tabular output.

Specifically, the component is designed to be used with an object such as that you might receive as the data portion of an API response, with a single property that is an array of similar objects where each element in this array corresponds to a csv or table row. Alternatively, the "object" provided can be an array of similar objects.

For example, following an API call, you may receive a response such as the below. The component is designed to be assigned the value of the data property of this response, or the entire response (if the latter, the component would likely be used to query the array against the data property).

```
{
  "current_page": 1,
  "data": [
    {
      "code": "EXAMPLE_CODE_1",
      "attributes": {
        "LOYALTY_POINTS": "288",
        "GLOB__FINANCE_OPTIONS": [
          "FINANCE_OPTION_1",
          "FINANCE_OPTION_2",
          "FINANCE_OPTION_3",
          "FINANCE_OPTION_4"
        ],
      }
    },
    {
      "code": "EXAMPLE_CODE_2",
      "attributes": {
        "LOYALTY_POINTS": "288",
        "GLOB__FINANCE_OPTIONS": [
          "FINANCE_OPTION_1",
          "FINANCE_OPTION_2",
          "FINANCE_OPTION_3",
          "FINANCE_OPTION_4"
        ],
      }
    },
    {
      "code": "EXAMPLE_CODE_3",
      "attributes": {
        "LOYALTY_POINTS": "608",
        "GLOB__FINANCE_OPTIONS": [
          "FINANCE_OPTION_1",
          "FINANCE_OPTION_2",
          "FINANCE_OPTION_3",
          "FINANCE_OPTION_4"
        ],
      }
    }
  ],
  "total": 115720
}
```

---
### Concatenation

Where the values returned for a field are an array of strings or integers, these values will be returned in a single result "cell", concatenated and joined by a string which is determined by the `concatenation-characters` prop. For example, if the `myObj.myArr` field was retrieved from the below data (with a default concatenation-characters prop):

```
[
	{
		myObj: {
			myArr: [
				"string1",
				"string2",
			]
		}
	},
	{
		myObj: {
			myArr: [
				"string3",
				"string4",
			]
		}
	}
]

```
Then the below results would be present in the filteredData component data (e.g. what would be emitted in the data property of the object accompanying a `filtered` event):

```
[
	[
    	"string1 | string2"
    ],
    [
    	"string3 | string4"
    ]
]
```
---

### Props

The above usage example includes only a few of the props that can be provided to the component. A full list follows: 

#### file-name-function
###### Expects: Function
###### Default: returns Report\<ms_since_1970>.csv
A function can be provided to the component to generate the file name that is used for exported csv files. The default function returns `Report<ms_since_1970>.csv`. The component does not append the `.csv` extension to the file name returned by this function (it is done within the function itself), so it is recommended that the provided function does this.

#### show-export-button
###### Expects: Boolean
###### Default: false
When true, the `export-button` slot is rendered.

#### show-table
###### Expects: Boolean
###### Default: false
When true, the `table` slot is rendered.

#### json
###### Expects: String (JSON format)
###### Default: Empty string
If this prop is provided and the `object` prop is not, the string provided is parsed and used as the data object to be queried.

#### object
###### Expects: Object (JSON format)
###### Default: Empty object
If this prop is provided, this will be used as the data object to be queried regardless of the presence of the `json` prop. 


#### fields
###### Expects: Array of dot-notated field names or array of objects each containing an alias and name property
###### Default: Empty array
This prop determines which fields should be returned. The first item in the array is used to determine how the prop should be processed. For example, if this is a string (i.e. a field name), then the rest of the array is expected to be the same.

An array of objects can be provided in this prop, each with an `alias` and `name` property. The `alias` property will be used for display purposes (e.g. what is shown in the exported csv or results table). The `name` property should be the dot-notated string specifying the property to be returned.

If a simple array of strings is provided in this prop, each string is effectively treated as both the `name` and `alias` properties.

#### errors
###### Expects: Boolean
###### Default: true
If this prop is set to true, the component can generate console errors and warnings to aid with debugging and implementation.

#### concatenation-characters
###### Expects: String
###### Default: " | "
This prop controls the string used to concatenate array results for queried properties. For example, where the queried property's value is an array of strings, the returned result would be: `arr_el_1<concatenation_string>arr_el_2<concatenation_string>...arr_el_n`

#### export-function
###### Expects: Function
###### Default: Function to export data as csv
This prop controls the function that is called when the default `export-button` is clicked. By default, this function is passed two parameters. These are the `aliasedFields` and `filteredData` component data - the former is used as a header row for the resultant csv, whilst the latter forms the body of the csv. The default function also triggers `exporting` and `exported` events appropriately.

If you desire some other functionality to be performed when clicking the default `export-button`, utilise this prop.

---

### Slots
The below slots can be used to customise the appearance of the component

#### table

The default content for this slot renders a table (utilising Bulma classes) which has a column for each element in the `fields` prop, with a column header for each field (where an `alias` property has been provided for the field, this will be used as the column header). The table then contains a row for each element (an array) in the component's `filteredData` data, with each element of that array being displayed as a "cell" in the table.

When customising the content of this slot, please note the above if you intend on achieving similar results.

Note: the contents of this slot are only rendered if the `show-table` prop is set to `true`

#### export-button

The default content for this slot renders a button (utilising Bulma classes), which performs the `export-function` prop on click. By default, the function is passed the `aliasedFields` and `filteredData` component data.

Note: the contents of this slot are only rendered if the `show-export-button` prop is set to `true`

---

### Events
This component triggers various events when processing data. These can be hooked into to improve your implementation of the component.

#### filtering
###### Triggered when: the `fields`, `object` or `json` props change.
###### Passes data: an object containing an `unaliasedFields` property this is an array of the field names being used to query the data object

#### filtered
###### Triggered when: the query results are about to be returned
###### Passes data: an object containing `unaliasedFields`, `aliasedFields` and `data` properties, which represent the dot-notated field names, display field names and query results respectively

#### exporting
###### Triggered when: the default `export-function` is called
###### Passes data: an object containing `fields` and `data` properties. These represent the aliased field names and query results respectively

#### exported
###### Triggered when: the default `export-function` has completed
###### Passes data: an object containing a csv property, which is an array whose first element is an array of aliased field names. The rest of the elements represent "rows" of query results - with each row being an array with each element representing the result for a queried field for the given row.


---

## Authors

* **Dan Clark** - [email me with a question](danielc93@hotmail.co.uk)

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details

---
_Source: https://npm.io/package/vue-nested-json-to-csv · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._