refactor!: Replace boolean --preserve-names option with enum --identfier-names including a legacy option for replicating <3.0.0 behaviour

.nsprc

@@ -1,2 +1,8 @@
 {
+  "1096460": {
+    "active": true,
+    "notes": "No fixed version of 'ip' package exists",
+    "expiry": "2024-03-01"
+  }
 }
+

package.json

@@ -13,13 +13,17 @@
     "audit": "better-npm-audit audit",
     "dev": "run-s dev:*",
     "dev:helloworld": "tsx src/dev.ts generate -a ./examples/helloworld/application.json -o ./examples/helloworld/client.generated.ts",
-    "dev:helloworld-pn": "tsx src/dev.ts generate -a ./examples/helloworld/application.json -o ./examples/helloworld/client.pn.generated.ts -pn",
+    "dev:helloworld-pn": "tsx src/dev.ts generate -a ./examples/helloworld/application.json -o ./examples/helloworld/client.pn.generated.ts -in preserve",
+    "dev:helloworld-lg": "tsx src/dev.ts generate -a ./examples/helloworld/application.json -o ./examples/helloworld/client.lg.generated.ts -in legacy",
     "dev:lifecycle": "tsx src/dev.ts generate -a ./examples/lifecycle/application.json -o ./examples/lifecycle/client.generated.ts",
-    "dev:lifecycle-pn": "tsx src/dev.ts generate -a ./examples/lifecycle/application.json -o ./examples/lifecycle/client.pn.generated.ts -pn",
+    "dev:lifecycle-pn": "tsx src/dev.ts generate -a ./examples/lifecycle/application.json -o ./examples/lifecycle/client.pn.generated.ts -in preserve",
+    "dev:lifecycle-lg": "tsx src/dev.ts generate -a ./examples/lifecycle/application.json -o ./examples/lifecycle/client.lg.generated.ts -in legacy",
     "dev:state": "tsx src/dev.ts generate -a ./examples/state/application.json -o ./examples/state/client.generated.ts",
-    "dev:state-pn": "tsx src/dev.ts generate -a ./examples/state/application.json -o ./examples/state/client.pn.generated.ts -pn",
+    "dev:state-pn": "tsx src/dev.ts generate -a ./examples/state/application.json -o ./examples/state/client.pn.generated.ts -in preserve",
+    "dev:state-lg": "tsx src/dev.ts generate -a ./examples/state/application.json -o ./examples/state/client.lg.generated.ts -in legacy",
     "dev:voting": "tsx src/dev.ts generate -a ./examples/voting/application.json -o ./examples/voting/client.generated.ts",
-    "dev:voting-pn": "tsx src/dev.ts generate -a ./examples/voting/application.json -o ./examples/voting/client.pn.generated.ts -pn",
+    "dev:voting-pn": "tsx src/dev.ts generate -a ./examples/voting/application.json -o ./examples/voting/client.pn.generated.ts -in preserve",
+    "dev:voting-lg": "tsx src/dev.ts generate -a ./examples/voting/application.json -o ./examples/voting/client.lg.generated.ts -in legacy",
     "build": "run-s build:*",
     "build:0-clean": "rimraf dist coverage",
     "build:1-schema-to-types": "cd src/schema && json2ts application.schema.json > application.d.ts",
@@ -46,9 +50,6 @@
   },
   "author": "Algorand Foundation",
   "license": "MIT",
-  "overrides": {
-    "semver": "7.5.2"
-  },
   "dependencies": {
     "@algorandfoundation/algokit-utils": "^5.4.0",
     "algosdk": "^2.7.0",

src/cli.ts

@@ -1,9 +1,10 @@
-import { Command } from 'commander'
+import { Command, Option } from 'commander'
 import { loadApplicationJson } from './schema/load'
 import * as path from 'path'
 import { generate } from './client/generate'
 import { writeDocumentPartsToStream } from './output/writer'
 import { colorConsole } from './util/color-console'
+import { IdentifierNaming } from './util/sanitization'
 
 export function cli(workingDirectory: string, args: string[]) {
   const program = new Command()
@@ -12,17 +13,32 @@ export function cli(workingDirectory: string, args: string[]) {
     .description('Generates a TypeScript client for the given application.json file')
     .requiredOption('-a --application <path>', 'Specifies the application.json file')
     .requiredOption('-o --output <path>', 'Specifies the output file path')
-    .option('-pn --preserve-names', 'Preserve names from application.json spec instead of sanitizing them')
+    .addOption(
+      new Option(
+        '-in --identifier-names <name>',
+        'Specifies a strategy for sanitizing identifier names read from the application.json' + ' spec.',
+      )
+        .choices([IdentifierNaming.JavaScript, IdentifierNaming.Preserve, IdentifierNaming.Legacy])
+        .default('js'),
+    )
     .action(
-      async ({ application, output, preserveNames }: { application: string; output: string; preserveNames?: boolean }): Promise<void> => {
+      async ({
+        application,
+        output,
+        identifierNames,
+      }: {
+        application: string
+        output: string
+        identifierNames: IdentifierNaming
+      }): Promise<void> => {
         const fs = await import('fs')
         const resolvedAppJsonPath = path.resolve(workingDirectory, application)
         const resolvedOutPath = path.resolve(workingDirectory, output)
         const resolvedOutDir = path.dirname(resolvedOutPath)
         colorConsole.info`Reading application.json file from path ${resolvedAppJsonPath}`
         const spec = await loadApplicationJson(resolvedAppJsonPath)
         colorConsole.info`Generating TS client for ${spec.contract.name}`
-        const parts = generate(spec, { preserveNames: Boolean(preserveNames) })
+        const parts = generate(spec, { identifierNames: identifierNames })
         if (!fs.existsSync(resolvedOutDir)) {
           colorConsole.warn`Output directory ${resolvedOutDir} does not exist and will be created.`
           fs.mkdirSync(resolvedOutDir, { recursive: true })

src/client/generate.ts

@@ -8,8 +8,9 @@ import { imports } from './imports'
 import { createGeneratorContext, GeneratorOptions } from './generator-context'
 import { appTypes } from './app-types'
 import { callComposerType } from './call-composer-types'
+import { IdentifierNaming } from '../util/sanitization'
 
-export function* generate(app: AlgoAppSpec, options: GeneratorOptions = { preserveNames: false }): DocumentParts {
+export function* generate(app: AlgoAppSpec, options: GeneratorOptions = { identifierNames: IdentifierNaming.JavaScript }): DocumentParts {
   const ctx = createGeneratorContext(app, options)
   yield `/* eslint-disable */`
   yield `/**`

src/client/generator-context.ts

@@ -1,6 +1,6 @@
 import { AlgoAppSpec } from '../schema/application'
 import { CallConfigSummary, getCallConfigSummary } from './helpers/get-call-config-summary'
-import { getSanitizer, Sanitizer } from '../util/sanitization'
+import { getSanitizer, IdentifierNaming, Sanitizer } from '../util/sanitization'
 import * as algokit from '@algorandfoundation/algokit-utils'
 
 export type GeneratorContext = {
@@ -12,7 +12,7 @@ export type GeneratorContext = {
 }
 
 export type GeneratorOptions = {
-  preserveNames: boolean
+  identifierNames: IdentifierNaming
 }
 
 export const createGeneratorContext = (app: AlgoAppSpec, options: GeneratorOptions) => {

src/util/sanitization.ts

@@ -14,6 +14,25 @@ export interface Sanitizer {
   isSafeVariableIdentifier(value: string): boolean
 }
 
+export enum IdentifierNaming {
+  /*
+  Convert identifiers to match js style guides.
+  i.e. camelCase vars and props, PascalCase types
+   */
+  JavaScript = 'js',
+  /*
+  Preserve the original values from the application.json whenever
+  possible. Type names may need to be sanitised if they contain invalid chars
+   */
+  Preserve = 'preserve',
+  /*
+  Matches the casing used in version < 3 of the client generator.
+
+  Js naming for most identifiers, but original case for state values.
+   */
+  Legacy = 'legacy',
+}
+
 const defaultSanitiser: Sanitizer = {
   makeSafePropertyIdentifier(value: string) {
     return camelCase(replaceInvalidWithUnderscore(value))
@@ -38,6 +57,13 @@ const defaultSanitiser: Sanitizer = {
   },
 }
 
+const legacySanitiser: Sanitizer = {
+  ...defaultSanitiser,
+  makeSafePropertyIdentifier(value: string) {
+    return this.isSafeVariableIdentifier(value) ? value : `"${escapeQuotes(value)}"`
+  },
+}
+
 const preservingSanitiser: Sanitizer = {
   isSafeVariableIdentifier(value: string): boolean {
     return /^[a-z$_][a-z0-9_$]*$/i.test(value)
@@ -62,4 +88,13 @@ const preservingSanitiser: Sanitizer = {
   },
 }
 
-export const getSanitizer = ({ preserveNames }: { preserveNames: boolean }) => (preserveNames ? preservingSanitiser : defaultSanitiser)
+export const getSanitizer = ({ identifierNames }: { identifierNames: IdentifierNaming }) => {
+  switch (identifierNames) {
+    case IdentifierNaming.Preserve:
+      return preservingSanitiser
+    case IdentifierNaming.Legacy:
+      return legacySanitiser
+    case IdentifierNaming.JavaScript:
+      return defaultSanitiser
+  }
+}