Skip to content

Commit

Permalink
rename Photon JS to Photon.js
Browse files Browse the repository at this point in the history
  • Loading branch information
nikolasburk committed Aug 12, 2019
1 parent 6238f8a commit e069d9f
Show file tree
Hide file tree
Showing 10 changed files with 47 additions and 47 deletions.
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -49,7 +49,7 @@ Learn more about the `prisma2 init` flow [here](./docs/getting-started.md) or ge
- [SQLite](./docs/core/connectors/sqlite.md)
- [MongoDB](./docs/core/connectors/mongo.md)
- Generators
- [Photon JS](./docs/core/generators/photonjs.md)
- [Photon.js](./docs/core/generators/photonjs.md)
- Photon
- [API](./docs/photon/api.md)
- [Use only Photon](./docs/photon/use-only-photon.md)
Expand Down
2 changes: 1 addition & 1 deletion docs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@
- [SQLite](./core/connectors/sqlite.md)
- [MongoDB](./core/connectors/mongo.md)
- Generators
- [Photon JS](./core/generators/photonjs.md)
- [Photon.js](./core/generators/photonjs.md)
- Photon
- [API](./photon/api.md)
- [Use only Photon](./photon/use-only-photon.md)
Expand Down
14 changes: 7 additions & 7 deletions docs/core/generators/photonjs.md
Original file line number Diff line number Diff line change
@@ -1,14 +1,14 @@
# Photon JS generator
# Photon.js generator

The Photon JS generator can be used in a [Prisma schema file](../../prisma-schema-file.md) to generate the Photon database client for Node.js and TypeScript. The API of the generated client is documented [here](../../photon/api.md).
The Photon.js generator can be used in a [Prisma schema file](../../prisma-schema-file.md) to generate the Photon database client for Node.js and TypeScript. The API of the generated client is documented [here](../../photon/api.md).

## Node.js requirements

The generated data access code of the `photonjs` generator targets [ES2016](https://exploringjs.com/es2016-es2017/) which means you need [Node.js 8.x](https://nodejs.org/en/download/releases/) or newer to be able to use it.

## Specifying the right platform for Photon JS
## Specifying the right platform for Photon.js

Photon JS depends on a _query engine_ that's running as a _binary_ on the same host as your application. When deploying your Photon-based application to production, you need to ensure that the binary used by Photon can run in your production environment, i.e. it needs to be compatible with the runtime of your deployment provider.
Photon.js depends on a _query engine_ that's running as a _binary_ on the same host as your application. When deploying your Photon-based application to production, you need to ensure that the binary used by Photon can run in your production environment, i.e. it needs to be compatible with the runtime of your deployment provider.

The query engine binary is downloaded when you run `prisma2 generate`, it is then stored alongside the generated Photon code inside `node_modules/@generated` (or the [custom `output` path](./codegen-and-node-setup.md) you specified). This section explains how you can determine which binary should be downloaded when `prisma2 generate` is executed to ensure compatibility at runtime.

Expand Down Expand Up @@ -65,7 +65,7 @@ In both cases, the Prisma CLI determines the current operating system where `pri

### Example

This example shows the configuration of a Photon JS generator for local development (`native` can resolve to any other platform) and AWS Lambda (Node 10) as the production environment.
This example shows the configuration of a Photon.js generator for local development (`native` can resolve to any other platform) and AWS Lambda (Node 10) as the production environment.

```prisma
generator photon {
Expand Down Expand Up @@ -97,7 +97,7 @@ It will then store the generated Photon API in the specified `./generated/photon

## Mapping types from the data model

The Photon JS generator provides the following mapping from data model [scalar types](../../data-modeling.md#scalar-types) to JavaScript/TypeScript types:
The Photon.js generator provides the following mapping from data model [scalar types](../../data-modeling.md#scalar-types) to JavaScript/TypeScript types:

| Type | JS / TS |
| -------- | ------- |
Expand All @@ -109,7 +109,7 @@ The Photon JS generator provides the following mapping from data model [scalar t

## Reserved model names

When generating Photon JS based on your [data model definition](./data-modeling.md#data-model-definition), there are a number of reserved names that you can't use for your models. Here is a list of the reserved names:
When generating Photon.js based on your [data model definition](./data-modeling.md#data-model-definition), there are a number of reserved names that you can't use for your models. Here is a list of the reserved names:

- `String`
- `Int`
Expand Down
6 changes: 3 additions & 3 deletions docs/data-modeling.md
Original file line number Diff line number Diff line change
Expand Up @@ -112,7 +112,7 @@ Every _model_ in the data model definition will result in a number of CRUD opera

The operations are accessible via a generated property on the Photon instance. By default the name of the property is the plural, lowercase form of the model name, e.g. `users` for a `User` model or `posts` for a `Post` model.

Here is an example illustrating the use of a `users` property from the [Photon JS API](./photon/api.md):
Here is an example illustrating the use of a `users` property from the [Photon.js API](./photon/api.md):

```js
const newUser = await photon.users.create({ data: {
Expand All @@ -121,7 +121,7 @@ const newUser = await photon.users.create({ data: {
const allUsers = await photon.users.findMany()
```

Note that for Photon JS the name of the `users` property is auto-generated using the [`pluralize`](https://github.com/blakeembrey/pluralize) package.
Note that for Photon.js the name of the `users` property is auto-generated using the [`pluralize`](https://github.com/blakeembrey/pluralize) package.

## Fields

Expand Down Expand Up @@ -453,7 +453,7 @@ Learn more about relations [here](./relations.md).

## Reserved model names

When generating Photon JS based on your [data model definition](./data-modeling.md#data-model-definition), there are a number of reserved names that you can't use for your models. Here is a list of the reserved names:
When generating Photon.js based on your [data model definition](./data-modeling.md#data-model-definition), there are a number of reserved names that you can't use for your models. Here is a list of the reserved names:

- `String`
- `Int`
Expand Down
4 changes: 2 additions & 2 deletions docs/glossary.md
Original file line number Diff line number Diff line change
Expand Up @@ -69,7 +69,7 @@ Also sometimes referred to as:

### Generator

A generator determines what kind of code should be generated from the [data model](#data-model-definition). For example, you can specify the _Photon JS generator_ to generate Photon JS as a type-safe database client based on the data model.
A generator determines what kind of code should be generated from the [data model](#data-model-definition). For example, you can specify the _Photon.js generator_ to generate Photon.js as a type-safe database client based on the data model.

You can include various generators in your [schema file](#prisma-schema-file). When running `prisma2 generate`, the Prisma CLI reads the specified generators from the Prisma schema and invokes each of them.

Expand Down Expand Up @@ -133,7 +133,7 @@ The [Prisma schema file](./prisma-schema-file.md) specifies the main parts of yo

- [**Data sources**](#data-source): Specify the details of the data sources Prisma should connect to (e.g. a PostgreSQL database)
- [**Data model definition**](#data-model-definition): Specifies the shape of the data per data source
- [**Generators**](#generator): Specifies what data source clients should be generated (e.g. Photon JS)
- [**Generators**](#generator): Specifies what data source clients should be generated (e.g. Photon.js)

### Scalar type

Expand Down
26 changes: 13 additions & 13 deletions docs/photon/codegen-and-node-setup.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,15 +2,15 @@

## TLDR

Photon JS is generated into `node_modules/@generated` by default. While this approach has a number of [benefits](#why-is-photon-js-generated-into-node_modulesgenerated-by-default), it is also unconventional and can be a source confusion for developers new to Photon JS.
Photon.js is generated into `node_modules/@generated` by default. While this approach has a number of [benefits](#why-is-photon-js-generated-into-node_modulesgenerated-by-default), it is also unconventional and can be a source confusion for developers new to Photon.js.

Using `node_modules/@generated` as the default `output` for Photon JS is still experimental. Please share your feedback and tell us whether you think this is a good idea or any other thoughts you have on this topic by joining the [dicussion on GitHub](https://github.com/prisma/photonjs/issues/88).
Using `node_modules/@generated` as the default `output` for Photon.js is still experimental. Please share your feedback and tell us whether you think this is a good idea or any other thoughts you have on this topic by joining the [dicussion on GitHub](https://github.com/prisma/photonjs/issues/88).

## Overview

`prisma2 generate` uses the [generators](../prisma-schema-file.md#generators-optional) specified in the [Prisma schema file](../prisma-schema-file.md) and generates the respective packages on the respective output path(s).

The default Photon JS generator can be specified as follows in your schema file:
The default Photon.js generator can be specified as follows in your schema file:

```prisma
generator photonjs {
Expand All @@ -33,17 +33,17 @@ When running `prisma2 generate` for either of these schema files, the `photon` p
node_modules/@generated/photon
```

## Photon JS should be viewed as an npm package
## Photon.js should be viewed as an npm package

Node.js libraries are typically installed as npm dependencies using `npm install`. The respective packages are then located inside the [`node_modules`](https://docs.npmjs.com/files/folders#node-modules) directory from where they can be easily imported into application code.

Because Photon JS is a custom API for _your_ specific database setup, it can't follow that model. It needs to be generated locally instead of being installed from a central repository like npm. However, the mental model for Photon JS should still be that of an Node module.
Because Photon.js is a custom API for _your_ specific database setup, it can't follow that model. It needs to be generated locally instead of being installed from a central repository like npm. However, the mental model for Photon.js should still be that of an Node module.

## Why is Photon JS generated into `node_modules/@generated` by default?
## Why is Photon.js generated into `node_modules/@generated` by default?

### Easy imports

By generating Photon JS into `node_modules/@generated`, you can easily import it into your code:
By generating Photon.js into `node_modules/@generated`, you can easily import it into your code:

```js
import Photon from '@generated/photon'
Expand All @@ -57,13 +57,13 @@ const Photon = require('@generated/photon')

### Keeping the query engine binary out of version control by default

Photon JS is based on a query engine that's running as a binary alongside your application. This binary is downloaded when `prisma2 generate` is invoked initially and stored in the `output` path (right next to the generated Photon API).
Photon.js is based on a query engine that's running as a binary alongside your application. This binary is downloaded when `prisma2 generate` is invoked initially and stored in the `output` path (right next to the generated Photon API).

By generating Photon JS into `node_modules`, the query engine is kept out of version control by default (since `node_modules` is typically ignored for version control). If it was not generated into `node_modules`, then developers would need to explicitly ignore it, e.g. for Git they'd need to add the `output` path to `.gitignore`.
By generating Photon.js into `node_modules`, the query engine is kept out of version control by default (since `node_modules` is typically ignored for version control). If it was not generated into `node_modules`, then developers would need to explicitly ignore it, e.g. for Git they'd need to add the `output` path to `.gitignore`.

## Generating Photon JS in `postinstall` hook
## Generating Photon.js in `postinstall` hook

Generating Photon JS into `node_modules` has the potential problem that package managers like `npm` or `yarn` want to maintain the integrity of `node_modules`. They therefore remove any additional folders that are not specified by the respective `.lock` files on operations like `install`, `add`, etc.
Generating Photon.js into `node_modules` has the potential problem that package managers like `npm` or `yarn` want to maintain the integrity of `node_modules`. They therefore remove any additional folders that are not specified by the respective `.lock` files on operations like `install`, `add`, etc.

To work around this problem, you can add a `postinstall` script to your `package.json`. This gets invoked automatically after any time invocation of `npm install`:

Expand All @@ -75,6 +75,6 @@ To work around this problem, you can add a `postinstall` script to your `package
}
```

When collaborating on a project that uses Photon JS, this approach allows for conventional Node.js best practices where a team member can clone a Git repository and then run `npm install` to get their version of the Node dependencies inside their local `node_modules` directory.
When collaborating on a project that uses Photon.js, this approach allows for conventional Node.js best practices where a team member can clone a Git repository and then run `npm install` to get their version of the Node dependencies inside their local `node_modules` directory.

However, the downside of this approach is that when developers have _not_ configured a `postinstall` script for the generation of Photon JS and are not aware that they must generate Photon JS after cloning a repository, they will most likely run into errors and be confused.
However, the downside of this approach is that when developers have _not_ configured a `postinstall` script for the generation of Photon.js and are not aware that they must generate Photon.js after cloning a repository, they will most likely run into errors and be confused.
8 changes: 4 additions & 4 deletions docs/photon/deployment.md
Original file line number Diff line number Diff line change
@@ -1,14 +1,14 @@
# Deployment

Photon JS depends on a query engine that's running as a binary on the same host as your application. When deploying your Photon-based application to production, you need to ensure that the binary used by Photon can run in your production environment, i.e. it needs to be compatible with the runtime of your deployment provider.
Photon.js depends on a query engine that's running as a binary on the same host as your application. When deploying your Photon-based application to production, you need to ensure that the binary used by Photon can run in your production environment, i.e. it needs to be compatible with the runtime of your deployment provider.

The query engine binary is downloaded when you run `prisma2 generate`, it is then stored alongside the generated Photon code inside `node_modules/@generated` (or the [custom `output` path](./codegen-and-node-setup.md) you specified).

**IMPORTANT**: To ensure the query engine binary is compatible with your production environment, you have to [specify the right platform for Photon JS](../core/generators/photonjs.md#specifying-the-right-platform-for-photon-js).
**IMPORTANT**: To ensure the query engine binary is compatible with your production environment, you have to [specify the right platform for Photon.js](../core/generators/photonjs.md#specifying-the-right-platform-for-photon-js).

## Examples

Here are a number of example projects demonstrating how to deploy Photon JS to various deploymenty providers:
Here are a number of example projects demonstrating how to deploy Photon.js to various deploymenty providers:

- [Google Cloud Functions](https://github.com/prisma/photonjs/tree/master/examples/deployment-platforms/google-cloud-functions)
- [Netlify](https://github.com/prisma/photonjs/tree/master/examples/deployment-platforms/netlify)
Expand All @@ -20,7 +20,7 @@ Here are a number of example projects demonstrating how to deploy Photon JS to v

### ZEIT Now

You can deploy your "Photon JS"-based application to [ZEIT Now](https://zeit.co/now).
You can deploy your "Photon.js"-based application to [ZEIT Now](https://zeit.co/now).

When deploying to ZEIT Now, you must configure the following in your `now.json`:

Expand Down
6 changes: 3 additions & 3 deletions docs/prisma-schema-file.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,18 +4,18 @@ The Prisma schema file (short: _schema file_, _Prisma schema_ or just _schema_)

- [**Data sources**](./data-sources.md): Specify the details of the data sources Prisma should connect to (e.g. a PostgreSQL database)
- [**Data model definition**](./data-modeling.md): Specifies your application models (the shape of the data per data source)
- [**Generators**](#generators-optional) (optional): Specifies what clients should be generated based on the data model (e.g. Photon JS)
- [**Generators**](#generators-optional) (optional): Specifies what clients should be generated based on the data model (e.g. Photon.js)

Whenever a `prisma2` command is invoked, the CLI typically reads some information from the schema file, e.g.:

- `prisma2 generate`: Reads _all_ above mentioned information from the Prisma schema to generate the correct data source client code (e.g. Photon JS).
- `prisma2 generate`: Reads _all_ above mentioned information from the Prisma schema to generate the correct data source client code (e.g. Photon.js).
- `prisma2 lift save`: Reads the data sources and data model definition to create a new [migration]().

You can also [use environment variables](#using-environment-variables) inside the schema file to provide configuration options when a CLI command is invoked.

## Example

Here is a simple example for a schema file that specifies a data source (SQLite), a generator (Photon JS) and a simple data model definition:
Here is a simple example for a schema file that specifies a data source (SQLite), a generator (Photon.js) and a simple data model definition:

```groovy
// schema.prisma
Expand Down
4 changes: 2 additions & 2 deletions docs/prisma2-feedback.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ For that, a full rewrite of Prisma was necessary so that we can build upon a pro
- Open issues in following repos:
- General Prisma 2 questions and catch-all for problems and questions: [`prisma 2`](https://github.com/prisma/prisma2)
- Problems/questions regarding Lift: [`lift`](https://github.com/prisma/lift)
- Problems/questions regarding Photon JS: [`photonjs`](https://github.com/prisma/photonjs)
- Problems/questions regarding Photon.js: [`photonjs`](https://github.com/prisma/photonjs)

## Your opinion matters – a lot!

Expand Down Expand Up @@ -48,7 +48,7 @@ In any of the following scenarios, please make sure to create a GitHub issue to

If your issue relates to either Photon or Lift specifically, you can open an issue directly in the respective repos:

- [Open an issue for **Photon JS**](https://github.com/prisma/photonjs/issues/new)
- [Open an issue for **Photon.js**](https://github.com/prisma/photonjs/issues/new)
- [Open an issue for **Lift**](https://github.com/prisma/lift/issues/new)

Otherwise, the default place for opening issues is the official `prisma2` repo (when in doubt, create the issue here):
Expand Down

0 comments on commit e069d9f

Please sign in to comment.