doc: update doc

Author: huydo862003

dbml-homepage/docs/js-module/core.md

@@ -25,11 +25,13 @@ npm install @dbml/core
 const { importer } = require('@dbml/core');
 ```
 
-#### `importer.import(str, format)`
+#### `importer.import(str, format[, options])`
 
 * **Arguments:**
   * ```{string} str```
   * ```{'mysql'|'mysqlLegacy'|'postgres'|'postgresLegacy'|'dbml'|'schemarb'|'mssql'|'mssqlLegacy'|'snowflake'|'json'|'oracle'} format```
+  * ```{ImportOptions} options``` *(optional)*
+    * `includeRecords` `{boolean}` — whether to include `Records` blocks in the output DBML. Defaults to `true`.
 
 * **Returns:**
   * ```{string} DBML```
@@ -85,11 +87,14 @@ const dbml = importer.generateDbml(schemaJson);
 const { exporter } = require('@dbml/core');
 ```
 
-#### `exporter.export(str, format)`
+#### `exporter.export(str, format[, options])`
 
 * **Arguments:**
   * ```{string} str```
-  * ```{'mysql'|'postgres'|'oracle'|'dbml'|'schemarb'|'mssql'|'json'} format```
+  * ```{'mysql'|'postgres'|'oracle'|'dbml'|'mssql'|'json'} format```
+  * ```{ExportOptions} options``` *(optional)*
+    * `includeRecords` `{boolean}` — whether to include `Records` blocks in the DBML output. Defaults to `true`. Only applies to the `dbml` format.
+    * `isNormalized` `{boolean}` — whether the model is already normalized. Defaults to `true`. Only applies to the `json` format.
 
 * **Returns:**
   * ```{string} SQL```
@@ -154,12 +159,18 @@ const database = parser.parse(dbml, 'dbml');
 const { ModelExporter } = require('@dbml/core');
 ```
 
-#### `ModelExporter.export(model, format, isNormalized)`
+#### `ModelExporter.export(model, format[, options])`
 
 * **Arguments:**
-  * ```{model} Database```
-  * ```{'mysql'|'postgres'|'oracle'|'dbml'|'schemarb'|'mssql'|'json'} format```
-  * ```{boolean} isNormalized```
+  * ```{Database|NormalizedModel} model```
+  * ```{'mysql'|'postgres'|'oracle'|'dbml'|'mssql'|'json'} format```
+  * ```{ExportOptions} options``` *(optional)*
+    * `includeRecords` `{boolean}` — whether to include `Records` blocks in the DBML output. Defaults to `true`. Only applies to the `dbml` format.
+    * `isNormalized` `{boolean}` — whether the passed model is already normalized. Defaults to `true`. Only applies to the `json` format.
+
+:::note
+Passing a boolean as the third argument is deprecated. Use `ExportOptions` instead.
+:::
 
 * **Returns:** specified format string
 
@@ -177,7 +188,5 @@ const parser = new Parser();
 const database = parser.parse(dbml, 'dbml');
 
 // Export Database object to PostgreSQL
-const postgreSQL = ModelExporter.export(database, 'postgres', false);
-// or
-const postgreSQL = ModelExporter.export(database.normalize(), 'postgres');
+const postgreSQL = ModelExporter.export(database, 'postgres');
 ```

packages/dbml-core/src/export/DbmlExporter.ts

@@ -6,19 +6,11 @@ import type { NormalizedModel, RecordValue } from '../../types/model_structure/d
 import type { NormalizedTable } from '../../types/model_structure/table';
 import type { NormalizedTableGroup } from '../../types/model_structure/tableGroup';
 
-export interface DbmlExporterFlags {
-  /** When false, TableData (Records) blocks are omitted from the output. Defaults to true. */
+export interface DbmlExporterOptions {
+  /** When false, Records blocks are omitted from the output. Defaults to true. */
   includeRecords: boolean;
 }
 
-
-interface TableContent {
-  tableId: number;
-  fieldContents: string[];
-  checkContents: string[];
-  indexContents: string[];
-}
-
 class DbmlExporter {
   static hasWhiteSpace (str: string): boolean {
     return /\s/g.test(str);
@@ -202,7 +194,12 @@ class DbmlExporter {
     return lines;
   }
 
-  static getTableContentArr (tableIds: number[], model: NormalizedModel): TableContent[] {
+  static getTableContentArr (tableIds: number[], model: NormalizedModel): {
+    tableId: number;
+    fieldContents: string[];
+    checkContents: string[];
+    indexContents: string[];
+  }[] {
     const tableContentArr = tableIds.map((tableId) => {
       const fieldContents = DbmlExporter.getFieldLines(tableId, model);
       const checkContents = DbmlExporter.getCheckLines(tableId, model);
@@ -411,10 +408,10 @@ class DbmlExporter {
     return recordStrs.join('\n');
   }
 
-  static export (model: NormalizedModel, flags: DbmlExporterFlags): string {
+  static export (model: NormalizedModel, options: DbmlExporterOptions): string {
     const elementStrs: string[] = [];
     const database = model.database['1'];
-    const { includeRecords } = flags;
+    const { includeRecords } = options;
 
     database.schemaIds.forEach((schemaId) => {
       const {

packages/dbml-core/src/export/JsonExporter.ts

@@ -1,14 +1,14 @@
 import Database from '../model_structure/database';
 import type { NormalizedModel } from '../../types/model_structure/database';
 
-export interface JsonExporterFlags {
+export interface JsonExporterOptions {
   /** When false, the model is exported via its `.export()` method before stringifying. Defaults to true. */
   isNormalized: boolean;
 }
 
 class JsonExporter {
-  static export (model: Database | NormalizedModel, flags: JsonExporterFlags): string {
-    const { isNormalized } = flags;
+  static export (model: Database | NormalizedModel, options: JsonExporterOptions): string {
+    const { isNormalized } = options;
 
     if (!isNormalized && model instanceof Database) {
       return JSON.stringify(model.export(), null, 2);

packages/dbml-core/src/export/ModelExporter.ts

@@ -6,36 +6,36 @@ import SqlServerExporter from './SqlServerExporter';
 import OracleExporter from './OracleExporter';
 import Database from '../model_structure/database';
 import type { NormalizedModel } from '../../types/model_structure/database';
-import { ExportFlags, ExportFormatOption, normalizeExportFlags } from './index';
+import { ExportOptions, ExportFormat, normalizeExportOptions } from './index';
 
 class ModelExporter {
   /**
-   * @deprecated Passing a boolean as the third argument is deprecated. Use `ExportFlags` instead.
+   * @deprecated Passing a boolean as the third argument is deprecated. Use `ExportOptions` instead.
    */
   static export (
     model: Database | NormalizedModel,
-    format: ExportFormatOption,
-    flags: boolean,
+    format: ExportFormat,
+    options: boolean,
   ): string;
 
   static export (
     model: Database | NormalizedModel,
-    format: ExportFormatOption,
-    flags?: ExportFlags,
+    format: ExportFormat,
+    options?: ExportOptions,
   ): string;
 
   static export (
     model: Database | NormalizedModel,
-    format: ExportFormatOption,
-    flags: ExportFlags | boolean = {
+    format: ExportFormat,
+    options: ExportOptions | boolean = {
       isNormalized: true,
       includeRecords: true,
     },
   ): string {
     const {
       isNormalized,
       includeRecords,
-    } = normalizeExportFlags(flags);
+    } = normalizeExportOptions(options);
 
     const normalizedModel: NormalizedModel = model instanceof Database
       ? model.normalize()

packages/dbml-core/src/export/index.ts

@@ -1,60 +1,60 @@
 import ModelExporter from './ModelExporter';
 import Parser from '../parse/Parser';
-import { DbmlExporterFlags } from '../types';
-import { JsonExporterFlags } from './JsonExporter';
+import { DbmlExporterOptions } from './DbmlExporter';
+import { JsonExporterOptions } from './JsonExporter';
 
-export type ExportFormatOption = 'dbml' | 'mysql' | 'postgres' | 'json' | 'mssql' | 'oracle';
+export type ExportFormat = 'dbml' | 'mysql' | 'postgres' | 'json' | 'mssql' | 'oracle';
 
-export type ExportFlags =
-  Partial<DbmlExporterFlags> &
-  Partial<JsonExporterFlags>;
+export type ExportOptions =
+  Partial<DbmlExporterOptions> &
+  Partial<JsonExporterOptions>;
 
 /**
- * @deprecated Passing a boolean as the third argument is deprecated. Use `ExportFlags` instead.
+ * @deprecated Passing a boolean as the third argument is deprecated. Use `ExportOptions` instead.
  */
 function _export (
   str: string,
-  format: ExportFormatOption,
-  flags: boolean,
+  format: ExportFormat,
+  options: boolean,
 ): string;
 
 function _export (
   str: string,
-  format: ExportFormatOption,
-  flags?: ExportFlags,
+  format: ExportFormat,
+  options?: ExportOptions,
 ): string;
 
 function _export (
   str: string,
-  format: ExportFormatOption,
-  flags: ExportFlags | boolean = {
+  format: ExportFormat,
+  options: ExportOptions | boolean = {
     isNormalized: true,
     includeRecords: true
   },
 ): string {
-  const resolvedFlags = normalizeExportFlags(flags);
+  const resolvedFlags = normalizeExportOptions(options);
   const database = (new Parser()).parse(str, 'dbmlv2');
   return ModelExporter.export(database.normalize(), format, resolvedFlags);
 }
 
-export function normalizeExportFlags (
-  flags: ExportFlags | boolean = {},
-): Required<ExportFlags> {
-  if (typeof flags === 'boolean') {
+export function normalizeExportOptions (
+  options: ExportOptions | boolean = {},
+): Required<ExportOptions> {
+  if (typeof options === 'boolean') {
     return {
-      isNormalized: flags,
+      isNormalized: options,
       includeRecords: true,
     };
   }
 
   const {
     isNormalized = true,
     includeRecords = true,
-  } = flags;
+  } = options;
 
   return {
-    isNormalized: isNormalized,
-    includeRecords: includeRecords,
+    isNormalized,
+    includeRecords,
   };
 }
 

packages/dbml-core/src/import/index.ts

@@ -1,21 +1,21 @@
 import { generateDatabase } from '../parse/databaseGenerator';
 import Parser from '../parse/Parser';
 import ModelExporter from '../export/ModelExporter';
-import { DbmlExporterFlags } from 'export/DbmlExporter';
+import { DbmlExporterOptions } from 'export/DbmlExporter';
 
-export type ImportFormatOption = 'dbml' | 'mysql' | 'postgres' | 'json' | 'mssql' | 'postgresLegacy' | 'mssqlLegacy' | 'oracle';
+export type ImportFormat = 'dbml' | 'mysql' | 'postgres' | 'json' | 'mssql' | 'postgresLegacy' | 'mssqlLegacy' | 'schemarb' | 'snowflake' | 'oracle';
 
-export type ImportFlags = Partial<DbmlExporterFlags>;
+export type ImportOptions = Partial<DbmlExporterOptions>;
 
 function _import (
   str: string,
-  format: ImportFormatOption,
-  flags: ImportFlags = {
+  format: ImportFormat,
+  options: ImportOptions = {
     includeRecords: true,
   },
 ): string {
   const database = (new Parser()).parse(str, format);
-  const dbml = ModelExporter.export(database.normalize(), 'dbml', normalizeImportFlags(flags));
+  const dbml = ModelExporter.export(database.normalize(), 'dbml', normalizeImportOptions(options));
 
   return dbml;
 }
@@ -27,12 +27,12 @@ function generateDbml (schemaJson: unknown): string {
   return dbml;
 }
 
-export function normalizeImportFlags(
-  flags: ImportFlags,
-): Required<ImportFlags> {
+export function normalizeImportOptions(
+  options: ImportOptions,
+): Required<ImportOptions> {
   const {
     includeRecords = true,
-  } = flags;
+  } = options;
 
   return {
     includeRecords,

packages/dbml-core/types/export/DbmlExporter.d.ts

@@ -2,7 +2,7 @@ import type { NormalizedModel } from '../model_structure/database';
 import type { NormalizedTable } from '../model_structure/table';
 import type { NormalizedTableGroup } from '../model_structure/tableGroup';
 
-export interface DbmlExporterFlags {
+export interface DbmlExporterOptions {
     /** When false, TableData (Records) blocks are omitted from the output. Defaults to true. */
     includeRecords: boolean;
 }
@@ -24,7 +24,7 @@ declare class DbmlExporter {
     static exportTableGroups(tableGroupIds: number[], model: NormalizedModel): string;
     static exportStickyNotes(model: NormalizedModel): string;
     static exportRecords(model: NormalizedModel): string;
-    static export(model: NormalizedModel, flags: DbmlExporterFlags): string;
+    static export(model: NormalizedModel, flags: DbmlExporterOptions): string;
 }
 
 export default DbmlExporter;

packages/dbml-core/types/export/JsonExporter.d.ts

@@ -1,13 +1,13 @@
 import type Database from '../model_structure/database';
 import type { NormalizedModel } from '../model_structure/database';
 
-export interface JsonExporterFlags {
+export interface JsonExporterOptions {
     /** When false, the model is exported via its `.export()` method before stringifying. Defaults to true. */
     isNormalized: boolean;
 }
 
 declare class JsonExporter {
-    static export(model: Database | NormalizedModel, flags: JsonExporterFlags): string;
+    static export(model: Database | NormalizedModel, flags: JsonExporterOptions): string;
 }
 
 export default JsonExporter;

packages/dbml-core/types/export/ModelExporter.d.ts

@@ -1,13 +1,13 @@
 import type Database from '../model_structure/database';
 import type { NormalizedModel } from '../model_structure/database';
-import type { ExportFormatOption, ExportFlags } from './index';
+import type { ExportFormat, ExportOptions } from './index';
 
 declare class ModelExporter {
     /**
-     * @deprecated Passing a boolean as the third argument is deprecated. Use `ExportFlags` instead.
+     * @deprecated Passing a boolean as the third argument is deprecated. Use `ExportOptions` instead.
      */
-    static export(model: Database | NormalizedModel, format: ExportFormatOption, flags: boolean): string;
-    static export(model: Database | NormalizedModel, format: ExportFormatOption, flags?: ExportFlags): string;
+    static export(model: Database | NormalizedModel, format: ExportFormat, flags: boolean): string;
+    static export(model: Database | NormalizedModel, format: ExportFormat, flags?: ExportOptions): string;
 }
 
 export default ModelExporter;

packages/dbml-core/types/export/index.d.ts

@@ -1,14 +1,17 @@
-import type { DbmlExporterFlags } from './DbmlExporter';
-import type { JsonExporterFlags } from './JsonExporter';
+import type { DbmlExporterOptions } from './DbmlExporter';
+import type { JsonExporterOptions } from './JsonExporter';
 
-export type ExportFormatOption = 'dbml' | 'mysql' | 'postgres' | 'json' | 'mssql' | 'oracle';
+export type ExportFormat = 'dbml' | 'mysql' | 'postgres' | 'json' | 'mssql' | 'oracle';
 
-export type ExportFlags =
-  Partial<DbmlExporterFlags> &
-  Partial<JsonExporterFlags>;
+export type ExportOptions =
+  Partial<DbmlExporterOptions> &
+  Partial<JsonExporterOptions>;
 
-declare function _export(str: string, format: ExportFormatOption, flags: boolean): string;
-declare function _export(str: string, format: ExportFormatOption, flags?: ExportFlags): string;
+export declare function normalizeExportOptions(flags: ExportOptions | boolean): Required<ExportOptions>;
+export declare function normalizeExportOptions(flags?: ExportOptions | boolean): Required<ExportOptions>;
+
+declare function _export(str: string, format: ExportFormat, flags: boolean): string;
+declare function _export(str: string, format: ExportFormat, flags?: ExportOptions): string;
 
 declare const _default: {
     export: typeof _export;