didia / suitescript-types-tools-and-frameworks

SuiteScript 2.0 high level TypeScript types, tools, APIs and frameworks

Miscellaneous SuiteScript 2.0 TypeScript rich types, and high level utilities and APIs

What

• based on SuiteScript 2.0 types from project @hitc/netsuite-types
• Richer types for N/record and N/search so record fields, sublists and search columns, filters, joins, operators are also type-checked and documented in interfaces. (types automatically extracted from NetSuite's record-browser)
• High level utilities and APIs.
• Developer tools for agile development (watch/build/deploy npm run dev) Right now mostly oriented and tested for SuiteLet, but it should work on other script types

Features in detail

• TypedRecord - Record fields and sublists are strongly typed for fieldId and sublistId only of that record type. Example: when you load a 'customer' record setValue() and setSublistValue() calls will validate that fieldId and sublistId belong to record type 'customer. It uses types generated by metadataFromRecordBrowser (auto generated from record browser html pages). It only declare types - it doesn't implement any wrapper around the native objects so it virtually weights 0%. See src/record/typedRecord.
• TypedSearch - Search creation and results are strongly typed against the record type. For example, when you create a search of type: 'item', given columns, filters and join names are validated against that record type ("item"). Also filter operators are validated to be of the filter type supported operators only. It only declare types - it doesn't implement any wrapper around the native objects so it virtually weights 0%. See src/search/typedSearch.
• TDD/spec framework implementation. API similar to jasmine/mocha/jest that runs on NetSuite. Light weigh and simple written from scratch so you can write unit tests for your SuiteScript 2.0 modules like you would do with jasmine/jest/mocha using describe(), expect(), it(). etc and run them on NetSuite. Very basic support and result reported that supports both excecution in NetSuite and node.js.
• TSX/JSX for server side markup render support. Use TSX/JSX to render HTML in the server. Markup using TSX is strongly typed !. Implements JSX.Element and createElement() that render elements to string, very lightweight - no library required. See src/jsx
  • supports indented/minified output style
  • has the entire HTML/CSS DOM type declaration (copied from react - don't worry just types)
  • basic Styles <Style> tools to declare CSS rules and target classNames with type validation
  • supports NetSuite and node.js (pretty agnostic)
  • limited support for function attributes (cannot access the scope at all)
  • Support for custom Component classes (see src/jsc/StatelessComponent)
  • Basic tags for input value binding and data object storage in the DOM (to access data from function attributes since we cannot access the scope)
• app - server-side routes - pages declaration framework. High level API to declare url-parameter based routes that match server side pages to easily implement server-side html apps.
• Logger interface ResponseLogger implementation so is easy to debug when using SuiteLet, RestLet. Global console.log (and imt/timeEnd/error/warn) implemented. See src/log
• Record copy utilities: copyFields, copySublist, copySublists. See src/record/copy
• Commerce related utilities:
  • copyCategory, moveCategory, removeCategory : to copy/move commercecategory to another parent or remove it
  • matrix item utils (to see or find if an item is matrix parent, child, or non )
• Array.prototype.filter polly fill. see src/misc/misc
• search results utilities find/filter/toArray
• file cabinet high level operations like ls, glob, mkdirp, find. See src/file
• more to come...

Other features

• Easy to use devtools to watch, compile and deploy to filecabinet automatically. Support uploading only changed files (local file hash). See npm run devand devtools/dev.
• metadataFromRecordBrowser : tools to extract all record's metadata from online (or offline) record browser pages and generate typescript types. see ./metadataFromRecordBrowser
  • metadataFromRecordBrowser/metadataFromRecordBrowser.js - snippet that can be run on a record browser page to extract record's metadata such as fields, sublists, search columns, filters, joins, etc
  • metadataFromRecordBrowser/extractMetadataFromZip : tool based on puppeteer (headless browser) to navigate throu all record browser' pages and execute metadataFromRecordBrowser.js to extract all record's metadata. For each record it will generate a .json file
  • metadataFromRecordBrowser/tsGenerator will generate TypeScript files with interfaces describing each record metadata, as well as general interfaces describing which interface describe which record type, etc. (these types are consumed then by typedSearch and TypedRecord)

Usage

• npm run build will generate usable SuiteScript 2.0 .files that you can copy to your project and import it (if you are working with pure .js)
• npm run dev to develop:

Usage details:

If you are working with TypeScript, then is better to clone this repository, start your feature in src/ and import the utilities. Just make sure that:

• Configure account, target folder, role, applicationId, etc in ./config.js file (this information is needed to deploy the generated scripts to NetSuite)
• the first time you run it it will ask you for your email / password and this information will be stored in $(HOME)/netsuite_creds.js will:
• make sure all your imports are relative, i.e : import { copySublist } from '../record/copy/copySublist';
• import SuiteScript types like this: import * as record from 'N/record';
• don't make radical changes in tsconfig.json since it needs that particular configuration in order the emitted .js to work
• you will need to create the output folder structure manually in the file cabinet (by default SuiteScript folder) and upload script entry point manually.
• ./src/suitelet-sample1.ts is a SuiteLet entry point example
• ./src/user-event-sample1.ts is a user event entry point example

Limitations

• You need to respect current tsconfig.json
• always import files using exact relative names:
  • Don't use index.ts shortcut, i.e: from "../some/folder/index" will work . from "../some/folder" wont
  • configure your editor to always create/suggest/fix imports as relatives, for example in vscode settings: "Typescript › Preferences: Import Module Specifier. Preferred path style for auto imports. == RELATIVE"
• you can use all ecma syntax features as always as they are supported in es5 and NetSuite back-end. For example, Promises/await/async since NetSuite don't support setTimeout()

TODO

• move dependencies of devtools to its own package.json (gulp-watch, hasha, netsuite-uploader-util)
• more unit test for existing APIs.
• UnitTest should be account agnostics using "preconditions"
• memorize for test preconditions performance.
• upload the entry point .js file at last to prevent errors.
• (for devtools) we could separate tslib.js so emitted files are smaller
• Security: fix credentials storing at $(HOME)/netsuite_creds.js - always ask for password and never save it.
• research: browserify and have a single .js bundle? this would simplify the deploy ? Dont' know
• mode script entry point examples (schedule, restlet, client)
• better UX for users as a library
  • make the project more modular: separate it in several projects - spec, jsx, typedRecord, typedSearch, app, etc so users can import only what they want and not the whole thing.
  • support npm i so users don't have to copy/paste the whole thing.