lazyid


Namelazyid JSON
Version 2.1.0 PyPI version JSON
download
home_pageNone
SummaryMinimal 16-character URL-safe unique ID generator based on a millisecond timestamp and cryptographically secure random bits.
upload_time2025-10-14 08:33:04
maintainerNone
docs_urlNone
authorNone
requires_python>=3.7
licenseMIT
keywords id unique-id short-id uuid identifier base36 timestamp url-safe lazyid python
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            # LazyId

[](https://www.npmjs.com/package/lazyid)
[](https://www.google.com/search?q=LICENSE)

Minimal 16-character URL-safe unique ID generator based on a millisecond timestamp and cryptographically secure random bits.

## Overview

LazyId is a lightweight library for generating and parsing 16-character, URL-safe unique identifiers. Each ID consists of two parts: a time component derived from a millisecond timestamp (UTC) and a cryptographically secure random component, which are then encoded using **Base36** (`0-9`, `a-z`).

No external dependencies. Available for JavaScript, TypeScript, and Python.

-----

## Features

  - **Compact**: Generates 16-character IDs using a URL-safe Base36 alphabet.
  - **Timestamp-Based**: The first 8 characters are derived from a millisecond timestamp (since the Unix epoch, UTC).
  - **Cryptographic Random**: The last 8 characters are derived from secure random data.
  - **Cross-Platform**: Available for JavaScript, TypeScript, and Python with identical output.
  - **Reversible**: Extract the original millisecond timestamp from any ID.
  - **No Dependencies**: Uses only standard libraries.
  - **Practically Collision-Free**: Safe for use at a massive scale.

-----

## Installation

### JavaScript

Install via npm:

```bash
npm install lazyid
```

### TypeScript

Install via npm (scoped package):

```bash
npm install lazyid
```

### Python

Install via pip:

```bash
pip install lazyid
```

-----

## Usage

### JavaScript

```javascript
// CommonJS
const lazyid = require("lazyid");

// ES Modules
import lazyid from "lazyid";

// Generate a new ID
let id = lazyid(); 
// -> Example: 'k2vtbmo2j5ah57z1'

// Extract the timestamp from an ID
let timestamp = lazyid(id);
// -> Example: 1728494747234 (this is an integer millisecond timestamp)
```

### TypeScript

```typescript
import lazyid from "lazyid";

// Generate a new ID
const id: string = lazyid();
// -> Example: 'k2vtbmo2j5ah57z1'

// Extract the timestamp from an ID
const timestamp: number = lazyid(id);
// -> Example: 1728494747234 (this is an integer millisecond timestamp)
```

### Python

```python
from lazyid import lazyid

# Generate a new ID
new_id = lazyid()
# -> Example: 'k2vtbmo2j5ah57z1'

# Extract the timestamp from an ID
timestamp = lazyid(new_id)
# -> Example: 1728494747234 (this is an integer millisecond timestamp)
```

-----

## API Reference

### `lazyid([id])`

  - **Generate**: Call with no arguments to create a new LazyId string.
  - **Parse**: Call with an ID string to extract the original `integer` millisecond timestamp.

**Parameters:**
  - `id` (string, optional): If provided, extract timestamp from this ID string.

**Returns:**

  - **JavaScript**: `string` (on generate) or `number` (on parse).
  - **TypeScript**: `string` (on generate) or `number` (on parse) with full type safety.
  - **Python**: `str` (on generate) or `int` (on parse).

**Throws:** Throws an error if the input string is invalid.

-----

## Structure of a LazyId

  - **Total Length**: 16 characters.
  - **Encoding**: Base36 (`0123456789abcdefghijklmnopqrstuvwxyz`).
  - **Composition**: The ID is formed from the combination of two numerical components, encoded into Base36:
    1.  **Time Component (First 8 characters)**: Derived from the current millisecond timestamp (`Date.now() % 36**8`).
    2.  **Random Component (Last 8 characters)**: Derived from cryptographically secure random bytes (`crypto.randomBytes` in JS/TS, `os.urandom` in Python).

-----

## Notes

  - **Timezone**: All timestamps are processed in UTC.
  - **Random Quality**: Uses cryptographic-grade random generators (`crypto.randomBytes` in JS/TS, `os.urandom` in Python) with no fallback.
  - **Interoperability**: IDs generated in any language can be correctly parsed in any other supported language.

-----

## Collision Resistance

By combining a time component with millisecond precision and a random component with **\~2.8 trillion** (`36^8`) possibilities, LazyId collisions are practically impossible, even in distributed systems generating thousands of IDs per millisecond. It is safe for use as database primary keys, URL slugs, filenames, or event IDs.

-----

## Contributing

Contributions are welcome\! Please submit issues or pull requests to the GitHub repository.

1.  Fork the repository.
2.  Create a feature branch (`git checkout -b feature/your-feature`).
3.  Commit your changes (`git commit -m 'Add your feature'`).
4.  Push to the branch (`git push origin feature/your-feature`).
5.  Open a Pull Request.

-----

## Issues

Report bugs or request features at [https://github.com/niefdev/lazyid/issues](https://github.com/niefdev/lazyid/issues).

-----

## License

MIT © [niefdev](https://github.com/niefdev)

-----

## Author

Developed by **niefdev**

## Repository

Source code: [https://github.com/niefdev/lazyid](https://github.com/niefdev/lazyid)

## Homepage

Learn more: [https://github.com/niefdev/lazyid\#readme](https://github.com/niefdev/lazyid#readme)

            

Raw data

            {
    "_id": null,
    "home_page": null,
    "name": "lazyid",
    "maintainer": null,
    "docs_url": null,
    "requires_python": ">=3.7",
    "maintainer_email": "niefdev <niefdev@gmail.com>",
    "keywords": "id, unique-id, short-id, uuid, identifier, base36, timestamp, url-safe, lazyid, python",
    "author": null,
    "author_email": "niefdev <niefdev@gmail.com>",
    "download_url": "https://files.pythonhosted.org/packages/43/0f/d95054cfc84b9c561088634b954dccb642cd19a687a5e199cd1fea6bb98f/lazyid-2.1.0.tar.gz",
    "platform": null,
    "description": "# LazyId\n\n[](https://www.npmjs.com/package/lazyid)\n[](https://www.google.com/search?q=LICENSE)\n\nMinimal 16-character URL-safe unique ID generator based on a millisecond timestamp and cryptographically secure random bits.\n\n## Overview\n\nLazyId is a lightweight library for generating and parsing 16-character, URL-safe unique identifiers. Each ID consists of two parts: a time component derived from a millisecond timestamp (UTC) and a cryptographically secure random component, which are then encoded using **Base36** (`0-9`, `a-z`).\n\nNo external dependencies. Available for JavaScript, TypeScript, and Python.\n\n-----\n\n## Features\n\n  - **Compact**: Generates 16-character IDs using a URL-safe Base36 alphabet.\n  - **Timestamp-Based**: The first 8 characters are derived from a millisecond timestamp (since the Unix epoch, UTC).\n  - **Cryptographic Random**: The last 8 characters are derived from secure random data.\n  - **Cross-Platform**: Available for JavaScript, TypeScript, and Python with identical output.\n  - **Reversible**: Extract the original millisecond timestamp from any ID.\n  - **No Dependencies**: Uses only standard libraries.\n  - **Practically Collision-Free**: Safe for use at a massive scale.\n\n-----\n\n## Installation\n\n### JavaScript\n\nInstall via npm:\n\n```bash\nnpm install lazyid\n```\n\n### TypeScript\n\nInstall via npm (scoped package):\n\n```bash\nnpm install lazyid\n```\n\n### Python\n\nInstall via pip:\n\n```bash\npip install lazyid\n```\n\n-----\n\n## Usage\n\n### JavaScript\n\n```javascript\n// CommonJS\nconst lazyid = require(\"lazyid\");\n\n// ES Modules\nimport lazyid from \"lazyid\";\n\n// Generate a new ID\nlet id = lazyid(); \n// -> Example: 'k2vtbmo2j5ah57z1'\n\n// Extract the timestamp from an ID\nlet timestamp = lazyid(id);\n// -> Example: 1728494747234 (this is an integer millisecond timestamp)\n```\n\n### TypeScript\n\n```typescript\nimport lazyid from \"lazyid\";\n\n// Generate a new ID\nconst id: string = lazyid();\n// -> Example: 'k2vtbmo2j5ah57z1'\n\n// Extract the timestamp from an ID\nconst timestamp: number = lazyid(id);\n// -> Example: 1728494747234 (this is an integer millisecond timestamp)\n```\n\n### Python\n\n```python\nfrom lazyid import lazyid\n\n# Generate a new ID\nnew_id = lazyid()\n# -> Example: 'k2vtbmo2j5ah57z1'\n\n# Extract the timestamp from an ID\ntimestamp = lazyid(new_id)\n# -> Example: 1728494747234 (this is an integer millisecond timestamp)\n```\n\n-----\n\n## API Reference\n\n### `lazyid([id])`\n\n  - **Generate**: Call with no arguments to create a new LazyId string.\n  - **Parse**: Call with an ID string to extract the original `integer` millisecond timestamp.\n\n**Parameters:**\n  - `id` (string, optional): If provided, extract timestamp from this ID string.\n\n**Returns:**\n\n  - **JavaScript**: `string` (on generate) or `number` (on parse).\n  - **TypeScript**: `string` (on generate) or `number` (on parse) with full type safety.\n  - **Python**: `str` (on generate) or `int` (on parse).\n\n**Throws:** Throws an error if the input string is invalid.\n\n-----\n\n## Structure of a LazyId\n\n  - **Total Length**: 16 characters.\n  - **Encoding**: Base36 (`0123456789abcdefghijklmnopqrstuvwxyz`).\n  - **Composition**: The ID is formed from the combination of two numerical components, encoded into Base36:\n    1.  **Time Component (First 8 characters)**: Derived from the current millisecond timestamp (`Date.now() % 36**8`).\n    2.  **Random Component (Last 8 characters)**: Derived from cryptographically secure random bytes (`crypto.randomBytes` in JS/TS, `os.urandom` in Python).\n\n-----\n\n## Notes\n\n  - **Timezone**: All timestamps are processed in UTC.\n  - **Random Quality**: Uses cryptographic-grade random generators (`crypto.randomBytes` in JS/TS, `os.urandom` in Python) with no fallback.\n  - **Interoperability**: IDs generated in any language can be correctly parsed in any other supported language.\n\n-----\n\n## Collision Resistance\n\nBy combining a time component with millisecond precision and a random component with **\\~2.8 trillion** (`36^8`) possibilities, LazyId collisions are practically impossible, even in distributed systems generating thousands of IDs per millisecond. It is safe for use as database primary keys, URL slugs, filenames, or event IDs.\n\n-----\n\n## Contributing\n\nContributions are welcome\\! Please submit issues or pull requests to the GitHub repository.\n\n1.  Fork the repository.\n2.  Create a feature branch (`git checkout -b feature/your-feature`).\n3.  Commit your changes (`git commit -m 'Add your feature'`).\n4.  Push to the branch (`git push origin feature/your-feature`).\n5.  Open a Pull Request.\n\n-----\n\n## Issues\n\nReport bugs or request features at [https://github.com/niefdev/lazyid/issues](https://github.com/niefdev/lazyid/issues).\n\n-----\n\n## License\n\nMIT \u00a9 [niefdev](https://github.com/niefdev)\n\n-----\n\n## Author\n\nDeveloped by **niefdev**\n\n## Repository\n\nSource code: [https://github.com/niefdev/lazyid](https://github.com/niefdev/lazyid)\n\n## Homepage\n\nLearn more: [https://github.com/niefdev/lazyid\\#readme](https://github.com/niefdev/lazyid#readme)\n",
    "bugtrack_url": null,
    "license": "MIT",
    "summary": "Minimal 16-character URL-safe unique ID generator based on a millisecond timestamp and cryptographically secure random bits.",
    "version": "2.1.0",
    "project_urls": {
        "Documentation": "https://github.com/niefdev/lazyid#readme",
        "Homepage": "https://github.com/niefdev/lazyid",
        "Issues": "https://github.com/niefdev/lazyid/issues",
        "Repository": "https://github.com/niefdev/lazyid.git"
    },
    "split_keywords": [
        "id",
        " unique-id",
        " short-id",
        " uuid",
        " identifier",
        " base36",
        " timestamp",
        " url-safe",
        " lazyid",
        " python"
    ],
    "urls": [
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "edd63a0f70a10edd49995888607a9d46d8cc5d609291ab8b36c792663c21d60f",
                "md5": "a1de5753af9e801ee685961c7eef21c3",
                "sha256": "c7a8a3970f0c26ad3fe18055c37e95a722df29a4b04a18e744854a745addfdf3"
            },
            "downloads": -1,
            "filename": "lazyid-2.1.0-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "a1de5753af9e801ee685961c7eef21c3",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.7",
            "size": 3782,
            "upload_time": "2025-10-14T08:33:03",
            "upload_time_iso_8601": "2025-10-14T08:33:03.033232Z",
            "url": "https://files.pythonhosted.org/packages/ed/d6/3a0f70a10edd49995888607a9d46d8cc5d609291ab8b36c792663c21d60f/lazyid-2.1.0-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "430fd95054cfc84b9c561088634b954dccb642cd19a687a5e199cd1fea6bb98f",
                "md5": "f928d50dd960c817697182010f5aad2e",
                "sha256": "042b9a4bd1fa04adfdf4cd87acba4e38a00eca54f160ad938759cb8b51ed7664"
            },
            "downloads": -1,
            "filename": "lazyid-2.1.0.tar.gz",
            "has_sig": false,
            "md5_digest": "f928d50dd960c817697182010f5aad2e",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.7",
            "size": 3945,
            "upload_time": "2025-10-14T08:33:04",
            "upload_time_iso_8601": "2025-10-14T08:33:04.324030Z",
            "url": "https://files.pythonhosted.org/packages/43/0f/d95054cfc84b9c561088634b954dccb642cd19a687a5e199cd1fea6bb98f/lazyid-2.1.0.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2025-10-14 08:33:04",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "niefdev",
    "github_project": "lazyid#readme",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": false,
    "lcname": "lazyid"
}
        
Elapsed time: 2.79736s