Skip to content

Commit

Permalink
chore: organize and move to apt-parser-ts
Browse files Browse the repository at this point in the history
  • Loading branch information
tale committed Feb 12, 2023
1 parent b6efd16 commit 07c62a1
Show file tree
Hide file tree
Showing 4 changed files with 103 additions and 77 deletions.
1 change: 1 addition & 0 deletions .npmignore
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
.vscode/
node_modules/
test/
src/
Expand Down
14 changes: 14 additions & 0 deletions .vscode/settings.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
{
"markdownlint.config": {
"default": true,
"MD001": false,
"MD013": {
"line_length": 120
},
"MD033": {
"allowed_elements": [
"br",
]
},
}
}
155 changes: 83 additions & 72 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,13 +1,17 @@
# APT Parser

This library is capable of parsing files used within the [APT Package Manager](https://en.wikipedia.org/wiki/APT_(software)).<br>
A typical APT repository advertises a release file and packages file, both of which use a key-value organization system to declare information. This library is able to parse the data and return it as type-safe objects for usage in JavaScript and TypeScript projects.<br>
A typical APT repository advertises a release file and packages file, utilizing a key-value organization system.
This library is able to parse the data and return it as type-safe objects for usage in JavaScript and TypeScript projects.<br>

### Installation

`npm install --save apt-parser`<br>

### Release Parsing

Here's an example for getting the information out of a Release file:<br>

```ts
import axios from 'axios';
import { Release } from 'apt-parser';
Expand All @@ -21,44 +25,46 @@ console.log(release.get('InvalidKey')); // => null
```

A full Release object has the following properties attached on it, all of which map to documented APT fields.<br>
For more information on the Debian Repository Format, see https://wiki.debian.org/DebianRepository/Format.<br>
For more information on the Debian Repository Format, see <https://wiki.debian.org/DebianRepository/Format.<br>>

```ts
interface IRelease {
architectures: string[] // => Architectures
noSupportForArchitectureAll?: boolean // => No-Support-For-Architecture-All
description?: string // => Description
origin?: string // => Origin
label?: string // => Label
suite: string // => Suite
codename: string // => Codename
version?: string // => Version
date?: Date // => Date
validUntil?: Date // => Valid-Until
components: string[] // => Components
md5?: ReleaseHash[] // => MD5Sum
sha1?: ReleaseHash[] // => SHA1
sha256?: ReleaseHash[] // => SHA256
sha512?: ReleaseHash[] // => SHA512
notAutomatic?: boolean // => NotAutomatic
butAutomaticUpgrades?: boolean // => ButAutomaticUpgrades
acquireByHash?: boolean // => Acquire-By-Hash
signedBy?: string[] // => Signed-By
packagesRequireAuthorization: boolean // => Packages-Require-Authorization

get(key: string): string | undefined // => Retrieve a raw field value not assigned a strict type
get fieldCount(): number // => Get total number of fields in the Release contents
architectures: string[] // => Architectures
noSupportForArchitectureAll?: boolean // => No-Support-For-Architecture-All
description?: string // => Description
origin?: string // => Origin
label?: string // => Label
suite: string // => Suite
codename: string // => Codename
version?: string // => Version
date?: Date // => Date
validUntil?: Date // => Valid-Until
components: string[] // => Components
md5?: ReleaseHash[] // => MD5Sum
sha1?: ReleaseHash[] // => SHA1
sha256?: ReleaseHash[] // => SHA256
sha512?: ReleaseHash[] // => SHA512
notAutomatic?: boolean // => NotAutomatic
butAutomaticUpgrades?: boolean // => ButAutomaticUpgrades
acquireByHash?: boolean // => Acquire-By-Hash
signedBy?: string[] // => Signed-By
packagesRequireAuthorization: boolean // => Packages-Require-Authorization

get(key: string): string | undefined // => Retrieve a raw field value not assigned a strict type
get fieldCount(): number // => Get total number of fields in the Release contents
}

type ReleaseHash = {
filename: string
hash: string
size: number
filename: string
hash: string
size: number
}
```
### Binary Control Parsing
Here's an example for getting the information out of a binary control file:<br>
```ts
import { Release } from 'apt-parser';

Expand All @@ -84,41 +90,43 @@ console.log(control.get('Invalid-Key')); // => null
```

A full BinaryControl object has the following properties attached on it, all of which map to documented APT fields.<br>
For more information on the Debian Control Format, see https://www.debian.org/doc/debian-policy/ch-controlfields.html.<br>
For more information on the Debian Control Format, see <https://www.debian.org/doc/debian-policy/ch-controlfields.html.<br>>

```ts
interface IBinaryControl {
package: string // => Package
source?: string // => Source
version: string // => Version
section?: string // => Section
priority?: PriorityLevel // => Priority
architecture: string // => Architecture
essential?: boolean // => Essential

depends?: string[] // => Depends
preDepends?: string[] // => Pre-Depends
recommends?: string[] // => Recommends
suggests?: string[] // => Suggests
replaces?: string[] // => Replaces
enhances?: string[] // => Enhances
breaks?: string[] // => Breaks
conflicts?: string[] // => Conflicts

installedSize?: number // => Installed-Size
maintainer: string // => Maintainer
description: string // => Description
homepage?: string // => Homepage
builtUsing?: string // => Built-Using
packageType?: PackageType // => Package-Type

get(key: string): string | undefined // => Retrieve a raw field value not assigned a strict type
get fieldCount(): number // => Get total number of fields in the control contents
package: string // => Package
source?: string // => Source
version: string // => Version
section?: string // => Section
priority?: PriorityLevel // => Priority
architecture: string // => Architecture
essential?: boolean // => Essential

depends?: string[] // => Depends
preDepends?: string[] // => Pre-Depends
recommends?: string[] // => Recommends
suggests?: string[] // => Suggests
replaces?: string[] // => Replaces
enhances?: string[] // => Enhances
breaks?: string[] // => Breaks
conflicts?: string[] // => Conflicts

installedSize?: number // => Installed-Size
maintainer: string // => Maintainer
description: string // => Description
homepage?: string // => Homepage
builtUsing?: string // => Built-Using
packageType?: PackageType // => Package-Type

get(key: string): string | undefined // => Retrieve a raw field value not assigned a strict type
get fieldCount(): number // => Get total number of fields in the control contents
}
```

### Packages Parsing

Here's an example for getting the information out of a Packages file:<br>

```ts
import axios from 'axios';
import { Packages } from 'apt-parser';
Expand All @@ -127,44 +135,47 @@ const { data } = await axios.get('https://repo.chariz.com/Packages');
const packages = new Packages(data);

for (const pkg of packages) {
console.log(pkg.package); // Package Identifier
console.log(pkg.get('InvalidKey')); // => null
console.log(pkg.package); // Package Identifier
console.log(pkg.get('InvalidKey')); // => null
}
```

A full Packages object has the following properties attached on it, all of which map to documented APT fields.<br>
For more information on the Debian Repository Format, see https://wiki.debian.org/DebianRepository/Format.<br>
For more information on the Debian Repository Format, see <https://wiki.debian.org/DebianRepository/Format.<br>>

```ts
interface IPackage extends IBinaryControl {
filename: string // => Filename
size: number // => Size
md5?: string // => MD5sum
sha1?: string // => SHA1
sha256?: string // => SHA256
sha512?: string // => SHA512
descriptionMd5?: string // => Description-md5

get(key: string): string | undefined // => Retrieve a raw field value not assigned a strict type
get fieldCount(): number // => Get total number of fields in the package contents
filename: string // => Filename
size: number // => Size
md5?: string // => MD5sum
sha1?: string // => SHA1
sha256?: string // => SHA256
sha512?: string // => SHA512
descriptionMd5?: string // => Description-md5

get(key: string): string | undefined // => Retrieve a raw field value not assigned a strict type
get fieldCount(): number // => Get total number of fields in the package contents
}

interface IPackages extends Array<IPackage> {
constructor(rawData: string) // Pass in the raw contents of the file
constructor(rawData: string) // Pass in the raw contents of the file
}
```

### Skipping Validation
The parser validates required fields based on the parameters defined by the Debian Team on their documentation pages. Disabling this validation is possible, but it is not recommended if you are parsing valid repositories.

Disabling this validation will stop the APT parser from throwing any `MissingRequiredKeyError`s. It is disabled through an option when constructing your parser.
The parser validates required fields based on the parameters defined by the Debian Team on their documentation pages.
Disabling this validation is possible, but it is not recommended if you are parsing valid repositories.

Disabling this validation will stop the APT parser from throwing any `MissingRequiredKeyError`s.
It is disabled through an option when constructing your parser.

```ts
import axios from 'axios';
import { Packages } from 'apt-parser';

const { data } = await axios.get('https://repo.chariz.com/Packages');
const packages = new Packages(data, {
skipValidation: true
skipValidation: true
});
```
10 changes: 5 additions & 5 deletions package.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "apt-parser",
"version": "1.4.5",
"version": "1.5.0",
"description": "Parse APT's key-value files and retrieve all the values as a Map",
"author": "Canister <support@canister.me> (https://canister.me)",
"contributors": [
Expand All @@ -20,7 +20,7 @@
"scripts": {
"build": "tsup ./src/index.ts --format cjs,esm --dts --clean",
"prepublishOnly": "pnpm run build",
"push": "np",
"push": "np --message 'chore: v%s'",
"test": "vitest run"
},
"keywords": [
Expand All @@ -36,12 +36,12 @@
],
"repository": {
"type": "git",
"url": "git+https://github.com/cnstr/apt-parser.git"
"url": "git+https://github.com/cnstr/apt-parser-ts.git"
},
"bugs": {
"url": "https://github.com/cnstr/apt-parser/issues"
"url": "https://github.com/cnstr/apt-parser-ts/issues"
},
"homepage": "https://github.com/cnstr/apt-parser#readme",
"homepage": "https://github.com/cnstr/apt-parser-ts#readme",
"devDependencies": {
"np": "^7.6.2",
"tsup": "^6.2.3",
Expand Down

0 comments on commit 07c62a1

Please sign in to comment.