modules-pack/upload/file.doc.md

JavaScript Modules for Modern Frontend & Backend Projects

## FILE UPLOADS

### Example GraphQL User Type

```graphql
type User {
    files: [File!]
}
input UserInput {
    files: [FileInput!]
}
# Backend matches the same structure
```

### Example User File

```js
const File = {
  src: `/{uploadDir}/{ModelName}/{Id}/{kind}_{i}.{ext}`,
  kind: `profile`, // (or avatar/public/private/etc.)
  i: 0 // (or thumb/small/large)
}
```

Can yield 4 file versions with the same User Id:

```shell
>>> /uploads/User/Mdygx0NX0k/profile_0.jpg
>>> /uploads/User/Mdygx0NX0k/profile_hd.jpg
>>> /uploads/User/Mdygx0NX0k/avatar_0.png
>>> /uploads/User/Mdygx0NX0k/avatar_hd.png
```

### Example Files Grouped by Project

```shell
>>> /uploads/Project/Mdygx0Noxx/Texture/Mdygx0NX0k/base_0.jpg
>>> /uploads/Project/Mdygx0Noxx/Mesh/Mdygx0NX0j/hd.glTF
>>> /uploads/Project/Mdygx0Noxx/Preview/Mdygx0NX0h/public.jpg
>>> /uploads/Project/Mdygx0Noxx/Csv/Mdygx0NX0i.csv
```

### Flexible File Structure with Minimal Setup

Note: File type is flexible by design, and is to be used with these Components:

- `<UploadGrid...>` - list of a single or multiple file types of the same `kind`
- `<UploadGrids...>` - list of kinds as tabs, each with a single or multiple file `i` (identifier or index) types.

=> using `FIELD` definition, they automatically map `File` types from backend, and autosave, query, and mutate without
manual setup in frontend.

### Validation

- default `required` validator only checks that `<UploadGrid...>` has value
- specific identifier (i.e. 'HD' version of 'profile' kind) requires custom validator

### Adhoc implementations

- preview generated by backend automatically
- dimensions generated by backend automatically

-----------------------------------------------------------------------------

## SETUP

1. Set `src` as ID for caching

```js
// @see: https://www.apollographql.com/docs/react/caching/cache-configuration/#typepolicy-fields
// apollo.js
const client = new ApolloClient({
  cache: new InMemoryCache({
    typePolicies: {
      File: {
        keyFields: ['src'],
      },
    }
  })
})
```

2. Add FileSummary to EntrySummary Fragment (or FileDetails Fragment)

```graphql
# UserSummary.gql
#import "modules-pack/graphql/fragments/FileSummary.gql"
fragment UserSummary on User {
    photos {
        ...FileSummary
    }
}
```

3. Configure Form Field

```js
// constants.js
FIELD.DEF = {
  [FIELD.ID.FILES]: {
    name: 'files',
    parse: fileParser,
    // ...other required props
    view: FIELD.TYPE.UPLOAD_GRID,
  }
}
```

4. Decorate Resolver

```js
// resolvers.js
@filesUploaded()
user(parent, args, context, info)
{
  // ...resolver logic
  return new User(entry)
}
```

5. Define Type in Model Schema

```js
// models.js
const userSchema = {
  // ...user model fields
  files: {...Files, required}
}
```