Skip to content

Commit 224f569

Browse files
jotanarcisojotanarciso
authored
feat: utils and types packages (#21)
* feat: types package and utils package * fix: typo and import reference * fix: types * docs: update main doc * fix: hook sufix * docs: create readme * docs: Update types docs * docs: update utils docs * docs: fix name * docs: update README.md * docs: add type metadata * docs: Update README.md
1 parent e57edc6 commit 224f569

21 files changed

+1188
-13
lines changed

‎README.md

+91-2
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,8 @@ These libraries are designed to be versatile and can be used both within and out
1515
- [Utilities](#utilities)
1616
- [Cookies](#cookies)
1717
- [WASM Image Processor](#wasm-image-processor)
18+
- [Utils](#utils)
19+
- [Types](#types)
1820
- [AzionConfig](#config)
1921
- [Contributing](#contributing)
2022

@@ -289,9 +291,96 @@ console.log(imageResponse);
289291

290292
Read more in the [WASM Image Processor README](./packages/wasm-image-processor/README.md).
291293

294+
295+
### Utils
296+
297+
The Utils package provides a set of utility functions that simplify common tasks when working with Azion edge functions.
298+
299+
#### Available Functions
300+
301+
- **`mountSPA(requestURL: RequestURL): Promise<Response>`**
302+
Handles routing for Single-page Applications (SPA) by determining if the incoming request is for a static asset or an application route. It mounts the appropriate request URL for fetching the required resource.
303+
304+
- **`mountMPA(requestURL: RequestURL): Promise<Response>`**
305+
Handles routing for Multi-page Applications (MPA) by determining if the incoming request is for a static asset or an application route. It mounts the appropriate request URL for fetching the required resource.
306+
307+
- **`parseRequest(event: FetchEvent): Promise<ParsedRequest>`**
308+
Parses and logs the details of an incoming request, extracting key information such as headers, cookies, body, and client data. It provides a structured object with these details for further processing or logging.
309+
310+
#### Examples
311+
312+
313+
**JavaScript:**
314+
315+
```javascript
316+
import { mountSPA, mountMPA, parseRequest } from 'azion/utils';
317+
318+
// Handle SPA routing
319+
const myApp1 = await mountSPA('https://example.com/');
320+
console.log(myApp1);
321+
// Fetches: file:///index.html
322+
// Response object representing the content of index.html
323+
324+
// Handle MPA routing
325+
const myApp2 = await mountMPA('https://example.com/about');
326+
console.log(myApp2);
327+
// Fetches: file:///about/index.html
328+
// Response object representing the content of about/index.html
329+
330+
// Parse a request
331+
const parsedRequest = await parseRequest(event);
332+
console.log(parsedRequest);
333+
334+
```
335+
336+
**TypeScript:**
337+
338+
```typescript
339+
import { mountSPA, mountMPA, parseRequest } from 'azion/utils';
340+
import { ParsedRequest } from 'azion/utils/types';
341+
342+
// Handle SPA routing
343+
const myApp1: Response = await mountSPA('https://example.com/');
344+
console.log(myApp1);
345+
// Fetches: file:///index.html
346+
// Response object representing the content of index.html
347+
348+
// Handle MPA routing
349+
const myApp2: Response = await mountMPA('https://example.com/about');
350+
console.log(myApp2);
351+
// Fetches: file:///about/index.html
352+
// Response object representing the content of about/index.html
353+
354+
355+
// Parse a request
356+
const parsedRequest: ParsedRequest = await parseRequest(event);
357+
console.log(parsedRequest);
358+
```
359+
360+
Read more in the [Utils README](./packages/utils/README.md).
361+
362+
## Types
363+
364+
The Types package provides global TypeScript types that are used across Azion platform, ensuring consistency and reducing redundancy throughout the codebase.
365+
366+
⚠️ These types are specifically tailored for `Azion Runtime environments`.
367+
368+
#### Available Types
369+
370+
- **`Metadata`**
371+
Represents metadata information for requests, including GeoIP data, remote address, server protocol, and TLS information.
372+
373+
- **`FetchEvent`**
374+
Represents the FetchEvent interface, which includes the request object and methods to handle fetch events within the Azion Runtime.
375+
376+
- **`FirewallEvent`**
377+
Represents the FirewallEvent interface, including methods to manage firewall events such as denying, dropping, or continuing a request.
378+
379+
Read more in the [Types README](./packages/types/README.md).
380+
292381
## Config
293382

294-
The Config library provides methods to configure and validate options for the Azion platform.
383+
The Config library provides methods to configure and validate options for the Azion.config file.
295384

296385
### Examples
297386

@@ -321,7 +410,7 @@ const config = AzionConfig({
321410
});
322411
```
323412

324-
Read more in the [CONFIG README](./packages/config/README.md).
413+
Read more in the [Azion Config README](./packages/config/README.md).
325414

326415
## Contributing
327416

‎package-lock.json

+10-2
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎package.json

+17-1
Original file line numberDiff line numberDiff line change
@@ -75,6 +75,11 @@
7575
"import": "./packages/client/dist/index.mjs",
7676
"types": "./packages/client/dist/index.d.ts"
7777
},
78+
"./types": {
79+
"require": "./packages/types/dist/index.js",
80+
"import": "./packages/types/dist/index.mjs",
81+
"types": "./packages/types/dist/index.d.ts"
82+
},
7883
"./config": {
7984
"require": "./packages/config/dist/index.js",
8085
"import": "./packages/config/dist/index.mjs",
@@ -114,13 +119,21 @@
114119
"require": "./packages/wasm-image-processor/dist/index.js",
115120
"import": "./packages/wasm-image-processor/dist/index.mjs",
116121
"types": "./packages/wasm-image-processor/dist/index.d.ts"
122+
},
123+
"./utils": {
124+
"require": "./packages/utils/dist/index.js",
125+
"import": "./packages/utils/dist/index.mjs",
126+
"types": "./packages/utils/dist/index.d.ts"
117127
}
118128
},
119129
"typesVersions": {
120130
"*": {
121131
"client": [
122132
"./packages/client/dist/index.d.ts"
123133
],
134+
"types": [
135+
"./packages/types/dist/index.d.ts"
136+
],
124137
"storage": [
125138
"./packages/storage/dist/index.d.ts"
126139
],
@@ -141,7 +154,10 @@
141154
],
142155
"wasm-image-processor": [
143156
"./packages/wasm-image-processor/dist/index.d.ts"
157+
],
158+
"utils": [
159+
"./packages/utils/dist/index.d.ts"
144160
]
145161
}
146162
}
147-
}
163+
}

‎packages/types/README.md

+124
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,124 @@
1+
# Azion Types
2+
3+
The Types package provides global TypeScript types that are used across Azion platform, ensuring consistency and reducing redundancy throughout the codebase.
4+
5+
⚠️ These types are specifically tailored for Azion Runtime environments.
6+
## Table of Contents
7+
8+
- [Installation](#installation)
9+
- [Usage](#usage)
10+
- [Defining Metadata](#defining-metadata)
11+
- [Working with FetchEvent](#working-with-fetchevent)
12+
- [Handling FirewallEvent](#handling-firewallevent)
13+
- [API Reference](#api-reference)
14+
- [`Metadata`](#metadata)
15+
- [`FetchEvent`](#fetchevent)
16+
- [`FirewallEvent`](#firewallevent)
17+
- [Contributing](#contributing)
18+
19+
## Installation
20+
21+
Install the package using npm or yarn:
22+
23+
```sh
24+
npm install azion
25+
```
26+
27+
or
28+
29+
```sh
30+
yarn add azion
31+
```
32+
33+
## Usage
34+
35+
### Defining Metadata
36+
37+
The `Metadata` interface provides a structured way to represent request metadata, including GeoIP information, remote address details, and server/TLS data.
38+
39+
**TypeScript Example:**
40+
41+
```typescript
42+
import { Metadata } from 'azion/types';
43+
44+
const requestMetadata: Metadata = {
45+
geoip_asn: '12345',
46+
geoip_city: 'Sao Paulo',
47+
geoip_city_continent_code: 'SA',
48+
geoip_city_country_code: 'BR',
49+
geoip_city_country_name: 'Brazil',
50+
geoip_continent_code: 'SA',
51+
geoip_country_code: 'BR',
52+
geoip_country_name: 'Brazil',
53+
geoip_region: 'SP',
54+
geoip_region_name: 'Sao Paulo',
55+
remote_addr: '192.0.2.1',
56+
remote_port: '443',
57+
remote_user: 'user',
58+
server_protocol: 'HTTP/1.1',
59+
ssl_cipher: 'ECDHE-RSA-AES128-GCM-SHA256',
60+
ssl_protocol: 'TLSv1.2',
61+
};
62+
```
63+
64+
### Working with FetchEvent
65+
66+
The `FetchEvent` interface extends the standard `Event` interface to include request and metadata properties, providing a complete context for handling fetch operations in the Azion environment.
67+
68+
**TypeScript Example:**
69+
70+
```typescript
71+
import { FetchEvent, Metadata } from 'azion/types';
72+
73+
addEventListener('fetch', (event: FetchEvent) => {
74+
const { request } = event;
75+
const metadata: Metadata = request.metadata;
76+
77+
console.log('Request URL:', request.url);
78+
console.log('Client IP:', metadata.remote_addr);
79+
console.log('GeoIP City:', metadata.geoip_city);
80+
81+
event.respondWith(fetch(request));
82+
});
83+
```
84+
85+
### Handling FirewallEvent
86+
87+
The `FirewallEvent` interface provides additional methods specific to firewall events, allowing for actions like denying requests, dropping connections, or adding headers to requests and responses.
88+
89+
**TypeScript Example:**
90+
91+
```typescript
92+
import { FirewallEvent } from 'azion/types';
93+
94+
addEventListener('firewall', (event: FirewallEvent) => {
95+
const { request } = event;
96+
97+
console.log('Request URL:', request.url);
98+
console.log('GeoIP Country:', request.metadata.geoip_country_name);
99+
100+
if (request.metadata.geoip_country_code === 'CN') {
101+
event.deny();
102+
} else {
103+
event.continue();
104+
}
105+
});
106+
```
107+
108+
## API Reference
109+
110+
### `Metadata`
111+
112+
The `Metadata` interface represents metadata information for requests, including GeoIP data, remote address, server protocol, and TLS information.
113+
114+
### `FetchEvent`
115+
116+
The `FetchEvent` interface extends the standard `Event` interface and includes the request object and methods to handle fetch events within the Azion Runtime.
117+
118+
### `FirewallEvent`
119+
120+
The `FirewallEvent` interface extends the standard `Event` interface and includes methods to manage firewall events, such as denying or continuing requests and manipulating headers.
121+
122+
## Contributing
123+
124+
Feel free to submit issues or pull requests to improve the functionality or documentation.

‎packages/types/package.json

+20
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
{
2+
"name": "@azion/types",
3+
"version": "1.0.0",
4+
"description": "Global types for Azion packages",
5+
"main": "./dist/index.js",
6+
"module": "./dist/index.mjs",
7+
"types": "./dist/index.d.ts",
8+
"scripts": {
9+
"compile": "tsup --config ../../tsup.config.json",
10+
"lint": "eslint .",
11+
"lint:fix": "eslint --fix .",
12+
"prettier": "prettier --write ."
13+
},
14+
"author": "aziontech",
15+
"license": "MIT",
16+
"files": [
17+
"dist",
18+
"package.json"
19+
]
20+
}

0 commit comments

Comments
 (0)