Skip to content
Omnio-js
Esc
↑↓navigate↵open⌘Jpreview
On this page

Object keys

Reference for OmnioKey parsing and object key constraints.

Constraints

An object key must contain at least one character and satisfy these limits.

Constraint Value
Maximum characters 1024
Maximum UTF-8 bytes 1024
Minimum characters 1
Characters Any valid UTF-8 string.

An empty string, an overlong key, or invalid UTF-8 throws InvalidOmnioKeyError.

import { OmnioKey } from "@omniojs/core";

OmnioKey.check("notes/a.txt"); // true
OmnioKey.check(""); // false

Creating an OmnioKey

import { OmnioKey } from "@omniojs/core";

const key = new OmnioKey("photos/2026/sunset.jpg");
const same = OmnioKey.parse("photos/2026/sunset.jpg");

Both new OmnioKey() and OmnioKey.parse() validate the input. OmnioKey.check() validates without creating an instance.

Every Omnio method accepts a string or an OmnioKey. A string is parsed with OmnioKey.parse() internally.

Properties

key

const key = OmnioKey.parse("photos/2026/sunset.jpg");

key.key; // "photos/2026/sunset.jpg"

The full key string.

segments

key.segments; // ["photos", "2026", "sunset.jpg"]

The slash-separated segments. The array always has at least one element, and the returned array is a copy.

prefix

key.prefix; // "photos/2026/"

OmnioKey.parse("root").prefix; // ""

Everything except the last segment.

basename

key.basename; // "sunset.jpg"

The last segment.

filename

OmnioKey.parse("archive.tar.gz").filename; // "archive.tar"
OmnioKey.parse(".hidden").filename; // ".hidden"
OmnioKey.parse("Makefile").filename; // "Makefile"

The basename without its extension. A leading-dot hidden file is treated as having no extension.

extname

OmnioKey.parse("archive.tar.gz").extname; // ".gz"
OmnioKey.parse(".hidden").extname; // ""

The extension from the last dot, including the dot.

String conversion

const key = OmnioKey.parse("notes/a.txt");

String(key); // "notes/a.txt"
JSON.stringify(key); // "\"notes/a.txt\""

toString() and toJSON() return the key string.

Designing keys

Keys determine listing order. listObjects sorts by key, so putting a date or category first makes the order predictable.

photos/2026/01/sunset.jpg
photos/2026/02/beach.jpg
notes/2026-01-15/meeting.md

When logic depends on key structure, use prefix and extname instead of manual string manipulation.

Next steps

Was this page helpful?