Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 19 additions & 6 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -84,13 +84,26 @@ You may still pin the flag explicitly, and `psk new` does:
`psk new` generates models with `declare` **and** pins the flag.

**`Parse` is a global.** The library never imports `parse`; it reads
`global.Parse` the way cloud code sees it. Install `@types/parse` for the
type declarations. Do not declare your own global `Parse` namespace — it will
collide.
`global.Parse` the way cloud code sees it. Do not declare your own global
`Parse` namespace — it will collide with `@types/parse`.

**Peers:** `parse >=5`, `express >=4`, `reflect-metadata >=0.1.13`.
**Optional:** `parse-server >=8.3`, `node-cron >=3`, `swagger-ui-express >=4`,
`@types/parse >=3`.
**`@types/parse` is required for TypeScript.** The shipped declarations refer
to the global `Parse` namespace — `BaseModel` is declared as extending
`Parse.Object` — so without it nothing resolves, and the errors point at your
own code rather than at the missing package:

```
Cannot find namespace 'Parse'. ts(2503)
Property 'save' does not exist on type 'Note'.
```

The second follows from the first: `BaseModel` loses its base type, so every
model loses `save`, `get` and `set`. It was declared an optional peer until
3.0.1, which is why the failure looked like a bug in the model.

**Peers:** `parse >=5`, `express >=4`, `reflect-metadata >=0.1.13`,
`@types/parse >=3` (TypeScript only).
**Optional:** `parse-server >=8.3`, `node-cron >=3`, `swagger-ui-express >=4`.

---

Expand Down
7 changes: 3 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -137,10 +137,9 @@ export enum Roles {OWNER = 'Owner', MEMBER = 'Member', BILLING = 'Billing'}
## Quickstart

```bash
npx parse-server-kit new my-api
npx parse-server-kit new my-api # scaffolds and installs
cd my-api
docker compose up -d # MongoDB as a replica set, so transactions work
npm install
npm run db:up # MongoDB as a replica set, so transactions work
npm run dev
```

Expand All @@ -149,7 +148,7 @@ mandatory tsconfig flags already set. The server prints a ready-to-paste `curl`
on startup:

```
✓ Created my-api — 10 files
✓ Created my-api — 15 files

Your API is running.
Docs http://localhost:1337/api-docs
Expand Down
2 changes: 1 addition & 1 deletion docs/assets/search-index.js

Large diffs are not rendered by default.

2 changes: 1 addition & 1 deletion docs/assets/search-index.json

Large diffs are not rendered by default.

7 changes: 3 additions & 4 deletions docs/guide/cli.html
Original file line number Diff line number Diff line change
Expand Up @@ -96,15 +96,14 @@ <h2 id="commands">Commands</h2>
<tr><td><code>psk --version</code> / <code>--help</code></td><td></td></tr>
</tbody>
</table></div>
<p><code>generate</code> abbreviates to <code>g</code>; <code>-y</code> accepts defaults, <code>-f</code> overwrites existing files. Before installing anything, <code>npx parse-server-kit</code> works in place of <code>psk</code>.</p>
<p><code>generate</code> abbreviates to <code>g</code>; <code>-y</code> accepts defaults, <code>-f</code> overwrites existing files. <code>new</code> installs the generated project's dependencies for you — pass <code>--no-install</code> to skip that, for CI or a different package manager. Before installing anything, <code>npx parse-server-kit</code> works in place of <code>psk</code>.</p>

<h2 id="new">Creating a project</h2>
<pre class="code-block"><code>npx parse-server-kit new my-api
cd my-api
docker compose up -d
npm install
npm run db:up
npm run dev</code></pre>
<p>Ten files, and every one of them removes a trap that is otherwise easy to hit:</p>
<p>Fifteen files, and every one of them removes a trap that is otherwise easy to hit:</p>
<div class="table-wrap"><table>
<thead><tr><th>What it sets</th><th>What that avoids</th></tr></thead>
<tbody>
Expand Down
3 changes: 1 addition & 2 deletions docs/guide/getting-started.html
Original file line number Diff line number Diff line change
Expand Up @@ -103,8 +103,7 @@ <h2 id="create">Create a project</h2>

<pre class="code-block"><code>npx parse-server-kit new my-api
cd my-api
docker compose up -d
npm install
npm run db:up
npm run dev</code></pre>

<p>
Expand Down
3 changes: 1 addition & 2 deletions docs/guide/tutorial-orders.html
Original file line number Diff line number Diff line change
Expand Up @@ -135,8 +135,7 @@ <h2 id="building">What you are building</h2>
<h2 id="setup">1. Set up</h2>
<pre class="code-block"><code>npx parse-server-kit new shop-api
<span class="t-key">cd</span> shop-api
docker compose up -d <span class="t-com"># MongoDB as a replica set - transactions need one</span>
npm install
npm run db:up <span class="t-com"># MongoDB as a replica set - transactions need one</span>
npm run dev</code></pre>
<p>
The replica set matters. Transactions and <code>@ParseVersionField</code> are both
Expand Down
3 changes: 1 addition & 2 deletions docs/guide/tutorial.html
Original file line number Diff line number Diff line change
Expand Up @@ -93,8 +93,7 @@ <h1>Tutorial: build a real API</h1>
<h2 id="setup">1. Start the project</h2>
<pre class="code-block"><code>npx parse-server-kit new tasks-api
<span class="t-key">cd</span> tasks-api
docker compose up -d
npm install
npm run db:up
npm run dev</code></pre>
<p>
You now have a running server with a <code>Note</code> example, docs at
Expand Down
21 changes: 13 additions & 8 deletions package-lock.json

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

5 changes: 1 addition & 4 deletions package.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "parse-server-kit",
"version": "3.0.0",
"version": "3.0.1",
"description": "Decorator-driven toolkit for Parse Server: models, cloud functions, triggers, cron, REST routing, ACL, transactions, optimistic locking and Swagger, from TypeScript decorators.",
"main": "dist/index.js",
"types": "dist/index.d.ts",
Expand Down Expand Up @@ -64,9 +64,6 @@
"swagger-ui-express": ">=4.0.0"
},
"peerDependenciesMeta": {
"@types/parse": {
"optional": true
},
"node-cron": {
"optional": true
},
Expand Down
8 changes: 5 additions & 3 deletions src/cli/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -38,12 +38,13 @@ ${bold('Usage')}
${bold('Options')}
-y, --yes Accept the defaults, ask nothing ${dim('(new)')}
-f, --force Overwrite files that already exist
--no-install Skip installing dependencies ${dim('(new)')}
--ai=<list> Assistants to write for, or ${cyan('none')} ${dim('(new)')}
${dim(AI_TARGETS.map(t => t.id).join(', '))}

${bold('Examples')}
${cyan('npx parse-server-kit new my-api')}
${cyan('cd my-api && docker compose up -d && npm install && npm run dev')}
${cyan('cd my-api && npm run db:up && npm run dev')}

${cyan('psk g resource Product')}
${dim(' → src/models/Product.ts and src/functions/product.ts')}
Expand All @@ -52,7 +53,7 @@ ${bold('Examples')}

${cyan('psk ai claude cursor')}
${dim(' → CLAUDE.md, .claude/skills/, .claude/agents/, .cursor/rules/')}
${dim(' The traps this library fails silently on, in the dialect your tool reads.')}
${dim(' The mistakes Parse Server does not warn you about, in the dialect your tool reads.')}

${cyan('psk new my-api --ai=none -y')}
${dim(' Unattended, no assistant files.')}
Expand Down Expand Up @@ -108,6 +109,7 @@ export async function main(argv: string[]): Promise<number> {
name,
yes: flags.has('--yes') || flags.has('-y'),
force: flags.has('--force') || flags.has('-f'),
skipInstall: flags.has('--no-install'),
kitVersion: kitVersion(),
ai,
});
Expand Down Expand Up @@ -187,7 +189,7 @@ async function runAi(args: string[]): Promise<number> {
}

info();
info(dim(' These describe the mistakes this library fails silently on —'));
info(dim(' These cover the mistakes Parse Server does not warn you about —'));
info(dim(' shadowed fields, decorator order, the implementACL signature.'));
info();

Expand Down
66 changes: 62 additions & 4 deletions src/cli/new.ts
Original file line number Diff line number Diff line change
@@ -1,4 +1,6 @@
import {basename, resolve} from 'node:path';
import {existsSync} from 'node:fs';
import {basename, dirname, join, resolve} from 'node:path';
import {spawnSync} from 'node:child_process';
import {
generateKey,
isUsableTarget,
Expand All @@ -17,6 +19,8 @@ export interface NewCommandOptions {
kitVersion: string;
/** From `--ai=claude,cursor`. `undefined` means ask; `[]` means none. */
ai?: string[];
/** `--no-install`. Skips the dependency install after scaffolding. */
skipInstall?: boolean;
}

/**
Expand Down Expand Up @@ -98,19 +102,23 @@ export async function runNew(options: NewCommandOptions): Promise<number> {
info();
for (const file of ai.written) info(` ${cyan(file)}`);
info();
info(dim(' These describe the mistakes this library fails silently on —'));
info(dim(' These cover the mistakes Parse Server does not warn you about —'));
info(dim(' shadowed fields, decorator order, the implementACL signature.'));
}
for (const file of ai.skipped) {
warn(`${file} ${dim('(exists, left alone — pass --force to replace)')}`);
}

warnIfNested(targetDir, folder);

const installed = options.skipInstall ? false : installDependencies(targetDir);

info();
info(bold(' Next:'));
info();
info(` cd ${folder}`);
info(` docker compose up -d ${dim('# MongoDB (replica set, so transactions work)')}`);
info(' npm install');
info(` npm run db:up ${dim('# MongoDB (replica set, so transactions work)')}`);
if (!installed) info(' npm install');
info(' npm run dev');
info();
info(dim(' The server prints a ready-to-paste curl on startup,'));
Expand All @@ -122,6 +130,56 @@ export async function runNew(options: NewCommandOptions): Promise<number> {
return 0;
}

/**
* Install the generated project's dependencies.
*
* Scaffolding a project that cannot run until the user reads the next line of
* output is a needless step, and every other `create-*` tool in the ecosystem
* does this. `--no-install` opts out, for CI and for anyone on a different
* package manager.
*
* A failure here is reported and then ignored: the project on disk is complete
* and correct either way, and `npm install` is a thing the user can run
* themselves. Returning `false` puts that line back in the next steps.
*/
function installDependencies(targetDir: string): boolean {
info();
info(dim(' Installing dependencies…'));

const result = spawnSync('npm', ['install', '--no-audit', '--no-fund'], {
cwd: targetDir,
stdio: 'ignore',
// npm is a shell script on Windows, so it is not directly executable.
shell: process.platform === 'win32',
});

if (result.status === 0) {
ok('Dependencies installed');
return true;
}

warn('Could not install dependencies automatically — run `npm install` yourself.');
return false;
}

/**
* Say so when the new project lands inside another npm project.
*
* `npm install` in the parent will not install the child, and a `node_modules`
* one level up resolves for imports while being invisible in the project's own
* package.json. Nothing here is broken, but the arrangement is confusing enough
* to be worth one line rather than left to be discovered.
*/
function warnIfNested(targetDir: string, folder: string): void {
const parent = dirname(targetDir);
if (!existsSync(join(parent, 'package.json'))) return;

info();
warn(`${folder} is inside another npm project.`);
info(dim(' It is a separate project with its own package.json and its own'));
info(dim(' dependencies — install and run it from inside the folder.'));
}

/**
* Decide which assistants to write for.
*
Expand Down
20 changes: 18 additions & 2 deletions templates/default/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,8 +5,7 @@ A Parse Server API built with [parse-server-kit](https://www.npmjs.com/package/p
## Run it

```bash
docker compose up -d # MongoDB (replica set, so transactions work)
npm install
npm run db:up # MongoDB (replica set, so transactions work)
npm run dev
```

Expand Down Expand Up @@ -58,6 +57,7 @@ there is nothing to wire.
src/
app.ts boot order — the sequence is load-bearing
seed.ts roles, the first admin, and sample rows
note.test.ts a starting point for tests
models/Note.ts @ParseClass + @ParseField + a @BeforeSave trigger
functions/note.ts @Route + @CloudFunction — the method name is the route
```
Expand Down Expand Up @@ -92,6 +92,22 @@ Both are already set in `tsconfig.json`, and **both fail silently** if removed:
- `useDefineForClassFields: false` — otherwise every `@ParseField` reads as
`undefined` while `.get('field')` still returns the value.

## Tests

```bash
npm test
```

Node's own test runner — nothing to install, no config file. `src/note.test.ts`
checks the things that go wrong without raising an error: that a field written
on a model actually reaches Parse (rather than landing on a shadowed class
field), that `save()` would really send it, and that the rules declared on the
schema are enforced by the trigger.

When you want tests that hit the database, the hard part is already done: the
`docker-compose.yml` here starts a replica set, which is what Parse needs for
transactions.

## Adding a model

1. Create `src/models/Thing.ts` with `@ParseClass` and `@ParseField`.
Expand Down
8 changes: 7 additions & 1 deletion templates/default/package.json.template
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@
"build": "tsc",
"start": "node build/src/app.js",
"dev": "tsc && node build/src/app.js",
"test": "tsc && node --test build/src/",
"seed": "tsc && node build/src/seed.js",
"db:up": "docker compose up -d",
"db:down": "docker compose down"
Expand All @@ -23,6 +24,11 @@
"@types/node": "^20.0.0",
"@types/parse": "^3.0.9",
"typescript": "^5.5.0"
},
"overrides": {
"ws": "^8.21.3",
"follow-redirects": "^1.16.0",
"ip-address": "^10.7.0",
"uuid": "^11.1.1"
}
}

Loading
Loading