@openinc/parse-server-schema

A schema manager for Parse Server

CLI Usage

Repository on npm: https://www.npmjs.com/package/@openinc/parse-server-schema

npm i -g @openinc/parse-server-schema

parse-server-schema --help

# or

npm i -D @openinc/parse-server-schema

npx parse-server-schema --help

Generate local schemas from distant Parse server

parse-server-schema down ./path/to/local/schemas --configPath ./path/to/my-parse-conf.json

Generate TS types from distant Parse server

parse-server-schema typescript ./path/to/my/local/types --configPath ./path/to/my-parse-conf.json

Generate UML class diagrams from local schema/types

The draw command creates a class diagram from local Parse schema files.

Supported input:

• A folder with .json schema files (output from down)
• A folder with .ts files (output from typescript)
• A single .json file containing an array of classes

parse-server-schema draw <inputPath>

CLI options for diagram generation

The draw command supports the following options:

Option	Type	Default	Description
--output <path>	string	auto	Output file path. Defaults to schema-diagram.mmd/.md/.html by format
--format <format>	string	mermaid	Output format: mermaid, markdown, or html
--prefix <prefix>	string	""	Include only classes with this prefix; prefix is stripped in rendered names
--ignore <ignore...>	string[]	[]	Class name(s) to ignore
--font-size <px>	number	44	Mermaid font size in pixels
--default-renderer <renderer>	string	elk	Mermaid class renderer: dagre-wrapper, dagre-d3, or elk

Draw examples

# Create Mermaid source
parse-server-schema draw ./schema --format mermaid

# Create markdown with embedded Mermaid
parse-server-schema draw ./schema --format markdown --output ./docs/schema.md

# Create interactive HTML viewer
parse-server-schema draw ./types --format html --output ./schema-diagram.html

# Filter classes by prefix and ignore selected classes
parse-server-schema draw ./types --prefix OD3_ --ignore _User _Session _Role

# Use a specific Mermaid layout renderer
parse-server-schema draw ./types --format html --default-renderer dagre-wrapper

Configuration

You have two options to connect to parse server.

1. By providing a json config file
2. By providing an env with the necessary values set.

loadConfig(...) checks provided config in the following order:

1. options.operation === "down" ==> Set Config from process.env ==> return:

Config.initialize({
  publicServerURL: PARSE_SERVER_DOWN_SCHEMA_SERVER_URL,
  appId: PARSE_SERVER_DOWN_SCHEMA_APPID,
  masterKey: PARSE_SERVER_DOWN_SCHEMA_MASTERKEY,
});

2. options.operation === "up" ==> Set Config from process.env ==> return:

Config.initialize({
  publicServerURL: PARSE_SERVER_UP_SCHEMA_SERVER_URL,
  appId: PARSE_SERVER_UP_SCHEMA_APPID,
  masterKey: PARSE_SERVER_UP_SCHEMA_MASTERKEY,
});

3. Check for default process.env variable and use these, then return:

Config.initialize({
  publicServerURL: PARSE_SERVER_URL || PARSE_PUBLIC_SERVER_URL,
  appId: PARSE_SERVER_APPLICATION_ID,
  masterKey: PARSE_SERVER_MASTER_KEY,
});

4. Look for parse-server.config.json or provided config path.

1. Config files

By default the config file is expected to be in ./config/parse-server.config.json

You can specify the path providing the option --configPath.

Here's what a valid JSON file looks like:

{
  "masterKey": "my-parse-master-key",
  "publicServerURL": "https://my-parse-server.com",
  "appId": "my-parse-app-id"
}

2. Environment variables

The following variables can be set. By default the package looks for process.env, so takes every .env in cwd into account and uses these information to connect to parse server. The json file is ignored in this scenarion.

• PARSE_SERVER_APPLICATION_ID
• PARSE_SERVER_MASTER_KEY
• PARSE_PUBLIC_SERVER_URL
• PARSE_SERVER_URL

Distinct values for "down" script (optional)

• PARSE_SERVER_DOWN_SCHEMA_SERVER_URL
• PARSE_SERVER_DOWN_SCHEMA_APPID
• PARSE_SERVER_DOWN_SCHEMA_MASTERKEY

Distinct values for "up" script (optional)

• PARSE_SERVER_UP_SCHEMA_SERVER_URL
• PARSE_SERVER_UP_SCHEMA_APPID
• PARSE_SERVER_UP_SCHEMA_MASTERKEY

Providing custom types for class fields

By default array and object typed class fields are set to any[]/any. By specifing --custom-class-field-types-config <path> in the cli command you can set these to custom types. The file has to be an array of form classname --> fields --> [key: fieldname]: type. Specify the importfrom option to import the type correctly!

Example:

[
  {
    "classname": "YourClassName",
    "fields": [
      {
        "fieldname": "fieldtype",
        "importfrom": "import { fieldtype } from \"../path/to/type\""
      }
    ]
  }
]

CLI options for typescript conversion

The typescript command supports the following options:

Option	Type	Default	Description
--prefix <prefix>	string	""	Prefix will be stripped from class names in generated TypeScript files
--ignore <ignore...>	string[]	[]	Class name(s) to ignore during generation. Supports wildcards: Prefix* (starts with) or *Suffix (ends with). Can be specified multiple times
--include <include...>	string[]	[]	Class name(s) to include (overrides --ignore). Supports wildcards with *. Can be specified multiple times
--no-class	boolean	false	Don't create and register custom Parse.Object classes (generates type definitions only)
--no-sdk	boolean	false	Don't use Parse JS SDK dependencies, generates plain TypeScript types only
--import-parse-statement <statement>	string	""	Control the import on top of generated files by yourself. E.g. import Parse from "parse"; when using Parse JS SDK or "" when Parse is globally available (on server).
--is-esm	boolean	false	Use ES module imports/exports with .js extensions in generated files
--resolve-referenced-classes	boolean	false	Generate TypeScript files for all referenced classes, even if they're not in the initial schema (enables recursive dependency resolution)
--custom-class-field-types-config <path>	string	-	Path to JSON config file for custom class field type mappings
--verbose	boolean	false	Enable verbose logging including dependency validation and dependency graph visualization

Examples:

# Basic usage with prefix stripping
parse-server-schema typescript ./types --prefix "MyApp_"

# Generate with ES modules and recursive dependencies
parse-server-schema typescript ./types --is-esm --resolve-referenced-classes

# Generate type definitions only (no Parse.Object classes)
parse-server-schema typescript ./types --no-class --no-sdk

parse-server-schema typescript ./types --prefix XXX_ --import-parse-statement 'import Parse from "parse";'

# Ignore specific classes and use custom field types
parse-server-schema typescript ./types --ignore "_Session" "TempClass*" --custom-class-field-types-config ./custom-types.json

# Enable verbose logging for debugging dependency issues
parse-server-schema typescript ./types --verbose --resolve-referenced-classes

# Generate MyApp_ prefixed classes plus additional Asset classes
parse-server-schema typescript ./types --prefix "MyApp_" --include "Asset*"

# Generate Documentation classes plus specific additional classes
parse-server-schema typescript ./types --prefix "OD3_Documentation_" --include "OD3_Asset" "User"

Version update and deployment to npm

The next version number is calculated by semantic release.

When commiting keep the structure in mind: https://docs.openinc.dev/docs/general/semanticrelease

A GitHub workflow publishes the package automatically to npm.

Programmatic Usage

import {
  loadConfig,
  up,
  down,
  typescript,
  draw,
} from "@openinc/parse-server-schema";

// load JSON file with config
loadConfig("./parse-server-config.json");
// or load config from process.env
loadConfig();
// when using distinct up and down servers
loadConfig(undefined, { operation: "up" });
loadConfig(undefined, { operation: "down" });

await up(schemaPath);

await down(schemaPath);

await typescript(typescriptPath);

await draw(schemaPath, { format: "html", output: "./schema-diagram.html" });