Typescript conversion

DEVELOPING.md

@@ -0,0 +1,138 @@
+# Developing arc.js
+
+This guide covers working with the TypeScript codebase for arc.js.
+
+## Quick Start
+
+```bash
+npm install          # Install dependencies
+npm run build        # Build all outputs
+npm test             # Run TypeScript tests
+npm run test:all     # Run all tests (TypeScript + build validation)
+```
+
+## Project Structure
+
+```
+src/
+├── index.ts         # Main entry point
+├── coord.ts         # Coordinate class
+├── arc.ts           # Arc class  
+├── great-circle.ts  # Great circle calculations
+├── line-string.ts   # Internal geometry helper
+├── utils.ts         # Utility functions
+└── types.ts         # TypeScript type definitions
+
+test/
+├── *.test.ts        # Jest TypeScript tests (source code)
+└── build-output.test.js  # Build validation (compiled output)
+```
+
+## Development Workflow
+
+### Testing Locally
+
+```bash
+# Run TypeScript tests (fast, for development)
+npm test
+
+# Run build validation (slower, tests compiled output)
+npm run test:build
+
+# Run everything (recommended before committing)
+npm run test:all
+
+# Watch mode for development
+npm run test:watch
+```
+
+### Building
+
+```bash
+npm run build
+```
+
+This generates:
+- `dist/` - CommonJS output with `.d.ts` files
+- `dist/esm/` - ES modules output  
+- `arc.js` - Browser bundle (UMD format)
+
+## Publishing
+
+### Development Process
+
+1. **Create PR**: Submit changes via pull request
+2. **Code review**: Wait for maintainer approval
+3. **Merge**: Maintainer merges approved changes
+4. **Publishing**: Maintainer handles npm publishing
+
+### Pre-publish Checklist (for maintainers)
+
+1. **Tests pass**: `npm run test:all`
+2. **Build succeeds**: `npm run build`
+3. **Version updated**: Update `package.json` version
+4. **Changelog updated**: Document changes
+5. **PR approved**: All changes reviewed and merged
+
+### Publishing Process (maintainers only)
+
+```bash
+npm run build        # Builds automatically on prepublishOnly
+npm publish
+```
+
+The `prepublishOnly` script ensures a fresh build before publishing.
+
+### What Gets Published
+
+- `dist/` folder (compiled JS + TypeScript definitions)
+- `arc.js` browser bundle
+- `README.md`, `LICENSE.md`, `CHANGELOG.md`
+
+## TypeScript Development
+
+### TypeScript Configuration
+
+- **Source**: Modern TypeScript with strict settings
+- **Output**: ES2022 for broad compatibility
+- **Paths**: `@/` alias maps to `src/` in tests
+- **Declarations**: Full `.d.ts` generation for consumers
+### Adding New Types
+
+1. Add interfaces/types to `src/types.ts`. You can see that it makes use of some GeoJSON types, but in the future it may want to use more of them.
+2. Export public types from `src/index.ts`
+3. Import types with `import type { ... }`
+4. Add tests in relevant `test/*.test.ts` files including typescript.test.ts
+
+## Usage & Module Formats
+
+The package supports multiple import styles:
+
+```javascript
+// CommonJS (Node.js)
+const { GreatCircle } = require('arc');
+
+// ES Modules  
+import { GreatCircle } from 'arc';
+
+// Browser (UMD bundle)
+<script src="arc.js"></script>
+```
+
+All formats are tested in `test/build-output.test.js`.
+
+## Common Tasks
+
+```bash
+# Clean build artifacts
+npm run clean
+
+# Development with auto-rebuild
+npm run test:watch
+
+# Coverage report
+npm run test:coverage
+
+# Check types only (no tests)
+npx tsc --noEmit
+```

README.md

@@ -1,5 +1,5 @@
 # arc.js
-> Calculate great circles routes as lines in GeoJSON or WKT format.
+> Calculate great circle routes as lines in GeoJSON or WKT format.
 
 Algorithms from https://edwilliams.org/avform.htm#Intermediate
 
@@ -18,18 +18,51 @@ BSD
 
 ## Usage
 
-Require the library in node.js like:
+### Node.js (CommonJS)
+For Node.js projects using CommonJS modules:
 ```js
 var arc = require('arc');
+var gc = new arc.GreatCircle({x: -122, y: 48}, {x: -77, y: 39});
 ```
 
-Use in the browser like:
+### Node.js (ES Modules)
+For Node.js projects using ES modules:
+```js
+import * as arc from 'arc';
+const gc = new arc.GreatCircle({x: -122, y: 48}, {x: -77, y: 39});
+```
+
+### TypeScript
+Full TypeScript support with type definitions:
+```typescript
+import { GreatCircle, Coord, Arc, CoordinatePoint } from 'arc';
+
+const start: CoordinatePoint = { x: -122, y: 48 };
+const end: CoordinatePoint = { x: -77, y: 39 };
+const gc = new GreatCircle(start, end);
+```
+
+### Browser
+For direct browser usage (creates global `arc` object):
 ```html
 <script src="./arc.js"></script>
+<script>
+  var gc = new arc.GreatCircle({x: -122, y: 48}, {x: -77, y: 39});
+</script>
+```
+
+### Bundlers (Webpack, Rollup, etc.)
+Works with all modern bundlers:
+```js
+import { GreatCircle } from 'arc';
+// or
+const { GreatCircle } = require('arc');
 ```
 
 ## API
 
+### JavaScript Examples
+
 **1)** Create start and end coordinates
 
 First we need to declare where the arc should start and end
@@ -54,7 +87,42 @@ var generator = new arc.GreatCircle(start, end, {'name': 'Seattle to DC'});
 Then call the `Arc` function on the `GreatCircle` object to generate a line:
 
 ```js
-var line = generator.Arc(100,{offset:10});
+var line = generator.Arc(100, {offset: 10});
+```
+
+### TypeScript Examples
+
+**1)** Import types and create coordinates
+
+```typescript
+import { GreatCircle, CoordinatePoint, ArcOptions } from 'arc';
+
+const start: CoordinatePoint = { x: -122, y: 48 };
+const end: CoordinatePoint = { x: -77, y: 39 };
+```
+
+**2)** Create GreatCircle with typed properties
+
+```typescript
+interface RouteProperties {
+  name: string;
+  color?: string;
+  distance?: number;
+}
+
+const properties: RouteProperties = { name: 'Seattle to DC', color: 'blue' };
+const generator = new GreatCircle(start, end, properties);
+```
+
+**3)** Generate arc with typed options
+
+```typescript
+const options: ArcOptions = { offset: 10 };
+const line = generator.Arc(100, options);
+
+// TypeScript knows the return type is Arc
+const geojson = line.json(); // Returns GeoJSONFeature
+const wkt = line.wkt();      // Returns string
 ```
 
 The `line` will be a raw sequence of the start and end coordinates plus an arc of
@@ -105,4 +173,17 @@ Or to WKT (Well known text):
 'LINESTRING(-122 48,-112.061619 47.724167,-102.384043 46.608131,-93.227188 44.716217,-84.748239 42.144155,-77 38.999999)'
 ```
 
+## TypeScript
+
+```typescript
+import { GreatCircle, CoordinatePoint } from 'arc';
+
+const start: CoordinatePoint = { x: -122, y: 48 };
+const end: CoordinatePoint = { x: -77, y: 39 };
+const gc = new GreatCircle(start, end);
+```
+
+Available types: `CoordinatePoint`, `ArcOptions`, `Coord`, `GreatCircle`, `Arc`, `GeoJSONFeature`
+```
+
 It is then up to you to add up these features to create fully fledged geodata. See the examples/ directory for sample code to create a GeoJSON feature collection from multiple routes.