{"id":37216189,"url":"https://github.com/monadicstack/filestore","last_synced_at":"2026-01-15T00:59:50.494Z","repository":{"id":61622988,"uuid":"530750461","full_name":"monadicstack/filestore","owner":"monadicstack","description":"A facade that simplifies interaction with multiple types of file systems.","archived":false,"fork":false,"pushed_at":"2022-09-06T20:10:00.000Z","size":14,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2024-06-20T05:19:55.205Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/monadicstack.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2022-08-30T16:59:54.000Z","updated_at":"2024-06-20T05:19:55.206Z","dependencies_parsed_at":"2022-10-19T18:45:21.653Z","dependency_job_id":null,"html_url":"https://github.com/monadicstack/filestore","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/monadicstack/filestore","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/monadicstack%2Ffilestore","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/monadicstack%2Ffilestore/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/monadicstack%2Ffilestore/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/monadicstack%2Ffilestore/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/monadicstack","download_url":"https://codeload.github.com/monadicstack/filestore/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/monadicstack%2Ffilestore/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28441003,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-15T00:55:22.719Z","status":"ssl_error","status_checked_at":"2026-01-15T00:55:20.945Z","response_time":107,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-01-15T00:59:49.931Z","updated_at":"2026-01-15T00:59:50.481Z","avatar_url":"https://github.com/monadicstack.png","language":"Go","readme":"# `filestore`\n\nThe `filestore` package provides a facade that encapsulates\nthe common operations of a readable/writable file system. This could\nbe the actual underlying disk, an in-memory store, S3, whatever.\n\nCurrently, this package only ships with an implementation that\nuses the underlying disk file system. Over time, I might offer\nmore options through plugins, but disk is all I needed when I wrote\nit, so that's what's available :)\n\n### WARNING\n\nThis is absolutely a work in progress, and I am VERY likely\nto completely change the interfaces as I use it in \"real\" projects\nand realize my abstractions could use some work. Should you\nstumble upon this and want to use it, go for it. I would, however,\nsuggest that you version lock to a specific version as I'm quite\nlikely to check in breaking changes to meet my own needs until\nI feel good about the API.\n\n## Getting Started\n\n```bash\ngo get -u github.com/monadicstack/filestore\n```\n\n## Basic Usage\n\nYou can create a `filestore.FS` that utilizes your local\ndisk, and all of the operations are implicitly based in that location.\nFrom there, you have most of the standard file system operations\nyou would have on the Unix command line:\n\n```go\nfs := filestore.Disk(\"data\")\n```\n\n### List Files in a Directory\n\nYour `fs` is already tied to the data/ directory, so if\nyou wanted to list its contents, you would just do the following:\n```go\nfiles, err := fs.List(\".\")\nif err != nil {\n    // handle error\n}\nfor _, file := range files {\n    fmt.Printf(\"%s [Dir=%v]\\n\", file.Name(), file.IsDir())\n}\n```\n\nAdditionally, you could list the contents of any child directory\nwithin data/ by specifying the path. For instance, to list the\ncontents of data/images/logos/ it would look like this:\n\n```go\nfiles, err := fs.List(\"images/logos\")\n```\n\nLastly, you can filter results down to just those that meet\nspecific criteria. The `filestore` package ships with a few\ncommon filters for things like file name pattern or extension, but\nyou can provide any function that matches the filter signature:\n\n```go\npngFiles, err := fs.List(\"images/logos\", filestore.WithExt(\"png\"))\n```\n\n### Reading/Writing Files\n\nThe `filestore` package makes it easy to read/write files in\nthe underlying file system. Let's say you wanted to read the\nfile data/images/logos/splash-256.png, here's what that would\nlook like. Notice, that the `filestore.ReaderFile` returned by `Read()`\nimplements `io.Reader`, so you can use it with any of Go's standard\nstream processing operations:\n\n```go\nfile, err := fs.Read(\"images/logos/splash-256.png\")\nif err != nil {\n\t// handle error\n}\ndefer file.Close()\n\nimg, err := png.Decode(file)\n```\n\nWriting files is just as idiomatic. The `Write()` operation returns\na `filestore.WriterFile` which implements `io.Writer`, so you can\nhook into your favorite stream processing code.\n\n```go\n// If the data/conf/ directory doesn't exist, Write() will\n// lazily create it on the fly for you!!!\nfile, err := fs.Write(\"conf/config.json\")\nif err != nil {\n    // handle error\n}\ndefer file.Close()\n\nfile.Write([]byte(`{\"timeout\":\"10s\"}`))\n```\n\n### Other Handy Operations\n\nThe idea this package is to give you most of the same tools/behaviors\nthat you'd have on the command line. \n\nDelete a single file or even a whole directory and everything in it...\n```go\n// Single file\nerr := fs.Remove(\"conf/config.json\")\n// Whole directory\nerr := fs.Remove(\"tmp/uploads\")\n```\n\nMove a file or directory \n\n```go\n// Single file\nerr := fs.Move(\"uploads/tmp/upload.png\", \"images/logos/splash-256.png\")\n// Whole directory\nerr := fs.Move(\"uploads/processing\", \"uploads/done\")\n```\n\nGet a `filestore.FS` that is scoped to a subdirectory...\n\n```go\nlogos := fs.ChangeDirectory(\"images/logos\")\nlogoFiles, err := logos.List(\".\", filestore.WithExts(\"png\", \"jpg\"))\n\n// Prints \"data/images/logos\"\nfmt.Println(logos.WorkingDirectory())\n```\nCheck if a file exists or not...\n\n```go\nif fs.Exists(\"conf/config.json\") {\n    // Do something interesting\n}\n```\n\nGet name/size/type/etc. details about a file w/o reading it.\n\n```go\ninfo, err := fs.Stat(\"conf/config.json\")\nfmt.Printf(\"%s [Size=%d][Dir=%v]\\n\", info.Name(), info.Size(), info.IsDir())\n```\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmonadicstack%2Ffilestore","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmonadicstack%2Ffilestore","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmonadicstack%2Ffilestore/lists"}